Skip to content
Browse documentation
guides

Configuration and environment

Keep project metadata, native configuration, capability bindings, and server-only secrets with their owners.

Put configuration with its owner

smoothie.tomlProject/workspace identity, SDK identifier, and contract declarations.
package.json and bun.lockExact toolchain/dependency declarations, installed resolution, and native scripts.
Native target configurationVite, styling, HTTP hosting, and optional Wrangler settings.
Capability compositionExplicit provider, persistence, queue, policy, and runtime options used by your application.
Environment and secret storeTarget-specific values and credentials, read only by the target that needs them.

There is no required Framework-wide Config object or named runtime-profile registry. Configure each capability through its actual API and compose it in your native target. The local web Starter does not require model credentials just because the Framework also includes inference capabilities.

Use a minimal project manifest

toml
schema = 1

[project]
name = "my-product"
sdk = "typescript"

A created Starter already supplies this file. Preserve existing contract declarations and workspace membership when adapting it. The SDK field identifies the project; it does not install packages or select a renderer. Inspect metadata without executing the application:

bash
smoothie project check
smoothie project context --format json

Keep secrets server-only

Supply secrets through your native host's environment or secret store. Follow the adopted README for supported names, dotenv loading, and restart requirements; not every target reads .env in the same way. Browser-visible build variables become public application bytes, not a safe credential store.

Commit a value-free example when needed, not real keys. Exclude local secrets from Git, frontend imports, Agent instructions, genUI documents, logs, tool arguments, and build artifacts. A filename suffix alone does not enforce the client/server import boundary. Use separate development/test/production credentials with the minimum required access.

Validate configuration where it is consumed

Validate required values and bounds before starting the resource that uses them. Test missing or invalid configuration without making a real provider request. Project metadata checks cannot establish that a database is reachable or an API key works. Capability tests and deliberate service-backed checks provide that evidence separately.

Native provider authentication remains native. For example, Wrangler owns Cloudflare login and credentials; Smoothie does not create another provider token store. See Build and deployment for the explicit preparation and execution boundaries.