Agent Skills › lobehub/lobehub › add-setting-env

add-setting-env

GitHub

指导如何在项目中添加用于控制用户设置默认值的服务端环境变量，涵盖定义变量、更新类型、组装配置、合并至用户存储及文档更新的标准化流程。

.agents/skills/add-setting-env/SKILL.md lobehub/lobehub

Trigger Scenarios

需要新增服务端环境变量修改用户设置默认值逻辑更新项目配置文件

Install

npx skills add lobehub/lobehub --skill add-setting-env -g -y

More Options

Non-standard path

npx skills add https://github.com/lobehub/lobehub/tree/canary/.agents/skills/add-setting-env -g -y

Use without installing

npx skills use lobehub/lobehub@add-setting-env

指定 Agent (Claude Code)

npx skills add lobehub/lobehub --skill add-setting-env -a claude-code -g -y

安装 repo 全部 skill

npx skills add lobehub/lobehub --all -g -y

预览 repo 内 skill

npx skills add lobehub/lobehub --list

SKILL.md

Frontmatter

{
    "name": "add-setting-env",
    "description": "Add server-side environment variables that control default values for user settings.",
    "argument-hint": "[setting-name]",
    "disable-model-invocation": true
}

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 packages/env/src/<domain>.ts (import path stays @/envs/<domain> — tsconfig maps to packages/env/src/* first):

import { createEnv } from '@t3-oss/env-core';
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

// packages/env/src/image.ts  (import as @/envs/image)
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