How it works
Site config resolves from the following sources, in order of precedence:
Build Time
1. System
System details relate to the environment the app is running in.
export default {
env: import.meta.envName || process.env.NODE_ENV,
}If you do not set indexable, the resolved config derives it from env: true when env is 'production', else false.
2. Vendor CI Environment
When deploying to supported platforms, url and name are automatically populated from platform environment variables. These have low priority and are overridden by any explicit config you provide.
| Platform | url | name |
|---|---|---|
| Vercel | VERCEL_URL, NUXT_ENV_VERCEL_URL | NUXT_ENV_VERCEL_GIT_REPO_SLUG |
| Netlify | URL | SITE_NAME |
| Cloudflare Pages | CF_PAGES_URL |
site.name is no longer inferred from your project directory or package.json. It will only be auto-populated from CI platform env vars listed above, or from explicit config. See the v4 release notes.- Module overrides: Build time site config that modules set with
updateSiteConfig()fromnuxt-site-config/kit. - Nuxt Config
sitekey: Site config provided by the user in the Nuxt config. - Nuxt Hook:
updateSiteConfig()calls in thesite-config:resolvehook. - I18n:
urlfromi18n.baseUrland the default locale. - Runtime Config and Environment Variables:
runtimeConfig.public.siteand theNUXT_SITE_*environment variables (e.g.NUXT_SITE_URL,NUXT_SITE_NAME), first at build time, then at runtime.
A build time updateSiteConfig() call without a _priority ranks with the site key (SiteConfigPriority.config). To rank an entry differently, pass _priority with a SiteConfigPriority value.
SSR / Nitro Runtime
- Request URL: The request URL determines the site URL at runtime.
- Build Time Site Config: Config resolved in the build step, stored on
runtimeConfig['nuxt-site-config'].stack. - Route Rules: Config resolved from the route rules of the request path, the
sitekey. This allows for multi-site support.
CSR Runtime
In CSR, the browser hydrates site config directly from the SSR-rendered payload sent by the server. This ensures the client has the same config as the server without any hydration mismatches.