Learn Nuxt - Configuration & Runtime Config

#Introduction

The bigger a project gets, the more important centralized and secure configuration becomes. Episode 8 covers how to configure Nuxt properly: what lives in nuxt.config.ts at build time, and what is only known at runtime through runtime config.

The most common mistakes: storing API keys in frontend files, or editing nuxt.config.ts for values that actually depend on the environment. After this episode, you will know when to use what, and how feature flags and build optimizations can be managed in a structured way.

#nuxt.config.ts as the Configuration Hub

#One Source of Truth at Build Time

All build and module options live in nuxt.config.ts. Here is an example of common configuration for the belajar-shop project:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@pinia/nuxt", "@nuxt/image"],
  css: ["~/assets/css/main.css"],
  app: {
    head: {
      title: "Belajar Shop",
      meta: [{ name: "description", content: "Toko contoh belajar Nuxt" }],
    },
  },
})

The app.head option sets the global title and meta tags rendered on every page. Changes to this file require a dev server restart, because it is only read when the build starts.

#The RuntimeConfig Component

runtimeConfig is the part of nuxt.config.ts whose values can be changed at runtime without rebuilding. Its values are read from environment variables:

Runtime config dengan env

export default defineNuxtConfig({
  runtimeConfig: {
    apiKey: process.env.API_KEY,
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || "/api",
    },
  },
})

runtimeConfig is split in two: the defaults in public can be accessed by the client, and the values outside public are only available on the server. Environment variables are overridden automatically following naming rules.

#Environment Variables and Public/Private Config

#Environment Variable Naming Rules

Nuxt reads environment variables based on their name. For public values, the variable name is NUXT_PUBLIC_*; for private values, it's NUXT_*:

NUXT_PUBLIC_API_BASE=https://api.belajarshop.dev
NUXT_API_KEY=rahasia-jangan-bocor
NUXT_PUBLIC_SITE_URL=https://belajarshop.dev

The .env file above must not be committed to git — add it to .gitignore. Note one important detail: variables without the NUXT_ prefix are not automatically read by Nuxt.

#Public vs Private

Here is the crucial difference:

• Public config is sent to the browser. Only put values that are safe for the public to see, like a base URL.
• Private config only exists on the server, read through config.apiKey. Never use its value in client-side components.

Membaca config di server

const config = useRuntimeConfig()
 
async function getDataEksternal() {
  return await $fetch("https://api.eksternal.dev/v1", {
    headers: { Authorization: `Bearer ${config.apiKey}` },
  })
}

config.apiKey above may only be called in server code — for example in server/api. If called in a component, its value becomes undefined because it is not sent to the client.

#Configuring Modules and Plugins

#Passing Options to a Module

Many modules accept options through an array in modules:

Module dengan opsi

export default defineNuxtConfig({
  modules: [
    "@nuxt/image",
    ["@nuxtjs/i18n", { locales: ["id", "en"], defaultLocale: "id" }],
  ],
})

For modules with many options, the ["module-name", options] array form is more readable. Each module documents the options it supports.

#Application Plugins

Nuxt plugins are code run when the application initializes, defined in app/plugins. Their configuration usually concerns third-party libraries that need setup at startup.

#Build Optimizations and Feature Flags

#Build Optimizations

Nuxt optimizes the build automatically — code chunk splitting, minification, and tree-shaking. You can also tune it with the build.transpile option for specific libraries, or enable experiments:

Opsi build

export default defineNuxtConfig({
  build: {
    transpile: ["beberapa-library"],
  },
  features: {
    inlineStyles: true,
  },
})

#Feature Flags

Feature flags let you enable or disable features without rewriting code. Combine runtime config with conditions in components:

Feature flag lewat runtime config

const config = useRuntimeConfig()
const promoAktif = computed(() => config.public.promoAktif === "true")

The value config.public.promoAktif comes from NUXT_PUBLIC_PROMO_AKTIF in .env. Change the env value, restart, and the promo feature changes immediately without touching the code.

#Conclusion

Episode 8 makes your configuration centralized and secure: nuxt.config.ts for everything known at build time, runtime config for values that change at runtime, a firm separation between public and private config, and feature flags controlled through environment variables.

Key takeaways:

• nuxt.config.ts is the single source of truth for build configuration.
• runtimeConfig combines static values with environment variables.
• Public config must be safe for the browser; private config is server-only.
• Public variables use the NUXT_PUBLIC_ prefix, private ones use NUXT_.
• Never use private config in client-side code.
• Feature flags can be controlled via runtime config without changing code.

In the next episode, episode 9, we will discuss images and assets — image optimization with @nuxt/image, managing static assets and the public folder, responsive images with lazy loading, and media optimization strategies for performance. Your store will look sharp and load fast.