nuxt.config.ts

nuxt.config.ts is the single source of truth for modules, CSS, aliases, runtime config, and build behavior.

5 min read Level 2/5 #nuxt#config

What you'll learn

Register modules in the config
Set runtimeConfig for environment values
Enable devtools and experimental flags

nuxt.config.ts lives at the project root. It is the one file every module, build step, and runtime decision flows through.

The Skeleton

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/image', '@pinia/nuxt', '@vueuse/nuxt'],
  css: ['~/assets/css/main.css'],
  devtools: { enabled: true },
  typescript: { strict: true },
})

defineNuxtConfig is a type helper — your editor gets full autocomplete and validation for every option.

Runtime Config & Environment

runtimeConfig is how secrets and per-environment values flow into your app. The top level is server-only; the nested public block is exposed to the browser.

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '',                  // server-only
    public: {
      apiBase: '/api',              // available client + server
    },
  },
})

Override values at deploy time with environment variables:

NUXT_API_SECRET=sk_live_xxx
NUXT_PUBLIC_API_BASE=https://api.example.com

Inside any composable, page, or server route:

const config = useRuntimeConfig()
// server-only call:
fetch('https://api.stripe.com/v1/charges', {
  headers: { Authorization: `Bearer ${config.apiSecret}` },
})
// works anywhere:
fetch(config.public.apiBase + '/posts')

Aliases & Build Hints

export default defineNuxtConfig({
  alias: {
    '@types': '/types',
  },
  vite: {
    server: { hmr: { overlay: false } },
  },
  experimental: {
    typedPages: true,
  },
})

experimental.typedPages gives useRoute('/blog/[slug]') strong types for params.

File-Based Routing →