mydot/agents/.agents/skills/nuxt/references/core-config.md

name, description

name	description
configuration	Nuxt configuration files including nuxt.config.ts, app.config.ts, and runtime configuration

Nuxt Configuration

Nuxt uses configuration files to customize application behavior. The main configuration options are nuxt.config.ts for build-time settings and app.config.ts for runtime settings.

nuxt.config.ts

The main configuration file at the root of your project:

// nuxt.config.ts
export default defineNuxtConfig({
  // Configuration options
  devtools: { enabled: true },
  modules: ['@nuxt/ui'],
})

Nuxt 4 Path Aliases

In Nuxt 4 the default srcDir is app/, so the path aliases changed:

Alias	Resolves to
~ / @	<rootDir>/app
~~ / @@	<rootDir> (project root)
#shared	<rootDir>/shared
#server	<rootDir>/server

Reference root-level paths (modules, server handlers) with ~~ or #server:

export default defineNuxtConfig({
  modules: ['~~/custom-modules/awesome.js'], // relative to rootDir
  serverHandlers: [
    { route: '/foo/**', handler: '#server/foohandler.ts' },
  ],
})

Compatibility Version

Nuxt 4 is the default behavior. To preview upcoming Nuxt 5 defaults (Vite Environment API, normalized page names, etc.):

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5,
  },
})

Environment Overrides

Configure environment-specific settings:

export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {
    // Development-specific config
  },
  $env: {
    staging: {
      // Staging environment config
    },
  },
})

Use --envName flag to select environment: nuxt build --envName staging

Runtime Config

For values that need to be overridden via environment variables:

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only keys
    apiSecret: '123',
    // Keys within public are exposed to client
    public: {
      apiBase: '/api',
    },
  },
})

Override with environment variables:

# .env
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://api.example.com

Access in components/composables:

<script setup lang="ts">
const config = useRuntimeConfig()
// Server: config.apiSecret, config.public.apiBase
// Client: config.public.apiBase only
</script>

App Config

For public tokens determined at build time (not overridable via env vars):

// app/app.config.ts
export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000',
    },
  },
})

Access in components:

<script setup lang="ts">
const appConfig = useAppConfig()
</script>

runtimeConfig vs app.config

Feature	runtimeConfig	app.config
Client-side	Hydrated	Bundled
Environment variables	Yes	No
Reactive	Yes	Yes
Hot module replacement	No	Yes
Non-primitive JS types	No	Yes

Use runtimeConfig for secrets and values that change per environment. Use app.config for public tokens, theme settings, and non-sensitive config.

External Tool Configuration

Nuxt uses nuxt.config.ts as single source of truth. Configure external tools within it:

export default defineNuxtConfig({
  // Nitro configuration
  nitro: {
    // nitro options
  },
  // Vite configuration
  vite: {
    // vite options
    vue: {
      // @vitejs/plugin-vue options
    },
  },
  // PostCSS configuration
  postcss: {
    // postcss options
  },
})

Environment-specific Vite Config

Top-level vite options are shared. Use $client and $server to target a single Vite build:

export default defineNuxtConfig({
  vite: {
    $client: {
      build: { rollupOptions: { output: { manualChunks: { analytics: ['analytics-package'] } } } },
    },
    $server: {
      build: { sourcemap: 'inline' },
    },
  },
})

Vue Configuration

Enable Vue experimental features:

export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})

Experimental Features & Defaults

Notable Nuxt 4 flags under experimental (see source for the full list):

export default defineNuxtConfig({
  experimental: {
    // Stream the HTML shell first, then render body progressively (better TTFB)
    ssrStreaming: true,
    // Run useFetch when its key changes even if immediate:false and not yet triggered
    alwaysRunFetchOnKeyChange: true,
    // Split useAsyncData handlers into separate chunks (static builds)
    extractAsyncDataHandlers: true,
    // pending is true before fetching starts
    pendingWhenIdle: true,
    // Default options for core composables/components
    defaults: {
      nuxtLink: { prefetch: true, prefetchOn: { visibility: true } },
      useAsyncData: { deep: true },
      useState: { resetOnClear: true },
    },
  },
})