Configuration

Application Configuration

Configure your application through nuxt.config.ts and app.config.ts.

NuxtStart uses Nuxt's configuration system to manage application settings. Configuration is split between nuxt.config.ts for build-time and runtime settings, and app.config.ts for reactive app-level configuration.

`nuxt.config.ts`

Main configuration file for your Nuxt application. Located at project root.

Basic Structure

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      ],
    },
  },
  compatibilityDate: '2025-07-15',
  devtools: { enabled: true },
  modules: [
    '@nuxt/eslint',
    '@nuxt/image',
    '@nuxt/ui',
    '@pinia/nuxt',
    '@nuxt/content',
  ],
})

Key Sections

app - App-level settings like head metadata, page transitions, and root attributes.

nuxt.config.ts

app: {
  head: {
    link: [
      { rel: 'icon', type: 'image/x-icon', media: '(prefers-color-scheme: light)', href: '/favicon.ico' },
      { rel: 'icon', type: 'image/x-icon', media: '(prefers-color-scheme: dark)', href: '/favicon-light.ico' },
    ],
  },
  rootAttrs: {
    class: 'has-[>_.banner]:[--app-banner-height:48px]',
  },
}

nitro - Server engine configuration including tasks, storage, and imports.

nuxt.config.ts

nitro: {
  experimental: {
    tasks: true,
  },
  scheduledTasks: {
    [CRON_SCHEDULES_PRESET.EVERY_DAY]: ['liftBan'],
  },
  storage: {
    file: {
      driver: 's3',
      bucket: env.APP_AWS_BUCKET_NAME,
      region: env.APP_AWS_REGION,
    },
  },
}

Runtime Config

Runtime config provides environment-specific values available at both build-time and runtime. Define within runtimeConfig in nuxt.config.ts.

Structure

Top-level keys are server-only (private)
public namespace is available on both server and client

nuxt.config.ts

runtimeConfig: {
  // Server-only (private)
  mail: {
    adminEmails: env.ADMIN_EMAILS,
    from: {
      email: process.env.NODE_ENV === 'development' ? 'no-reply@example.com' : `no-reply@${env.NUXT_PUBLIC_APP_DOMAIN}`,
      name: env.NUXT_PUBLIC_APP_NAME,
    },
  },

  public: {
    // Available on both server & client
    server: {
      apiBaseUrl: env.NUXT_PUBLIC_API_BASE_URL,
    },
    app: {
      name: env.NUXT_PUBLIC_APP_NAME,
      domain: env.NUXT_PUBLIC_APP_DOMAIN,
      baseUrl: env.NUXT_PUBLIC_APP_BASE_URL,
      routes: {
        home: '/app',
        signIn: '/auth/sign-in',
        verifyEmail: '/auth/verify-email',
        billing: '/app/billing',
      },
    },
  },
}

Do note write any secrets or sensitive values in the public namespace because they are exposed to the client. Keep those in the server-only section.

Environment Variables

Runtime config values typically reference environment variables through the env utility (server/libs/env.ts):

nuxt.config.ts

import env from './server/libs/env'

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      app: {
        name: env.NUXT_PUBLIC_APP_NAME,
        domain: env.NUXT_PUBLIC_APP_DOMAIN,
      },
    },
  },
})

Set these in your .env file:

NUXT_PUBLIC_APP_NAME="NuxtStart"
NUXT_PUBLIC_APP_DOMAIN="NuxtStart.com"

Variables prefixed with NUXT_PUBLIC_ are exposed to the client. Keep sensitive values in server-only config.

`app.config.ts`

Reactive, app-level configuration for UI customization and non-sensitive settings. Located at app/app.config.ts.

Unlike runtime config, app.config.ts is not meant for secrets or environment-specific values. It's bundled client-side.

Structure

app/app.config.ts

export default defineAppConfig({
  app: {
    logoUrl: '/logo.svg',
    logoClass: 'dark:invert',
  },
  layout: {
    default: {
      themePreferences: [
        {
          label: 'System',
          icon: 'i-lucide-monitor',
          onSelect: () => useColorMode().preference = 'system',
        },
        {
          label: 'Light',
          icon: 'i-lucide-sun',
          onSelect: () => useColorMode().preference = 'light',
        },
        {
          label: 'Dark',
          icon: 'i-lucide-moon',
          onSelect: () => useColorMode().preference = 'dark',
        },
      ],
    },
  },
  ui: {
    colors: {
      primary: 'black',
      neutral: 'neutral',
    },
    card: {
      slots: {
        root: 'py-4 sm:*:py-6',
        header: '!py-0',
        body: '!py-0',
        footer: '!py-0',
      },
    },
  },
  github: {
    url: 'https://github.com/NuxtStart/NuxtStart',
    branch: 'main',
  },
  socials: {
    x: 'https://x.com/me_jd_solanki',
    discord: 'https://discord.gg/xXPJRpnv',
  },
})

Key Sections

app - Logo and branding configuration (app/app.config.ts).

app/app.config.ts

app: {
  logoUrl: '/logo.svg',
  logoClass: 'dark:invert',
}

layout - Layout-specific settings like theme preferences (app/app.config.ts:6-26).

app/app.config.ts

layout: {
  default: {
    themePreferences: [
      {
        label: 'System',
        icon: 'i-lucide-monitor',
        onSelect: () => useColorMode().preference = 'system',
      },
      // ... more theme options
    ],
  },
}

ui - Nuxt UI customization including colors and component variants (app/app.config.ts).

app/app.config.ts

ui: {
  colors: {
    primary: 'black',
    neutral: 'neutral',
  },
  card: {
    slots: {
      root: 'py-4 sm:*:py-6',
      header: '!py-0',
      body: '!py-0',
      footer: '!py-0',
    },
    variants: {
      variant: {
        outline: {
          root: 'divide-none gap-6 flex flex-col',
        },
      },
    },
  },
}

github & socials - Documentation and social links (app/app.config.ts).

app/app.config.ts

github: {
  url: 'https://github.com/NuxtStart/NuxtStart',
  branch: 'main',
},
socials: {
  x: 'https://x.com/me_jd_solanki',
  discord: 'https://discord.gg/xXPJRpnv',
}

When to Use

Use app.config.ts for:

UI theme customization
Branding (logo, colors)
Feature flags
Non-sensitive configuration

Use nuxt.config.ts runtime config for:

Environment-specific values
API endpoints
Secrets (server-only)
Build-time configuration

Edit this page or Report an issue

Environment Variables

How to manage and use environment variables in the Nuxt boilerplate.

Authentication Configuration

Configuring authentication providers and settings.