@nuxt/docs 0.0.0 → 3.17.1

package/2.guide/3.going-further/1.features.md

@@ -0,0 +1,103 @@
+---
+title: "Features"
+description: "Enable or disable optional Nuxt features to unlock new possibilities."
+---
+
+Some features of Nuxt are available on an opt-in basis, or can be disabled based on your needs.
+
+## `features`
+
+### inlineStyles
+
+Inlines styles when rendering HTML. This is currently available only when using Vite.
+
+You can also pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  features: {
+    inlineStyles: false // or a function to determine inlining
+  }
+})
+```
+
+### noScripts
+
+Disables rendering of Nuxt scripts and JS resource hints. Can also be configured granularly within `routeRules`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  features: {
+    noScripts: true
+  }
+})
+```
+
+## `future`
+
+There is also a `future` namespace for early opting-in to new features that will become default in a future (possibly major) version of the framework.
+
+### compatibilityVersion
+
+::important
+This configuration option is available in Nuxt v3.12+. Please note, that for now, you need to define the compatibility version in each layer that opts into Nuxt 4 behavior. This will not be required after Nuxt 4 is released.
+::
+
+This enables early access to Nuxt features or flags.
+
+Setting `compatibilityVersion` to `4` changes defaults throughout your
+Nuxt configuration to opt-in to Nuxt v4 behaviour, but you can granularly re-enable Nuxt v3 behaviour
+when testing (see example). Please file issues if so, so that we can
+address in Nuxt or in the ecosystem.
+
+```ts
+export default defineNuxtConfig({
+  future: {
+    compatibilityVersion: 4,
+  },
+  // To re-enable _all_ Nuxt v3 behaviour, set the following options:
+  srcDir: '.',
+  dir: {
+    app: 'app'
+  },
+  experimental: {
+    scanPageMeta: 'after-resolve',
+    sharedPrerenderData: false,
+    compileTemplate: true,
+    resetAsyncDataToUndefined: true,
+    templateUtils: true,
+    relativeWatchPaths: true,
+    normalizeComponentNames: false
+    defaults: {
+      useAsyncData: {
+        deep: true
+      }
+    }
+  },
+  features: {
+    inlineStyles: true
+  },
+  unhead: {
+    renderSSRHeadOptions: {
+      omitLineBreaks: false
+    }
+  }
+})
+```
+
+### typescriptBundlerResolution
+
+This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting
+for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance.html#reduce-resolve-operations).
+
+It improves type support when using modern libraries with `exports`.
+
+See [the original TypeScript pull request](https://github.com/microsoft/TypeScript/pull/51669).
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  future: {
+    typescriptBundlerResolution: true
+  }
+})
+```

package/2.guide/3.going-further/1.internals.md

@@ -0,0 +1,81 @@
+---
+title: "How Nuxt Works?"
+description: "Nuxt is a minimal but highly customizable framework to build web applications."
+---
+
+This guide helps you better understand Nuxt internals to develop new solutions and module integrations on top of Nuxt.
+
+## The Nuxt Interface
+
+When you start Nuxt in development mode with [`nuxi dev`](/docs/api/commands/dev) or building a production application with [`nuxi build`](/docs/api/commands/build),
+a common context will be created, referred to as `nuxt` internally. It holds normalized options merged with `nuxt.config` file,
+some internal state, and a powerful [hooking system](/docs/api/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
+allowing different components to communicate with each other. You can think of it as **Builder Core**.
+
+This context is globally available to be used with [Nuxt Kit](/docs/guide/going-further/kit) composables.
+Therefore only one instance of Nuxt is allowed to run per process.
+
+To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/guide/going-further/modules).
+
+For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nuxt.ts).
+
+## The NuxtApp Interface
+
+When rendering a page in the browser or on the server, a shared context will be created, referred to as `nuxtApp`.
+This context keeps vue instance, runtime hooks, and internal states like ssrContext and payload for hydration.
+You can think of it as **Runtime Core**.
+
+This context can be accessed using [`useNuxtApp()`](/docs/api/composables/use-nuxt-app) composable within Nuxt plugins and `<script setup>` and vue composables.
+Global usage is possible for the browser but not on the server, to avoid sharing context between users.
+
+Since [`useNuxtApp`](/docs/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
+
+To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/guide/directory-structure/plugins).
+
+Check [Nuxt App](/docs/api/composables/use-nuxt-app) for more information about this interface.
+
+`nuxtApp` has the following properties:
+
+```js
+const nuxtApp = {
+  vueApp, // the global Vue application: https://vuejs.org/api/application.html#application-api
+
+  versions, // an object containing Nuxt and Vue versions
+
+  // These let you call and add runtime NuxtApp hooks
+  // https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts#L18
+  hooks,
+  hook,
+  callHook,
+
+  // Only accessible on server-side
+  ssrContext: {
+    url,
+    req,
+    res,
+    runtimeConfig,
+    noSSR,
+  },
+
+  // This will be stringified and passed from server to client
+  payload: {
+    serverRendered: true,
+    data: {},
+    state: {}
+  }
+
+  provide: (name: string, value: any) => void
+}
+```
+
+For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts).
+
+## Runtime Context vs. Build Context
+
+Nuxt builds and bundles project using Node.js but also has a runtime side.
+
+While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
+
+`nuxt.config` and [Nuxt Modules](/docs/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/guide/directory-structure/plugins) can be used to extend runtime.
+
+When building an application for production, `nuxi build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/guide/going-further/modules).

