@nuxt/docs 0.0.0 → 3.17.0

package/5.community/5.framework-contribution.md

@@ -0,0 +1,142 @@
+---
+title: 'Framework'
+navigation.icon: i-lucide-github
+description: Some specific points about contributions to the framework repository.
+---
+
+Once you've read the [general contribution guide](/docs/community/contribution), here are some specific points to make about contributions to the [`nuxt/nuxt`](https://github.com/nuxt/nuxt) repository.
+
+## Monorepo Guide
+
+- `packages/kit`: Toolkit for authoring Nuxt Modules, published as [`@nuxt/kit`](https://npmjs.com/package/@nuxt/kit).
+- `packages/nuxt`: The core of Nuxt, published as [`nuxt`](https://npmjs.com/package/nuxt).
+- `packages/schema`: Cross-version Nuxt typedefs and defaults, published as [`@nuxt/schema`](https://npmjs.com/package/@nuxt/schema).
+- `packages/rspack`: The [Rspack](https://rspack.dev) bundler for Nuxt, published as [`@nuxt/rspack-builder`](https://npmjs.com/package/@nuxt/rspack-builder).
+- `packages/vite`: The [Vite](https://vite.dev) bundler for Nuxt, published as [`@nuxt/vite-builder`](https://npmjs.com/package/@nuxt/vite-builder).
+- `packages/webpack`: The [webpack](https://webpack.js.org) bundler for Nuxt, published as [`@nuxt/webpack-builder`](https://npmjs.com/package/@nuxt/webpack-builder).
+
+## Setup
+
+To contribute to Nuxt, you need to set up a local environment.
+
+1. [Fork](https://help.github.com/articles/fork-a-repo) the [`nuxt/nuxt`](https://github.com/nuxt/nuxt)  repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository) it to your local device.
+2. Ensure using the latest [Node.js](https://nodejs.org/en) (20.x)
+3. Enable [Corepack](https://github.com/nodejs/corepack) to have `pnpm` and `yarn`
+    ```bash [Terminal]
+    corepack enable
+    ```
+4. Run `pnpm install --frozen-lockfile` to Install the dependencies with pnpm:
+    ```bash [Terminal]
+    pnpm install --frozen-lockfile
+    ```
+    ::note
+    If you are adding a dependency, please use `pnpm add`. :br
+    The `pnpm-lock.yaml` file is the source of truth for all Nuxt dependencies.
+    ::
+5. Activate the passive development system
+    ```bash [Terminal]
+    pnpm dev:prepare
+    ```
+6. Check out a branch where you can work and commit your changes:
+    ```bash [Terminal]
+    git checkout -b my-new-branch
+    ```
+
+Then, test your changes against the [playground](#playground) and [test](#testing) your changes before submitting a pull request.
+
+### Playground
+
+While working on a pull request, you will likely want to check if your changes are working correctly.
+
+You can modify the example app in `playground/`, and run:
+
+```bash [Terminal]
+pnpm dev
+```
+
+::important
+Please make sure not to commit it to your branch, but it could be helpful to add some example code to your PR description. This can help reviewers and other Nuxt users understand the feature you've built in-depth.
+::
+
+### Testing
+
+Every new feature should have a corresponding unit test (if possible). The `test/` directory in this repository is currently a work in progress, but do your best to create a new test following the example of what's already there.
+
+Before creating a PR or marking it as ready-to-review, ensure that all tests pass by running:
+
+```bash [Terminal]
+pnpm test
+```
+
+### Linting
+
+You might have noticed already that we use ESLint to enforce a coding standard.
+
+Before committing your changes, to verify that the code style is correct, run:
+
+```bash [Terminal]
+pnpm lint
+```
+
+::note
+You can use `pnpm lint --fix` to fix most of the style changes. :br
+If there are still errors left, you must correct them manually.
+::
+
+### Documentation
+
+If you are adding a new feature or refactoring or changing the behavior of Nuxt in any other manner, you'll likely want to document the changes. Please include any changes to the docs in the same PR. You don't have to write documentation up on the first commit (but please do so as soon as your pull request is mature enough).
+
+::important
+Make sure to make changes according to the [Documentation Style Guide](/docs/community/contribution#documentation-style-guide).
+::
+
+### Final Checklist
+
+When submitting your PR, there is a simple template that you have to fill out. Please tick all appropriate "answers" in the checklists.
+
+## Documentation Guide
+
+If you spot an area where we can improve documentation or error messages, please do open a PR - even if it's just to fix a typo!
+
+::important
+Make sure to make changes according to the [Documentation Style Guide](/docs/community/contribution#documentation-style-guide).
+::
+
+### Quick Edits
+
+If you spot a typo or want to rephrase a sentence, you can click on the **Edit this page** link located on the right aside in the **Community** section.
+
+Make the change directly in the GitHub interface and open a Pull Request.
+
+### Longer Edits
+
+The documentation content is inside the `docs/` directory of the [nuxt/nuxt](https://github.com/nuxt/nuxt) repository and written in markdown.
+
+::note
+To preview the docs locally, follow the steps on [nuxt/nuxt.com](https://github.com/nuxt/nuxt.com) repository.
+::
+
+::note
+We recommend that you install the [MDC extension](https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc) for VS Code.
+::
+
+### Linting Docs
+
+Documentation is linted using [MarkdownLint](https://github.com/DavidAnson/markdownlint) and [case police](https://github.com/antfu/case-police) to keep the documentation cohesive.
+
+```bash [Terminal]
+pnpm lint:docs
+```
+
+::note
+You can also run `pnpm lint:docs:fix` to highlight and resolve any lint issues.
+::
+
+### Open a PR
+
+Please make sure your PR title adheres to the [conventional commits](https://www.conventionalcommits.org) guidelines.
+
+```bash [Example of PR title]
+docs: update the section about the nuxt.config.ts file
+```

package/5.community/6.roadmap.md

@@ -0,0 +1,79 @@
+---
+title: 'Roadmap'
+description: 'Nuxt is constantly evolving, with new features and modules being added all the time.'
+navigation.icon: i-lucide-map
+---
+
+::read-more{to="/blog"}
+See our blog for the latest framework and ecosystem announcements.
+::
+
+## Status Reports
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/13653" target="_blank"}
+Documentation Progress
+::
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/discussions/16119" target="_blank"}
+Rendering Optimizations: Today and Tomorrow
+::
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/image/discussions/563" target="_blank"}
+Nuxt Image: Performance and Status
+::
+
+## Roadmap
+
+In roadmap below are some features we are planning or working on at the moment.
+
+::tip
+Check [Discussions](https://github.com/nuxt/nuxt/discussions) and [RFCs](https://github.com/nuxt/nuxt/discussions/categories/rfcs) for more upcoming features and ideas.
+::
+
+Milestone    | Expected date | Notes                                                                  | Description
+-------------|---------------|------------------------------------------------------------------------|-----------------------
+SEO & PWA    | 2024          | [nuxt/nuxt#18395](https://github.com/nuxt/nuxt/discussions/18395)      | Migrating from [nuxt-community/pwa-module](https://github.com/nuxt-community/pwa-module) for built-in SEO utils and service worker support
+Assets       | 2024          | [nuxt/nuxt#22012](https://github.com/nuxt/nuxt/discussions/22012)      | Allow developers and modules to handle loading third-party assets.
+Translations | -             | [nuxt/translations#4](https://github.com/nuxt/translations/discussions/4) ([request access](https://github.com/nuxt/nuxt/discussions/16054)) | A collaborative project for a stable translation process for Nuxt docs. Currently pending for ideas and documentation tooling support (content v2 with remote sources).
+
+## Core Modules Roadmap
+
+In addition to the Nuxt framework, there are modules that are vital for the ecosystem. Their status will be updated below.
+
+Module                              | Status              | Nuxt Support | Repository | Description
+------------------------------------|---------------------|--------------|------------|-------------------
+[Scripts](https://scripts.nuxt.com) | Public Beta         | 3.x          | [nuxt/scripts](https://github.com/nuxt/scripts) | Easy 3rd party script management.
+Auth Utils                          | Planned             | 3.x          | `nuxt/auth-utils` to be announced | The temporary repository [atinux/nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils) is available while awaiting its official integration into Nuxt via RFC.
+A11y                                | Planned             | 3.x          | `nuxt/a11y` to be announced | Accessibility hinting and utilities [nuxt/nuxt#23255](https://github.com/nuxt/nuxt/issues/23255)
+Hints                               | Planned             | 3.x          | `nuxt/hints` to be announced | Guidance and suggestions for enhancing development practices.
+
+## Release Cycle
+
+Since January 2023, we've adopted a consistent release cycle for Nuxt, following [semver](https://semver.org). We aim for major framework releases every year, with an expectation of patch releases every week or so and minor releases every month or so. They should never contain breaking changes except within options clearly marked as `experimental`.
+
+### Ongoing Support for Nuxt
+
+Going forward from v3, we commit to support each major version of Nuxt for a minimum of a year after the last release, and to providing an upgrade path for current users at that point.
+
+### Current Packages
+
+The current active version of [Nuxt](https://nuxt.com) is **v3** which is available as `nuxt` on npm with the `latest` tag.
+
+Nuxt 2 is in maintenance mode and is available on npm with the `2x` tag. It will reach End of Life (EOL) on June 30, 2024.
+
+Each active version has its own nightly releases which are generated automatically. For more about enabling the Nuxt nightly release channel, see [the nightly release channel docs](/docs/guide/going-further/nightly-release-channel).
+
+Release                                 |                                                                                                  | Initial release | End Of Life  | Docs
+----------------------------------------|---------------------------------------------------------------------------------------------------|-----------------|--------------|-------
+**4.x** (scheduled)                     |                                                                                           | approximately 1 month after release of nitro v3             |              |  
+**3.x** (stable)           | <a href="https://npmjs.com/package/nuxt"><img alt="Nuxt latest 3.x version" src="https://flat.badgen.net/npm/v/nuxt?label=" class="not-prose"></a>            | 2022-11-16      | TBA          | [nuxt.com](/docs)
+**2.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 2.x version" src="https://flat.badgen.net/npm/v/nuxt/2x?label=" class="not-prose"></a>         | 2018-09-21      | 2024-06-30   | [v2.nuxt.com](https://v2.nuxt.com/docs)
+**1.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 1.x version" src="https://flat.badgen.net/npm/v/nuxt/1x?label=" class="not-prose"></a>         | 2018-01-08      | 2019-09-21 | &nbsp;
+
+### Support Status
+
+Status      | Description
+------------|----------------------------------------------------------------------------------
+Unsupported | This version is not maintained any more and will not receive security patches
+Maintenance | This version will only receive security patches
+Stable      | This version is being developed for and will receive security patches
+Development | This version could be unstable
+Scheduled   | This version does not exist yet but is planned

package/5.community/7.changelog.md

@@ -0,0 +1,92 @@
+---
+title: 'Releases'
+description: Discover the latest releases of Nuxt & Nuxt official modules.
+navigation.icon: i-lucide-bell-dot
+---
+
+::card-group
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/nuxt
+  to: https://github.com/nuxt/nuxt/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt framework releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/cli
+  to: https://github.com/nuxt/cli/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt CLI (`nuxi`) releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/content
+  to: https://github.com/nuxt/content/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt Content releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/devtools
+  to: https://github.com/nuxt/devtools/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt DevTools releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/fonts
+  to: https://github.com/nuxt/fonts/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt Fonts releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/image
+  to: https://github.com/nuxt/image/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt Image releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/scripts
+  to: https://github.com/nuxt/scripts/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt Scripts releases.
+  ::
+  ::card
+  ---
+  icon: i-simple-icons-github
+  title: nuxt/ui
+  to: https://github.com/nuxt/ui/releases
+  target: _blank
+  ui.icon.base: text-black dark:text-white
+  ---
+  Nuxt UI releases.
+  ::
+::
+
+::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt" target="_blank"}
+Discover the `nuxt` organization on GitHub
+::

package/6.bridge/.navigation.yml

@@ -0,0 +1,3 @@
+titleTemplate: 'Migrate to Nuxt Bridge: %s'
+title: 'Migrate to Nuxt Bridge'
+icon: i-lucide-ship

package/6.bridge/1.overview.md

@@ -0,0 +1,137 @@
+---
+title: Overview
+description: Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3.
+---
+
+::note
+If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 Installation](/docs/getting-started/introduction).
+::
+
+::warning
+Nuxt Bridge provides identical features to Nuxt 3 ([docs](/docs/guide/concepts/auto-imports)) but there are some limitations, notably that [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch) composables are not available. Please read the rest of this page for details.
+::
+
+Bridge is a forward-compatibility layer that allows you to experience many of the new Nuxt 3 features by simply installing and enabling a Nuxt module.
+
+Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 and you can gradually proceed with the transition to Nuxt 3.
+
+## First Step
+
+### Upgrade Nuxt 2
+
+Make sure your dev server (`nuxt dev`) isn't running, remove any package lock files (`package-lock.json` and `yarn.lock`), and install the latest Nuxt 2 version:
+
+```diff [package.json]
+- "nuxt": "^2.16.3"
++ "nuxt": "^2.17.3"
+```
+
+Then, reinstall your dependencies:
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npm install
+```
+
+```bash [yarn]
+yarn install
+```
+
+```bash [pnpm]
+pnpm install
+```
+
+```bash [bun]
+bun install
+```
+
+::
+
+::note
+Once the installation is complete, make sure both development and production builds are working as expected before proceeding.
+::
+
+### Install Nuxt Bridge
+
+Install `@nuxt/bridge` and `nuxi` as development dependencies:
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npm install -D @nuxt/bridge nuxi
+```
+
+```bash [yarn]
+yarn add --dev @nuxt/bridge nuxi
+```
+
+```bash [pnpm]
+pnpm add -D @nuxt/bridge nuxi
+```
+
+```bash [bun]
+bun add -D @nuxt/bridge nuxi
+```
+
+::
+
+### Update `nuxt.config`
+
+Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in your config file. It will soon be deprecated and unsupported.
+
+You can use static `import`, dynamic `import()` and `export default` instead. Using TypeScript by renaming to [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) is also possible and recommended.
+
+```ts [nuxt.config.ts]
+import { defineNuxtConfig } from '@nuxt/bridge'
+
+export default defineNuxtConfig({
+  bridge: false
+})
+```
+
+### Update Commands
+
+The `nuxt` command should now be changed to the `nuxt2` command.
+
+```diff
+{
+  "scripts": {
+-   "dev": "nuxt",
++   "dev": "nuxt2",
+-   "build": "nuxt build",
++   "build": "nuxt2 build",
+-   "start": "nuxt start",
++   "start": "nuxt2 start"
+  }
+}
+```
+
+Try running `nuxt2` once here. You will see that the application works as before.
+
+(If 'bridge' is set to false, your application will operate without any changes as before.)
+
+## Upgrade Steps
+
+With Nuxt Bridge, the migration to Nuxt 3 can proceed in steps.
+The below `Upgrade Steps` does not need to be done all at once.
+
+- [TypeScript](/docs/bridge/typescript)
+
+- [Migrate Legacy Composition API](/docs/bridge/bridge-composition-api)
+
+- [Plugins and Middleware](/docs/bridge/plugins-and-middleware)
+
+- [Migrate New Composition API](/docs/bridge/nuxt3-compatible-api)
+
+- [Meta Tags](/docs/bridge/meta)
+
+- [Runtime Config](/docs/bridge/runtime-config)
+
+- [Nitro](/docs/bridge/nitro)
+
+- [Vite](/docs/bridge/vite)
+
+## Migrate from CommonJS to ESM
+
+Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/docs/guide/concepts/esm) for more info and upgrading.

package/6.bridge/10.configuration.md

@@ -0,0 +1,96 @@
+---
+title: Configuration
+description: 'Learn how to configure Nuxt Bridge to your own needs.'
+---
+
+## Feature Flags
+
+You can optionally disable some features from bridge or opt-in to less stable ones. In normal circumstances, it is always best to stick with defaults!
+
+You can check [bridge/src/module.ts](https://github.com/nuxt/bridge/blob/main/packages/bridge/src/module.ts) for latest defaults.
+
+```ts [nuxt.config.ts]
+import { defineNuxtConfig } from '@nuxt/bridge'
+export default defineNuxtConfig({
+  bridge: {
+
+    // -- Opt-in features --
+
+    // Use Vite as the bundler instead of webpack 4
+    // vite: true,
+
+    // Enable Nuxt 3 compatible useHead
+    // meta: true,
+
+    // Enable definePageMeta macro
+    // macros: {
+    //   pageMeta: true
+    // },
+
+    // Enable transpiling TypeScript with esbuild
+    // typescript: {
+    //   esbuild: true
+    // },
+
+    // -- Default features --
+
+    // Use legacy server instead of Nitro
+    // nitro: false,
+
+    // Disable Nuxt 3 compatible `nuxtApp` interface
+    // app: false,
+
+    // Disable Composition API support
+    // capi: false,
+
+    // ... or just disable legacy Composition API support
+    // capi: {
+    //   legacy: false
+    // },
+
+    // Do not transpile modules
+    // transpile: false,
+
+    // Disable <script setup> support
+    // scriptSetup: false,
+
+    // Disable composables auto importing
+    // imports: false,
+
+    // Do not warn about module incompatibilities
+    // constraints: false
+  },
+
+  vite: {
+    // Config for Vite
+  }
+})
+```
+
+## Migration of each option
+
+### router.base
+
+```diff
+export default defineNuxtConfig({
+- router: {
+-   base: '/my-app/'
+- }
++ app: {
++   baseURL: '/my-app/'
++ }
+})
+```
+
+### build.publicPath
+
+```diff
+export default defineNuxtConfig({
+- build: {
+-   publicPath: 'https://my-cdn.net'
+- }
++ app: {
++   cdnURL: 'https://my-cdn.net'
++ }
+})
+```

package/6.bridge/2.typescript.md

@@ -0,0 +1,46 @@
+---
+title: TypeScript
+description: 'Learn how to use TypeScript with Nuxt Bridge.'
+---
+
+## Remove Modules
+
+- Remove `@nuxt/typescript-build`: Bridge enables same functionality
+- Remove `@nuxt/typescript-runtime` and `nuxt-ts`: Nuxt 2 has built-in runtime support
+
+### Set `bridge.typescript`
+
+```ts
+import { defineNuxtConfig } from '@nuxt/bridge'
+
+export default defineNuxtConfig({
+  bridge: {
+    typescript: true,
+    nitro: false // If migration to Nitro is complete, set to true
+  }
+})
+```
+
+## Update `tsconfig.json`
+
+If you are using TypeScript, you can edit your `tsconfig.json` to benefit from auto-generated Nuxt types:
+
+```diff [tsconfig.json]
+{
++ "extends": "./.nuxt/tsconfig.json",
+  "compilerOptions": {
+    ...
+  }
+}
+```
+
+::note
+As `.nuxt/tsconfig.json` is generated and not checked into version control, you'll need to generate that file before running your tests. Add `nuxi prepare` as a step before your tests, otherwise you'll see `TS5083: Cannot read file '~/.nuxt/tsconfig.json'`
+::
+
+::note
+Keep in mind that all options extended from `./.nuxt/tsconfig.json` will be overwritten by the options defined in your `tsconfig.json`.
+Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead TypeScript to not factor in the module resolutions from `./.nuxt/tsconfig.json`. This can lead to module resolutions such as `#imports` not being recognized.
+
+In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the `alias` property within your `nuxt.config`. `nuxi` will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
+::