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):
Feature | runtimeConfig | app.config |
---|---|---|
Client Side | Hydrated | Bundled |
Environment Variables | ✅ Yes | ❌ No |
Reactive | ✅ Yes | ✅ Yes |
Types support | ✅ Partial | ✅ Yes |
Configuration per Request | ❌ No | ✅ Yes |
Hot Module Replacement | ❌ No | ✅ Yes |
Non primitive JS types | ❌ No | ✅ Yes |
Both runtimeConfig
and app.config
allow you to expose variables to your application. However, there are some key differences:
runtimeConfig
supports environment variables, whereasapp.config
does not. This makesruntimeConfig
more suitable for values that need to be specified after the build using environment variables.runtimeConfig
values are hydrated on the client side during run-time, whileapp.config
values are bundled during the build process.app.config
supports Hot Module Replacement (HMR), which means you can update the configuration without a full page reload during development.app.config
values can be fully typed with TypeScript, whereasruntimeConfig
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.