From dd4d5d4de0c425900615cb3256e6abda612e3983 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= Date: Tue, 20 Sep 2022 11:07:43 +0200 Subject: [PATCH 01/10] docs: wip on configuration intro --- .../1.getting-started/3.configuration.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/content/1.getting-started/3.configuration.md diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md new file mode 100644 index 00000000000..bbc5a24ef1f --- /dev/null +++ b/docs/content/1.getting-started/3.configuration.md @@ -0,0 +1,43 @@ +# Configuration + +By default, Nuxt is configured to cover most use cases. The `nuxt.config.ts` file can override this default configuration, and provide custom variables. + +## The `nuxt.config.ts` file + +The configuration file is located at the root of a Nuxt project and can override or extend the application's behavior. + +A minimal configuration file exports the `defineNuxtConfig` function containing an object with your configuration. The `defineNuxtConfig` helper is globally available without import. + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + // My Nuxt config +}) +``` + +This file will often be mentioned in the documentation, for example to add custom scripts, register modules or change rendering modes. + +::alert{type=info} +Every configuration option is described in the [Configuration Reference](/api/configuration/nuxt.config). +:: + +::alert{type=info} +You don't have to use Typescript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration. +:: + +::alert{type=info} +Learn how to declare and use environement variables from your configuration file +:: + +## tsconfig.json + +Nuxt automatically generates a `.nuxt/tsconfig.json` file with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults. + +You can benefit from this by creating a [`tsconfig.json`](/guide/concepts/typescript) in the root of your project with the following content: + +```json +{ + "extends": "./.nuxt/tsconfig.json" +} +``` + +As you need to, you can customize the contents of this file. However, note that if you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the `alias` property within your `nuxt.config`, where they will get picked up and added to the autogenerated `tsconfig`. From 1e7d51b999db7d82252b4842fae9ad3fb67848f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= Date: Tue, 20 Sep 2022 17:29:17 +0200 Subject: [PATCH 02/10] docs(getting-started): complete configuration section --- .../1.getting-started/3.configuration.md | 97 ++++++++++++++++--- 1 file changed, 84 insertions(+), 13 deletions(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index bbc5a24ef1f..59fd38fc042 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -1,10 +1,10 @@ # Configuration -By default, Nuxt is configured to cover most use cases. The `nuxt.config.ts` file can override this default configuration, and provide custom variables. +By default, Nuxt is configured to cover most use cases. The `nuxt.config.ts` file can override or extend this default configuration, and provide custom variables. -## The `nuxt.config.ts` file +## Nuxt configuration -The configuration file is located at the root of a Nuxt project and can override or extend the application's behavior. +The `nuxt.config.ts` file is located at the root of a Nuxt project and can override or extend the application's behavior. A minimal configuration file exports the `defineNuxtConfig` function containing an object with your configuration. The `defineNuxtConfig` helper is globally available without import. @@ -24,20 +24,91 @@ Every configuration option is described in the [Configuration Reference](/api/co You don't have to use Typescript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration. :: -::alert{type=info} -Learn how to declare and use environement variables from your configuration file +### Environment variables and private tokens + +The `runtimeConfig` API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within `runtimeConfig.public` are also available client-side. + +Those values can be overriden **at build time or after** by a `.env` file at the root of your project. + +::code-group + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + runtimeConfig: { + // The private keys which are only available server-side + apiSecret: '123', + // Keys within public are also exposed client-side + public: { + apiBase: '/api' + } + } +}) +``` + +```text [.env] +# This will override the value of apiSecret +NUXT_API_SECRET=api_secret_token +``` + :: -## tsconfig.json +These variables are exposed to the rest of your application using the `useRuntimeConfig` composable. + +```vue [pages/index.vue] + +``` -Nuxt automatically generates a `.nuxt/tsconfig.json` file with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults. +## App configuration -You can benefit from this by creating a [`tsconfig.json`](/guide/concepts/typescript) in the root of your project with the following content: +The `app.config.ts` file, also located at the root of a Nuxt project, is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these can not be overriden using environment variables. -```json -{ - "extends": "./.nuxt/tsconfig.json" -} +A minimal configuration file exports the `defineAppConfig` function containing an object with your configuration. The `defineAppConfig` helper is globally available without import. + +```ts [app.config.ts] +defineAppConfig({ + title: 'Hello Nuxt' + theme: { + dark: true, + colors: { + primary: '#ff0000' + } + } +}) ``` -As you need to, you can customize the contents of this file. However, note that if you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the `alias` property within your `nuxt.config`, where they will get picked up and added to the autogenerated `tsconfig`. +These variables are exposed to the rest of your application using the `useAppConfig` composable. + +```vue [pages/index.vue] + +``` + +## `runtimeConfig` VS `app.config` + +As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine wether you should use one or the other, here are some guidelines: + +### Usage + +- `app.config` : Public tokens that are determined on build time, website configuration such as theme variant, title and any public project config that is determined on build time. +- `runtime config`: Private tokens or tokens that need to be specified after build using environment variables. + +### Pros and Cons + +#### `runtimeConfig` + +| Pros | Cons | +|------------------------|------------------| +| ✅ Can be overriden with environement variables | ❌ Adds to page load +| ✅ Fully dynamic for a server-deployment that needs to change config after build | ❌ Only accepts JS primitive types +| ✅ Private tokens | + +#### `app.config` + +| Pros | Cons | +|------------------------|------------------| +| ✅ More efficient | ❌ Cannot be overriden with environement variables +| ✅ Better typed | ❌ Cannot be changed after build +| ✅ Any JS variable type | From 3338886391549d86adb2adea57c69d473ac0b3a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= Date: Tue, 20 Sep 2022 17:46:36 +0200 Subject: [PATCH 03/10] docs(getting-started): add links to configuration guide --- docs/content/1.getting-started/3.configuration.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index 59fd38fc042..c91eebd48af 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -52,7 +52,7 @@ NUXT_API_SECRET=api_secret_token :: -These variables are exposed to the rest of your application using the `useRuntimeConfig` composable. +These variables are exposed to the rest of your application using the [`useRuntimeConfig`](/api/composables/use-runtime-config) composable. ```vue [pages/index.vue] ``` +:ReadMore{link="/guide/going-further/runtime-config"} + ## App configuration The `app.config.ts` file, also located at the root of a Nuxt project, is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these can not be overriden using environment variables. @@ -78,7 +80,7 @@ defineAppConfig({ }) ``` -These variables are exposed to the rest of your application using the `useAppConfig` composable. +These variables are exposed to the rest of your application using the [`useAppConfig`](/api/composables/use-app-config) composable. ```vue [pages/index.vue] ``` +:ReadMore{link="/guide/directory-structure/app.config"} + ## `runtimeConfig` VS `app.config` As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine wether you should use one or the other, here are some guidelines: From 240fcd5fc1bcd51f7bf99a584b592d4318fc00f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= Date: Wed, 21 Sep 2022 09:34:12 +0200 Subject: [PATCH 04/10] Update docs/content/1.getting-started/3.configuration.md Co-authored-by: pooya parsa --- docs/content/1.getting-started/3.configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index c91eebd48af..abbbc78c41f 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -28,7 +28,7 @@ You don't have to use Typescript to build an application with Nuxt. However, it The `runtimeConfig` API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within `runtimeConfig.public` are also available client-side. -Those values can be overriden **at build time or after** by a `.env` file at the root of your project. +Those values should be defined in `nuxt.config` and can be overridden using environment variables. ::code-group From a303fa92933eb2d830baffc53c4147990491a1d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= Date: Wed, 21 Sep 2022 09:34:34 +0200 Subject: [PATCH 05/10] Update docs/content/1.getting-started/3.configuration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Chopin --- docs/content/1.getting-started/3.configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index abbbc78c41f..f5c3434329a 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -1,6 +1,6 @@ # Configuration -By default, Nuxt is configured to cover most use cases. The `nuxt.config.ts` file can override or extend this default configuration, and provide custom variables. +By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/guide/directory-structure/nuxt.config) file can override or extend this default configuration, and provide custom variables. ## Nuxt configuration From 301e06e0c436421f935271bcd5ecb9b8f79ad3c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Wed, 21 Sep 2022 10:24:57 +0200 Subject: [PATCH 06/10] chore: update --- docs/content/1.getting-started/3.configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index f5c3434329a..e7c1238d8e2 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -96,8 +96,8 @@ As stated above, `runtimeConfig` and `app.config` are both used to expose variab ### Usage -- `app.config` : Public tokens that are determined on build time, website configuration such as theme variant, title and any public project config that is determined on build time. -- `runtime config`: Private tokens or tokens that need to be specified after build using environment variables. +- `runtimeConfig`: Private or public tokens that need to be specified after build using environment variables. +- `app.config` : Public tokens that are determined at build time, website configuration such as theme variant, title and any project config that are not sensitive. ### Pros and Cons From fff4201ffc3e1c36a5038b172e8ea3e025c26c96 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Wed, 21 Sep 2022 09:34:32 +0100 Subject: [PATCH 07/10] docs: some small tweaks --- docs/content/1.getting-started/3.configuration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index e7c1238d8e2..47f8f04bb33 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -1,6 +1,6 @@ # Configuration -By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/guide/directory-structure/nuxt.config) file can override or extend this default configuration, and provide custom variables. +By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/guide/directory-structure/nuxt.config) file can override or extend this default configuration. ## Nuxt configuration @@ -21,7 +21,7 @@ Every configuration option is described in the [Configuration Reference](/api/co :: ::alert{type=info} -You don't have to use Typescript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration. +You don't have to use TypeScript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration. :: ### Environment variables and private tokens @@ -69,7 +69,7 @@ The `app.config.ts` file, also located at the root of a Nuxt project, is used to A minimal configuration file exports the `defineAppConfig` function containing an object with your configuration. The `defineAppConfig` helper is globally available without import. ```ts [app.config.ts] -defineAppConfig({ +export default defineAppConfig({ title: 'Hello Nuxt' theme: { dark: true, @@ -92,7 +92,7 @@ const appConfig = useAppConfig() ## `runtimeConfig` VS `app.config` -As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine wether you should use one or the other, here are some guidelines: +As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine whether you should use one or the other, here are some guidelines: ### Usage @@ -105,7 +105,7 @@ As stated above, `runtimeConfig` and `app.config` are both used to expose variab | Pros | Cons | |------------------------|------------------| -| ✅ Can be overriden with environement variables | ❌ Adds to page load +| ✅ Can be overridden with environment variables | ❌ Adds to page payload size | ✅ Fully dynamic for a server-deployment that needs to change config after build | ❌ Only accepts JS primitive types | ✅ Private tokens | From 6ae797db69d6e57af674654b4dec48fef742bd2d Mon Sep 17 00:00:00 2001 From: pooya parsa Date: Wed, 21 Sep 2022 11:55:01 +0200 Subject: [PATCH 08/10] Update docs/content/1.getting-started/3.configuration.md --- docs/content/1.getting-started/3.configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index 47f8f04bb33..f780d1f01a6 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -70,7 +70,7 @@ A minimal configuration file exports the `defineAppConfig` function containing a ```ts [app.config.ts] export default defineAppConfig({ - title: 'Hello Nuxt' + title: 'Hello Nuxt', theme: { dark: true, colors: { From 674f5bc018436f0eb6278669d811b8275b073f7d Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Wed, 21 Sep 2022 12:35:02 +0200 Subject: [PATCH 09/10] update comparation table --- .../1.getting-started/3.configuration.md | 30 +++++++------------ 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index f780d1f01a6..177640c32df 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -90,29 +90,19 @@ const appConfig = useAppConfig() :ReadMore{link="/guide/directory-structure/app.config"} -## `runtimeConfig` VS `app.config` +## `runtimeConfig` or `app.config` As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine whether you should use one or the other, here are some guidelines: -### Usage - - `runtimeConfig`: Private or public tokens that need to be specified after build using environment variables. - `app.config` : Public tokens that are determined at build time, website configuration such as theme variant, title and any project config that are not sensitive. -### Pros and Cons - -#### `runtimeConfig` - -| Pros | Cons | -|------------------------|------------------| -| ✅ Can be overridden with environment variables | ❌ Adds to page payload size -| ✅ Fully dynamic for a server-deployment that needs to change config after build | ❌ Only accepts JS primitive types -| ✅ Private tokens | - -#### `app.config` - -| Pros | Cons | -|------------------------|------------------| -| ✅ More efficient | ❌ Cannot be overriden with environement variables -| ✅ Better typed | ❌ Cannot be changed after build -| ✅ Any JS variable type | +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 From e3416faaa02e39951d816fd6ddd045384c03d9f2 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Wed, 21 Sep 2022 12:36:08 +0200 Subject: [PATCH 10/10] title casing --- docs/content/1.getting-started/3.configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/1.getting-started/3.configuration.md b/docs/content/1.getting-started/3.configuration.md index 177640c32df..0ea468afb99 100644 --- a/docs/content/1.getting-started/3.configuration.md +++ b/docs/content/1.getting-started/3.configuration.md @@ -2,7 +2,7 @@ By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/guide/directory-structure/nuxt.config) file can override or extend this default configuration. -## Nuxt configuration +## Nuxt Configuration The `nuxt.config.ts` file is located at the root of a Nuxt project and can override or extend the application's behavior. @@ -24,7 +24,7 @@ Every configuration option is described in the [Configuration Reference](/api/co You don't have to use TypeScript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration. :: -### Environment variables and private tokens +### Environment Variables and Private Tokens The `runtimeConfig` API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within `runtimeConfig.public` are also available client-side. @@ -62,7 +62,7 @@ const runtimeConfig = useRuntimeConfig() :ReadMore{link="/guide/going-further/runtime-config"} -## App configuration +## App Configuration The `app.config.ts` file, also located at the root of a Nuxt project, is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these can not be overriden using environment variables. @@ -90,7 +90,7 @@ const appConfig = useAppConfig() :ReadMore{link="/guide/directory-structure/app.config"} -## `runtimeConfig` or `app.config` +## `runtimeConfig` vs `app.config` As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine whether you should use one or the other, here are some guidelines: