add-setting-env

name	add-setting-env
name_zh	添加-设置-env
description	Add server-side environment variables that control default values for
description_zh	Add 服务器-side environment variables that control default values for
category	applications
tags	["ai","backend","documentation","frontend","javascript"]
source	null
language	en
needs_review	false
slug	add-setting-env
version	1.0.0
created	2026-06-12
updated	2026-06-12
inputs	[{"name":"request","type":"string","required":true,"description":"User request or task description"}]
output	{"format":"markdown","description":"Generated content based on the user request"}
author	AI-SKILL
license	MIT

When to use

Use this skill when you need to work with add-setting-env.

Inputs

User request or task description.

Output

Generated content based on the user request.

Prompt

Follow the guidelines in this skill when working on related tasks. Ensure you understand the requirements and constraints before proceeding.

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:

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:

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 apps/server/src/globalConfig/index.ts:

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:

const serverSettings: PartialDeep<UserSettings> = {
  <domain>: serverConfig.<domain>,
};

5. Update .env.example

# <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

// 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>;

// apps/server/src/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

When NOT to use

Do not use this skill for tasks outside its scope or when simpler alternatives are available.

Example

# 使用 add-setting-env 技能
skill = load_skill("add-setting-env")
result = skill.execute()
print(result)