
Add Setting Env
Wire server-side environment variables so Lobe Chat defaults for user settings follow User Custom > Server Env Var > Hardcoded Default.
Overview
add-setting-env is an agent skill for the Build phase that adds typed server environment variables as default values for Lobe Chat user settings.
Install
npx skills add https://github.com/lobehub/lobe-chat --skill add-setting-envWhat is this skill?
- Four-step flow: define env in src/envs/<domain>.ts with @t3-oss/env-nextjs and Zod, extend GlobalServerConfig, assemble
- Explicit priority chain: User Custom > Server Env Var > Hardcoded Default
- Reuses packages/types user/settings types instead of inventing parallel shapes
- Supports new domains via User<Domain>Config on GlobalServerConfig and cleanObject in getServerGlobalConfig
- Model invocation disabled—human-orchestrated repo edit pattern (disable-model-invocation: true)
- 3-layer priority: User Custom > Server Env Var > Hardcoded Default
- 4 documented implementation steps from env module through server config assembly
Adoption & trust: 826 installs on skills.sh; 78.4k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need deployment-level defaults for user settings without breaking the User Custom > Server Env Var > Hardcoded Default precedence or duplicating types.
Who is it for?
Contributors extending Lobe Chat settings with operator-controlled defaults on Railway, Vercel, or self-hosted Node deployments.
Skip if: Teams not on the Lobe Chat repo, client-only feature flags, or secrets that should never surface as user-visible setting defaults.
When should I use this skill?
Add server-side environment variables that control default values for user settings (argument-hint: setting name).
What do I get? / Deliverables
You get a validated env module, updated GlobalServerConfig typing, and assembled server globals so settings defaults load from process.env on boot.
- src/envs/<domain>.ts env module
- Updated GlobalServerConfig / globalConfig assembly for the new default
Recommended Skills
Journey fit
Canonical shelf is Build because the skill implements typed server env modules and global server config assembly for the product backend. Backend subphase fits env validation, GlobalServerConfig typing, and default-setting plumbing rather than UI or agent-only tooling.
How it compares
Use this repo convention instead of ad-hoc process.env reads scattered in React components or untyped config objects.
Common Questions / FAQ
Who is add-setting-env for?
Solo builders and maintainers working in the Lobe Chat monorepo who add or change user settings that need server-provided defaults at deploy time.
When should I use add-setting-env?
Use it during Build/backend work when introducing a new settings domain or env-backed default before users can override values in the UI.
Is add-setting-env safe to install?
Treat it as procedural documentation for code changes; review the Security Audits panel on this Prism page and avoid placing secrets in user-visible setting env vars.
SKILL.md
READMESKILL.md - Add Setting Env
# Adding Environment Variable for User Settings Add server-side environment variables to configure default values for user settings. **Priority**: User Custom > Server Env Var > Hardcoded Default ## Steps ### 1. Define Environment Variable Create `src/envs/<domain>.ts`: ```typescript import { createEnv } from '@t3-oss/env-nextjs'; import { z } from 'zod'; export const get<Domain>Config = () => { return createEnv({ server: { YOUR_ENV_VAR: z.coerce.number().min(MIN).max(MAX).optional(), }, runtimeEnv: { YOUR_ENV_VAR: process.env.YOUR_ENV_VAR, }, }); }; export const <domain>Env = get<Domain>Config(); ``` ### 2. Update Type (if new domain) Add to `packages/types/src/serverConfig.ts`: ```typescript import { User<Domain>Config } from './user/settings'; export interface GlobalServerConfig { <domain>?: PartialDeep<User<Domain>Config>; } ``` **Prefer reusing existing types** from `packages/types/src/user/settings`. ### 3. Assemble Server Config (if new domain) In `src/server/globalConfig/index.ts`: ```typescript import { <domain>Env } from '@/envs/<domain>'; export const getServerGlobalConfig = async () => { const config: GlobalServerConfig = { <domain>: cleanObject({ <settingName>: <domain>Env.YOUR_ENV_VAR, }), }; return config; }; ``` ### 4. Merge to User Store (if new domain) In `src/store/user/slices/common/action.ts`: ```typescript const serverSettings: PartialDeep<UserSettings> = { <domain>: serverConfig.<domain>, }; ``` ### 5. Update .env.example ```bash # <Description> (range/options, default: X) # YOUR_ENV_VAR=<example> ``` ### 6. Update Documentation - `docs/self-hosting/environment-variables/basic.mdx` (EN) - `docs/self-hosting/environment-variables/basic.zh-CN.mdx` (CN) ## Example: AI_IMAGE_DEFAULT_IMAGE_NUM ```typescript // src/envs/image.ts AI_IMAGE_DEFAULT_IMAGE_NUM: z.coerce.number().min(1).max(20).optional(), // packages/types/src/serverConfig.ts image?: PartialDeep<UserImageConfig>; // src/server/globalConfig/index.ts image: cleanObject({ defaultImageNum: imageEnv.AI_IMAGE_DEFAULT_IMAGE_NUM }), // src/store/user/slices/common/action.ts image: serverConfig.image, // .env.example # AI_IMAGE_DEFAULT_IMAGE_NUM=4 ```