add-setting-env_skill

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.