package/2.guide/3.going-further/10.runtime-config.md

@@ -0,0 +1,174 @@
+---
+title: "Runtime Config"
+description: "Nuxt provides a runtime config API to expose configuration and secrets within your application."
+---
+
+## Exposing
+
+To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/guide/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/api/nuxt-config#runtimeconfig) option.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    // The private keys which are only available within server-side
+    apiSecret: '123',
+    // Keys within public, will be also exposed to the client-side
+    public: {
+      apiBase: '/api'
+    }
+  }
+})
+```
+
+When adding `apiBase` to the `runtimeConfig.public`, Nuxt adds it to each page payload. We can universally access `apiBase` in both server and browser.
+
+```ts
+const runtimeConfig = useRuntimeConfig()
+
+console.log(runtimeConfig.apiSecret)
+console.log(runtimeConfig.public.apiBase)
+```
+
+::tip
+Public runtime config is accessible in Vue templates with `$config.public`.
+::
+
+### Serialization
+
+Your runtime config will be serialized before being passed to Nitro. This means that anything that cannot be serialized and then deserialized (such as functions, Sets, Maps, and so on), should not be set in your `nuxt.config`.
+
+Instead of passing non-serializable objects or functions into your application from your `nuxt.config`, you can place this code in a Nuxt or Nitro plugin or middleware.
+
+### Environment Variables
+
+The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
+
+::note
+Nuxi CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.
+:read-more{to="/docs/guide/directory-structure/env"}
+::
+
+Runtime config values are **automatically replaced by matching environment variables at runtime**.
+
+There are two key requirements:
+
+1. Your desired variables must be defined in your `nuxt.config`. This ensures that arbitrary environment variables are not exposed to your application code.
+
+1. Only a specially-named environment variable can override a runtime config property. That is, an uppercase environment variable starting with `NUXT_` which uses `_` to separate keys and case changes.
+
+::warning
+Setting the default of `runtimeConfig` values to *differently named environment variables* (for example setting `myVar` to `process.env.OTHER_VARIABLE`) will only work during build-time and will break on runtime.
+It is advised to use environment variables that match the structure of your `runtimeConfig` object.
+::
+
+::tip{icon="i-lucide-video" to="https://youtu.be/_FYV5WfiWvs" target="_blank"}
+Watch a video from Alexander Lichter showcasing the top mistake developers make using runtimeConfig.
+::
+
+#### Example
+
+```ini [.env]
+NUXT_API_SECRET=api_secret_token
+NUXT_PUBLIC_API_BASE=https://nuxtjs.org
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    apiSecret: '', // can be overridden by NUXT_API_SECRET environment variable
+    public: {
+      apiBase: '', // can be overridden by NUXT_PUBLIC_API_BASE environment variable
+    }
+  },
+})
+```
+
+## Reading
+
+### Vue App
+
+Within the Vue part of your Nuxt app, you will need to call [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) to access the runtime config.
+
+::important
+The behavior is different between the client-side and server-side:
+
+- On client-side, only keys in `runtimeConfig.public` and `runtimeConfig.app` (which is used by Nuxt internally) are available, and the object is both writable and reactive.
+
+- On server-side, the entire runtime config is available, but it is read-only to avoid context sharing.
+::
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const config = useRuntimeConfig()
+
+console.log('Runtime config:', config)
+if (import.meta.server) {
+  console.log('API secret:', config.apiSecret)
+}
+</script>
+
+<template>
+  <div>
+    <div>Check developer console!</div>
+  </div>
+</template>
+```
+
+::caution
+**Security note:** Be careful not to expose runtime config keys to the client-side by either rendering them or passing them to `useState`.
+::
+
+### Plugins
+
+If you want to use the runtime config within any (custom) plugin, you can use [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) inside of your `defineNuxtPlugin` function.
+
+```ts [plugins/config.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig()
+
+  console.log('API base URL:', config.public.apiBase)
+});
+```
+
+### Server Routes
+
+You can access runtime config within the server routes as well using `useRuntimeConfig`.
+
+```ts [server/api/test.ts]
+export default defineEventHandler(async (event) => {
+  const { apiSecret } = useRuntimeConfig(event)
+  const result = await $fetch('https://my.api.com/test', {
+    headers: {
+      Authorization: `Bearer ${apiSecret}`
+    }
+  })
+  return result
+})
+```
+
+::note
+Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
+::
+
+## Typing Runtime Config
+
+Nuxt tries to automatically generate a typescript interface from provided runtime config using [unjs/untyped](https://github.com/unjs/untyped).
+
+But it is also possible to type your runtime config manually:
+
+```ts [index.d.ts]
+declare module 'nuxt/schema' {
+  interface RuntimeConfig {
+    apiSecret: string
+  }
+  interface PublicRuntimeConfig {
+    apiBase: string
+  }
+}
+// It is always important to ensure you import/export something when augmenting a type
+export {}
+```
+
+::note
+`nuxt/schema` is provided as a convenience for end-users to access the version of the schema used by Nuxt in their project. Module authors should instead augment `@nuxt/schema`.
+::

package/2.guide/3.going-further/11.nightly-release-channel.md

@@ -0,0 +1,68 @@
+---
+title: "Nightly Release Channel"
+description: "The nightly release channel allows using Nuxt built directly from the latest commits to the repository."
+---
+
+Nuxt lands commits, improvements, and bug fixes every day. You can opt in to test them earlier before the next release.
+
+After a commit is merged into the `main` branch of [nuxt/nuxt](https://github.com/nuxt/nuxt) and **passes all tests**, we trigger an automated npm release, using GitHub Actions.
+
+You can use these 'nightly' releases to beta test new features and changes.
+
+The build and publishing method and quality of these 'nightly' releases are the same as stable ones. The only difference is that you should often check the GitHub repository for updates. There is a slight chance of regressions not being caught during the review process and by the automated tests. Therefore, we internally use this channel to double-check everything before each release.
+
+::note
+Features that are only available on the nightly release channel are marked with an alert in the documentation.
+::
+
+::warning
+The `latest` nightly release channel is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now - be careful!
+
+You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.
+::
+
+## Opting In
+
+Update `nuxt` dependency inside `package.json`:
+
+```diff [package.json]
+{
+  "devDependencies": {
+--    "nuxt": "^3.0.0"
+++    "nuxt": "npm:nuxt-nightly@3x"
+  }
+}
+```
+
+Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb`) and reinstall dependencies.
+
+## Opting Out
+
+Update `nuxt` dependency inside `package.json`:
+
+```diff [package.json]
+{
+  "devDependencies": {
+--    "nuxt": "npm:nuxt-nightly@3x"
+++    "nuxt": "^3.0.0"
+  }
+}
+```
+
+Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb`) and reinstall dependencies.
+
+## Using Nightly `nuxi`
+
+::note
+All cli dependencies are bundled because of the building method for reducing `nuxi` package size. :br You can get dependency updates and CLI improvements using the nightly release channel.
+::
+
+To try the latest version of [nuxt/cli](https://github.com/nuxt/cli):
+
+```bash [Terminal]
+npx nuxi-nightly@latest [command]
+```
+
+::read-more{to="/docs/api/commands"}
+Read more about the available commands.
+::

package/2.guide/3.going-further/2.hooks.md

@@ -0,0 +1,98 @@
+---
+title: "Lifecycle Hooks"
+description: "Nuxt provides a powerful hooking system to expand almost every aspect using hooks."
+---
+
+::tip
+The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookable).
+::
+
+## Nuxt Hooks (Build Time)
+
+These hooks are available for [Nuxt Modules](/docs/guide/going-further/modules) and build context.
+
+### Within `nuxt.config.ts`
+
+```js [nuxt.config.ts]
+export default defineNuxtConfig({
+  hooks: {
+    close: () => { }
+  }
+})
+```
+
+### Within Nuxt Modules
+
+```js
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    nuxt.hook('close', async () => { })
+  }
+})
+```
+
+::read-more{to="/docs/api/advanced/hooks#nuxt-hooks-build-time"}
+Explore all available Nuxt hooks.
+::
+
+## App Hooks (Runtime)
+
+App hooks can be mainly used by [Nuxt Plugins](/docs/guide/directory-structure/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
+
+```js [plugins/test.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('page:start', () => {
+    /* your code goes here */
+  })
+})
+```
+
+::read-more{to="/docs/api/advanced/hooks#app-hooks-runtime"}
+Explore all available App hooks.
+::
+
+## Server Hooks (Runtime)
+
+These hooks are available for [server plugins](/docs/guide/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
+
+```js [~/server/plugins/test.ts]
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('render:html', (html, { event }) => {
+    console.log('render:html', html)
+    html.bodyAppend.push('<hr>Appended by custom plugin')
+  })
+
+  nitroApp.hooks.hook('render:response', (response, { event }) => {
+    console.log('render:response', response)
+  })
+})
+```
+
+::read-more{to="/docs/api/advanced/hooks#nitro-app-hooks-runtime-server-side"}
+Learn more about available Nitro lifecycle hooks.
+::
+
+## Additional Hooks
+
+You can add additional hooks by augmenting the types provided by Nuxt. This can be useful for modules.
+
+```ts
+import { HookResult } from "@nuxt/schema";
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'your-nuxt-runtime-hook': () => HookResult
+  }
+  interface NuxtHooks {
+    'your-nuxt-hook': () => HookResult
+  }
+}
+
+declare module 'nitropack' {
+  interface NitroRuntimeHooks {
+    'your-nitro-hook': () => void;
+  }
+}
+```