mcpField
A
add-setting-env

add-setting-env

github.com/lobehubDevelopment83.6k4.2k installsUpdated today
Repository

About add-setting-env

A development guide for adding server-side environment variables that provide defaults for user settings. It covers configuration, types, server config assembly, store merging, and documentation updates.

Key features

  1. 01Define validated environment variables
  2. 02Add or reuse server configuration types
  3. 03Assemble global server configuration
  4. 04Merge defaults into the user store
  5. 05Update example and self-hosting documentation

Use cases

  1. 01Setting server-provided defaults for user preferences
  2. 02Adding a configurable setting in a new domain
  3. 03Documenting an environment variable for deployment

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lobehub/lobehub --skill add-setting-env

After installing, type/add-setting-envin Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

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

Comments

Markdown supported