home / skills / lobehub / lobe-chat / add-setting-env

add-setting-env skill

safe

This skill helps you implement server-side environment variables to configure default user settings and manage domain-specific defaults.

npx playbooks add skill lobehub/lobe-chat --skill add-setting-env

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: add-setting-env
description: Guide for adding environment variables to configure user settings. Use when implementing server-side environment variables that control default values for user settings. Triggers on env var configuration or setting default value tasks.
---

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

Overview

This skill guides engineers through adding server-side environment variables that set default values for user settings. It enforces a clear priority (User Custom > Server Env Var > Hardcoded Default) and provides concrete file locations, TypeScript patterns, and example snippets to integrate new env-driven defaults into the app.

How this skill works

The skill shows how to declare typed environment variables, expose them via a domain-specific env module, and wire them into the global server config. It then covers merging those server defaults into the user store so the client receives sensible defaults unless a user overrides them. It also reminds you to update .env.example and documentation.

When to use it

You need server-controlled default values for user-configurable features.
Introducing a new domain of settings that should be configurable via environment variables.
Changing a hardcoded default to be deploy-time configurable.
Providing operator-controlled limits or ranges (e.g., numeric caps).
Preparing self-hosting docs and examples for environment configuration.

Best practices

Follow the priority: User Custom > Server Env Var > Hardcoded Default.
Declare env types with zod and use createEnv to coerce and validate values.
Add type entries to GlobalServerConfig, reuse existing user-setting types where possible.
Keep server config clean by mapping only defined env values using a cleanObject helper.
Update .env.example and self-hosting docs whenever you add or change env vars.

Example use cases

Add AI_IMAGE_DEFAULT_IMAGE_NUM to configure default generated image count per user session.
Expose rate limit caps or feature toggles for self-hosted deployments.
Switch a hardcoded timeout or retry count to an env var for operational tuning.
Provide default preferences (theme, page size, sorting) that admins want to control centrally.

FAQ

Where do I define the environment variable type and validation?

Create a domain file under src/envs (e.g., src/envs/image.ts) using createEnv with zod validators and runtimeEnv mappings.

How do server env values become visible to the client or user store?

Map env values into getServerGlobalConfig, then merge the resulting serverConfig into the user store slice so defaults are applied unless the user overrides them.