Configuration
Where a configuration value belongs, app config schema, agent-native.config.ts, or an...
Install
npx skills add BuilderIO/agent-native --skill configuration -g -a claude-code -y- Repository
- BuilderIO/agent-native7.6k
- Category
- AI and agents
- Updated
- 3d ago
- License
- MIT
- Context cost
- Mediumabout 2,051 tokens
- Runs scripts
- No, instructions only
What it does
Where a configuration value belongs, app config schema, agent-native.config.ts, or an environment variable, and how the layers resolve. Use before adding an env var, a configure*/set* function, a plugin option, or a register* function, and when deciding whether something is config or a registry.
Configuration
Core had 301 distinct environment variables and only 48 of them were secrets.
The other 253 are product decisions that landed in process.env because at the
call site that needed them, nothing else was reachable. This skill exists so the
next value does not do the same thing.
The rule
Consumer code never reads process.env. Exactly four resolvers do:
| Resolver | Covers |
|---|---|
The app config env layer (app-config/env-layer.ts) | product behavior, via a declared .meta({ env }) alias |
resolveDeployEnvironment() | platform facts, NODE_ENV, NETLIFY, AWS_* |
readDeployCredentialEnv() | secrets, as the deployment layer inside scoped resolution |
getAmbientUserEmail() / getAmbientOrgId() | CLI identity when there is no request context |
The bottom three are not configuration: platform variables are facts nobody sets in an app, credentials resolve per user or org, and ambient identity exists only for CLI runs. Everything else is a field in the schema.
This is the credential rule ("one resolver per key, and every runtime path goes through it") applied to all configuration, with a schema lookup replacing the grep.
Where a value goes
| Value | Where |
|---|---|
| Server behavior, closures, per-tenant resolvers, anything not for a browser | defineAppConfig() |
| Client-visible data | agent-native.config.ts |
| A deployment override of a server value | an env alias on the schema field |
| A secret value | the vault, via resolveCredential, see the secrets skill |
| Something a user changes at runtime in the UI | the settings store, not config |
