Nuxt 3 provides powerful configuration options, allowing you to adapt your application to different use cases.

The two key parts of Nuxt 3's configuration system are runtimeConfig and appConfig. This article will explain the purpose and differences between these two options and show you how to use them.

Understanding runtimeConfig

runtimeConfig is used to expose environment variables and private tokens within your application, such as API keys or other sensitive information. These values can be set in the nuxt.config.ts file and can be overridden using environment variables.

Setting up runtimeConfig in nuxt.config.ts

To set up private and public keys in your nuxt.config.ts file, you can use the following code example:

export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available server-side
    shoeStoreApiSecret: 'my-secret-key',
    // Keys within public are also exposed client-side
    public: {
      shoeStoreApiBase: '/shoe-api'
    }
  }
})

Accessing runtimeConfig values

To access runtimeConfig values within your application, you can use the useRuntimeConfig composable:

<script setup lang="ts">
const { shoeStoreApiBase } = useRuntimeConfig();
console.log(shoeStoreApiBase); // /shoe-api
</script>

Note that you can’t access a private key on the client-side:

<script setup lang="ts">
const { shoeStoreApiSecret } = useRuntimeConfig();
console.log(shoeStoreApiSecret); // undefined
</script>

But you can access all values in a server route:

export default defineEventHandler(async (event) => {
  const { shoreStoreApiSecret } = useRuntimeConfig();
  console.log(shoeStoreApiSecret); // my-secret-key
});

Using environment variables

You can set environment variables in a .env file to make them accessible during development and build/generate. Just make sure that you use the right prefixes.

Put NUXT_ before everything, and don’t forget to add in PUBLIC if it’s a value in the public field of your config:

NUXT_PUBLIC_SHOE_STORE_API_BASE_URL = "https://api.shoestore.com"
NUXT_SHOE_STORE_API_SECRET = "my-secret-key"

Understanding app.config

app.config is used to expose public variables that can be determined at build time, such as theme variants, titles, or other non-sensitive project configurations. These values are set in the app.config.ts file.

Setting up app.config in app.config.ts

To define app.config variables, you need to create the app.config.ts file in the root of your project:

// app.config.ts

export default defineAppConfig({
  theme: {
    primaryColor: '#ababab'
  }
})

Accessing app.config values

To access app.config values within your application, you can use the useAppConfig composable:

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

Typing App Config

Although the appConfig type is automatically inferred, you can manually type your app.config using TypeScript if you really need to. This example is from the docs:

// index.d.ts
declare module 'nuxt/schema' {
  interface AppConfig {
    // This will entirely replace the existing inferred `theme` property
    theme: {
      // You might want to type this value to add more specific types than Nuxt can infer,
      // such as string literal types
      primaryColor?: 'red' | 'blue'
    }
  }
}

If you’re writing a module that needs config, you can also provide a type for your module.

Comparison of runtimeConfig and app.config

To better understand the differences and similarities between runtimeConfig and app.config, let's take a look at this feature comparison table (taken from the Nuxt documentation):

Both runtimeConfig and app.config allow you to expose variables to your application. However, there are some key differences:

1. runtimeConfig supports environment variables, whereas app.config does not. This makes runtimeConfig more suitable for values that need to be specified after the build using environment variables.
2. runtimeConfig values are hydrated on the client side during run-time, while app.config values are bundled during the build process.
3. app.config supports Hot Module Replacement (HMR), which means you can update the configuration without a full page reload during development.
4. app.config values can be fully typed with TypeScript, whereas runtimeConfig cannot.

When to use runtimeConfig and app.config

To decide whether to use runtimeConfig or app.config, I’d think about it this way:

• runtimeConfig: Use runtimeConfig for private or public tokens that need to be specified after the build using environment variables. This is ideal for sensitive information or values that may change between different environments.
• app.config: Use app.config for public tokens that are determined at build time, such as website configuration (theme variant, title) or any project config that are not sensitive. Since app.config supports HMR, it is particularly helpful for values that you may want to update during development without a full page reload.

Conclusion

runtimeConfig and app.config serve different purposes in a Nuxt application.

runtimeConfig is great for handling private or public tokens that require environment variables, while app.config is perfect for public tokens and project configurations that are determined at build time.

By choosing the right configuration option for your use case, you can ensure that your Nuxt application is both secure and easily maintainable.