Biến môi trường & runtimeConfig

Mọi khoá runtimeConfig mà @tasco/nuxt-layer-base khai báo, kèm biến môi trường ghi đè, giá trị mặc định và nơi đọc. Cách chọn giá trị cho từng môi trường: Cấu hình & biến môi trường.

Quy tắc

• Tên biến = NUXT_ + đường dẫn khoá viết hoa, các cấp nối bằng _, camelCase tách thành từ: auth.endpoints.userInfo → NUXT_AUTH_ENDPOINTS_USER_INFO, public.apiBaseURL → NUXT_PUBLIC_API_BASE_URL.
• Chỉ khoá có trong bảng mới nhận giá trị từ env. Biến NUXT_* không khớp khoá nào thì không có tác dụng.
• Kiểu giá trị: Nuxt parse chuỗi env — true/false thành boolean, chuỗi số thành number.
• Đổi lúc chạy: server đọc env khi khởi động, không cần build lại. Khác với app.config.ts — xem app.config › tasco.
• public.* xuống trình duyệt: không bao giờ đặt bí mật dưới public.

Bắt buộc

Biến	Khi nào	Thiếu thì
NUXT_SESSION_SECRET	Production	Route chạm phiên trả 500 Session secret chưa cấu hình. Đặt NUXT_SESSION_SECRET (>= 32 ký tự). Dev thì dùng khoá tạm và in cảnh báo
NUXT_AUTH_BASE_URL	Không bật NUXT_AUTH_MOCK	Đăng nhập trả 500 auth.baseURL chưa cấu hình (NUXT_AUTH_BASE_URL).
NUXT_API_PROXY_TARGET	App gọi /api/**	Mọi lời gọi /api/** trả 500 apiProxyTarget chưa cấu hình.

Server

Chỉ code chạy trên server (route Nitro) đọc được: useRuntimeConfig(event).

Phiên và proxy

Khoá	Biến môi trường	Kiểu	Mặc định	Đọc ở
session.secret	NUXT_SESSION_SECRET	string	''	Mã hoá và ký cookie tasco_session (AES-256-GCM). Tạo: openssl rand -base64 32
apiProxyTarget	NUXT_API_PROXY_TARGET	string	''	Đích chuyển tiếp của /api/** — xem Route BFF

IAM — endpoint

Đường dẫn tương đối, nối sau auth.baseURL. Để rỗng endpoint nào thì tính năng tương ứng tắt.

Khoá	Biến môi trường	Mặc định	Dùng cho
auth.baseURL	NUXT_AUTH_BASE_URL	''	Base URL cổng IAM, bọc cả /iam và /auth, vd https://iam.example.com/cop
auth.endpoints.login	NUXT_AUTH_ENDPOINTS_LOGIN	/auth/auth/login-v1	POST đổi tài khoản lấy token
auth.endpoints.userInfo	NUXT_AUTH_ENDPOINTS_USER_INFO	/iam/user/userInfo	POST, header authorization: <token> không có tiền tố Bearer
auth.endpoints.clients	NUXT_AUTH_ENDPOINTS_CLIENTS	/iam/client/findAll?status=1	GET danh sách ứng dụng cho dropdown; rỗng → /auth/clients trả mảng rỗng
auth.endpoints.otpSend	NUXT_AUTH_ENDPOINTS_OTP_SEND	/auth/auth/login/request	POST gửi OTP Telegram; rỗng → /auth/otp/send trả 400

IAM — bóc dữ liệu từ response

Giá trị là dot-path tính từ gốc JSON của response IAM.

Khoá	Biến môi trường	Mặc định	Lấy ra
auth.mapping.token	NUXT_AUTH_MAPPING_TOKEN	body.tokenData.access_token	Access token (bắt buộc có, thiếu thì đăng nhập lỗi)
auth.mapping.refresh	NUXT_AUTH_MAPPING_REFRESH	body.tokenData.refresh_token	Refresh token — đọc được nhưng không lưu vào cookie
auth.mapping.expiresIn	NUXT_AUTH_MAPPING_EXPIRES_IN	body.tokenData.expires_in	Số giây token còn sống (số hoặc chuỗi số)
auth.mapping.id	NUXT_AUTH_MAPPING_ID	body.userId	AuthUser.id
auth.mapping.name	NUXT_AUTH_MAPPING_NAME	body.fullName	AuthUser.name
auth.mapping.email	NUXT_AUTH_MAPPING_EMAIL	body.email	AuthUser.email
auth.mapping.roles	NUXT_AUTH_MAPPING_ROLES	body.listRole	Mảng role
auth.mapping.permissions	NUXT_AUTH_MAPPING_PERMISSIONS	body.authorization	Mảng quyền
auth.mapping.roleKey	NUXT_AUTH_MAPPING_ROLE_KEY	code	Field làm mã role khi phần tử là object
auth.mapping.permissionKey	NUXT_AUTH_MAPPING_PERMISSION_KEY	uri	Field làm mã quyền khi phần tử là object
auth.mapping.permissionType	NUXT_AUTH_MAPPING_PERMISSION_TYPE	web	Chỉ giữ quyền có type này; rỗng → không lọc
auth.mapping.permissionTypeKey	NUXT_AUTH_MAPPING_PERMISSION_TYPE_KEY	type	Tên field chứa type

IAM — mã phương thức OTP

Khoá	Biến môi trường	Mặc định	Ý nghĩa
auth.authenMethod.google	NUXT_AUTH_AUTHEN_METHOD_GOOGLE	1	Mã authenMethod gửi IAM khi người dùng chọn Google Authenticator (đã xác nhận với IAM)
auth.authenMethod.telegram	NUXT_AUTH_AUTHEN_METHOD_TELEGRAM	2	Mã cho OTP Telegram — giá trị giả định, đối chiếu lại với IAM của dự án

Phương thức không có trong bảng thì BFF gửi mã 1.

Dev

Khoá	Biến môi trường	Mặc định	Ý nghĩa
auth.mock	NUXT_AUTH_MOCK	false	Bỏ qua IAM: /auth/login nhận mọi tài khoản, trả người dùng giả — chỉ dùng ở dev. Xem Chạy dev không có IAM

Public

Client đọc được: useRuntimeConfig().public. Nằm trong HTML gửi xuống trình duyệt.

Khoá	Biến môi trường	Kiểu	Mặc định	Đọc ở
public.apiBaseURL	NUXT_PUBLIC_API_BASE_URL	string	/api	Tiền tố của useApi
public.auth.methods	NUXT_PUBLIC_AUTH_METHODS	string	google,telegram	Phương thức OTP trên TascoLoginForm, ngăn cách bằng dấu phẩy; rỗng → ẩn ô OTP
public.auth.showClientSelect	NUXT_PUBLIC_AUTH_SHOW_CLIENT_SELECT	boolean	true	Hiện dropdown "Chọn ứng dụng"
public.auth.defaultClientCode	NUXT_PUBLIC_AUTH_DEFAULT_CLIENT_CODE	string	''	Cố định một ứng dụng khi ẩn dropdown
public.auth.superRoles	NUXT_PUBLIC_AUTH_SUPER_ROLES	string	''	Role bỏ qua mọi kiểm tra quyền, ngăn cách bằng dấu phẩy — dùng ở usePermission, v-can, <Can>

Props của TascoLoginForm (methods, show-client-select, default-client-code) thắng giá trị public.auth.*.

Biến ngoài runtimeConfig

Không đi qua runtimeConfig nên không theo quy tắc NUXT_*.

Biến	Đọc ở	Ghi chú
AI_GATEWAY_URL, AI_GATEWAY_KEY	Route server/api/ai/chat.post.ts app tự tạo, truyền vào createAiChatProxy	Chỉ khi dùng @tasco/ai — xem AI trong sản phẩm
NPM_TOKEN	.npmrc khi pnpm install	Token đọc registry @tasco, không bao giờ commit — xem Chuẩn bị môi trường
HOST, PORT	Server Nitro của bản build	Dockerfile của template đặt 0.0.0.0 và 3000

Biến CI/CD của app (REGISTRY_USER, REGISTRY_PASSWORD…): CI/CD & Deploy.

Liên quan

• Cấu hình & biến môi trường — ba nơi cấu hình và cách thêm khoá của dự án.
• Cấu hình IAM — đổi endpoint và mapping khi backend khác cấu trúc.
• Route BFF — route nào đọc khoá nào.