Hello world
+ + ``` + +5. Create a simple unit test for this newly created component `~/components/HelloWorld.spec.ts` + + ```ts twoslash + import { describe, it, expect } from 'vitest' + import { mount } from '@vue/test-utils' + + import HelloWorld from './HelloWorld.vue' + + describe('HelloWorld', () => { + it('component renders Hello world properly', () => { + const wrapper = mount(HelloWorld) + expect(wrapper.text()).toContain('Hello world') + }) + }) + ``` + +6. Run vitest command + + ::code-group + ```bash [yarn] + yarn test + ``` + ```bash [npm] + npm run test + ``` + ```bash [pnpm] + pnpm run test + ``` + ```bash [bun] + bun run test + ``` + :: + +Congratulations, you're all set to start unit testing with `@vue/test-utils` in Nuxt! Happy testing! + ## End-To-End Testing -For end-to-end testing, we support [Vitest](https://github.com/vitest-dev/vitest) and [Jest](https://jestjs.io) as test runners. +For end-to-end testing, we support [Vitest](https://github.com/vitest-dev/vitest), [Jest](https://jestjs.io), [Cucumber](https://cucumber.io/) and [Playwright](https://playwright.dev/) as test runners. ### Setup @@ -454,7 +563,7 @@ Please use the options below for the `setup` method. - `type`: The type of browser to launch - either `chromium`, `firefox` or `webkit` - `launch`: `object` of options that will be passed to playwright when launching the browser. See [full API reference](https://playwright.dev/docs/api/class-browsertype#browser-type-launch). - `runner`: Specify the runner for the test suite. Currently, [Vitest](https://vitest.dev) is recommended. - - Type: `'vitest' | 'jest'` + - Type: `'vitest' | 'jest' | 'cucumber'` - Default: `'vitest'` ### APIs @@ -493,11 +602,11 @@ const pageUrl = url('/page') ### Testing in a Browser -We provide built-in support using Playwright within `@nuxt/test-utils`, but you can also use other test runners for end-to-end browser testing. +We provide built-in support using Playwright within `@nuxt/test-utils`, either programmatically or via the Playwright test runner. #### `createPage(url)` -You can create a configured Playwright browser instance, and (optionally) point it at a path from the running server. You can find out more about the API methods available from [in the Playwright documentation](https://playwright.dev/docs/api/class-page). +Within `vitest`, `jest` or `cucumber`, you can create a configured Playwright browser instance with `createPage`, and (optionally) point it at a path from the running server. You can find out more about the API methods available from [in the Playwright documentation](https://playwright.dev/docs/api/class-page). ```ts twoslash import { createPage } from '@nuxt/test-utils/e2e' @@ -505,3 +614,70 @@ import { createPage } from '@nuxt/test-utils/e2e' const page = await createPage('/page') // you can access all the Playwright APIs from the `page` variable ``` + +#### Testing with Playwright Test Runner + +We also provide first-class support for testing Nuxt within [the Playwright test runner](https://playwright.dev/docs/intro). + +::code-group +```bash [yarn] +yarn add --dev @playwright/test @nuxt/test-utils +``` +```bash [npm] +npm i --save-dev @playwright/test @nuxt/test-utils +``` +```bash [pnpm] +pnpm add -D @playwright/test @nuxt/test-utils +``` +```bash [bun] +bun add --dev @playwright/test @nuxt/test-utils +``` +:: + +You can provide global Nuxt configuration, with the same configuration details as the `setup()` function mentioned earlier in this section. + +```ts [playwright.config.ts] +import { fileURLToPath } from 'node:url' +import { defineConfig, devices } from '@playwright/test' +import type { ConfigOptions } from '@nuxt/test-utils/playwright' + +export default defineConfig
+
+
+
+π For more details, see the [PR implementing this change](https://github.com/nuxt/nuxt/pull/27029).
+
+##### Reasons for Change
+
+1. **Performance** - placing all your code in the root of your repo causes issues with `.git/` and `node_modules/` folders being scanned/included by FS watchers which can significantly delay startup on non-Mac OSes.
+1. **IDE type-safety** - `server/` and the rest of your app are running in two entirely different contexts with different global imports available, and making sure `server/` isn't _inside_ the same folder as the rest of your app is a big first step to ensuring you get good auto-completes in your IDE.
+
+##### Migration Steps
+
+1. Create a new directory called `app/`.
+1. Move your `assets/`, `components/`, `composables/`, `layouts/`, `middleware/`, `pages/`, `plugins/` and `utils/` folders under it, as well as `app.vue`, `error.vue`, `app.config.ts`. If you have an `app/router-options.ts` or `app/spa-loading-template.html`, these paths remain the same.
+1. Make sure your `nuxt.config.ts`, `modules/`, `public/` and `server/` folders remain outside the `app/` folder, in the root of your project.
+
+However, migration is _not required_. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you _already_ have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.
+
+You can also force a v3 folder structure with the following configuration:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ // This reverts the new srcDir default from `app` back to your root directory
+ srcDir: '.',
+ // This specifies the directory prefix for `app/router.options.ts` and `app/spa-loading-template.html`
+ dir: {
+ app: 'app'
+ }
+})
+```
+
+#### Shared Prerender Data
+
+π¦ **Impact Level**: Medium
+
+##### What Changed
+
+We enabled a previously experimental feature to share data from `useAsyncData` and `useFetch` calls, across different pages. See [original PR](https://github.com/nuxt/nuxt/pull/24894).
+
+##### Reasons for Change
+
+This feature automatically shares payload _data_ between pages that are prerendered. This can result in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and fetch the same data in different pages.
+
+For example, if your site requires a `useFetch` call for every page (for example, to get navigation data for a menu, or site settings from a CMS), this data would only be fetched once when prerendering the first page that uses it, and then cached for use when prerendering other pages.
+
+##### Migration Steps
+
+Make sure that any unique key of your data is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch` should do this automatically for you.)
+
+```ts [app/pages/test/[slug\\].vue]
+// This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
+// to the data fetched, but Nuxt can't know that because it's not reflected in the key.
+const route = useRoute()
+const { data } = await useAsyncData(async () => {
+ return await $fetch(`/api/my-page/${route.params.slug}`)
+})
+// Instead, you should use a key that uniquely identifies the data fetched.
+const { data } = await useAsyncData(route.params.slug, async () => {
+ return await $fetch(`/api/my-page/${route.params.slug}`)
+})
+```
+
+Alternatively, you can disable this feature with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ experimental: {
+ sharedPrerenderData: false
+ }
+})
+```
+
+#### Default `data` and `error` values in `useAsyncData` and `useFetch`
+
+π¦ **Impact Level**: Minimal
+
+##### What Changed
+
+`data` and `error` objects returned from `useAsyncData` will now default to `undefined`.
+
+##### Reasons for Change
+
+Previously `data` was initialized to `null` but reset in `clearNuxtData` to `undefined`. `error` was initialized to `null`. This change is to bring greater consistency.
+
+##### Migration Steps
+
+If you encounter any issues you can revert back to the previous behavior with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ experimental: {
+ defaults: {
+ useAsyncData: {
+ value: 'null',
+ errorValue: 'null'
+ }
+ }
+ }
+})
+```
+
+Please report an issue if you are doing this, as we do not plan to keep this as configurable.
+
+#### Removal of deprecated `boolean` values for `dedupe` option when calling `refresh` in `useAsyncData` and `useFetch`
+
+π¦ **Impact Level**: Minimal
+
+##### What Changed
+
+Previously it was possible to pass `dedupe: boolean` to `refresh`. These were aliases of `cancel` (`true`) and `defer` (`false`).
+
+```ts twoslash [app.vue]
+const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt 3!' }))
+
+async function refreshData () {
+ await refresh({ dedupe: true })
+}
+```
+
+##### Reasons for Change
+
+These aliases were removed, for greater clarity.
+
+The issue came up when adding `dedupe` as an option to `useAsyncData`, and we removed the boolean values as they ended up being _opposites_.
+
+`refresh({ dedupe: false })` meant 'do not _cancel_ existing requests in favour of this new one'. But passing `dedupe: true` within the options of `useAsyncData` means 'do not make any new requests if there is an existing pending request.' (See [PR](https://github.com/nuxt/nuxt/pull/24564#pullrequestreview-1764584361).)
+
+##### Migration Steps
+
+The migration should be straightforward:
+
+```diff
+ const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt 3!' }))
+
+ async function refreshData () {
+- await refresh({ dedupe: true })
++ await refresh({ dedupe: 'cancel' })
+
+- await refresh({ dedupe: false })
++ await refresh({ dedupe: 'defer' })
+ }
+```
+
+#### Respect defaults when clearing `data` in `useAsyncData` and `useFetch`
+
+π¦ **Impact Level**: Minimal
+
+##### What Changed
+
+If you provide a custom `default` value for `useAsyncData`, this will now be used when calling `clear` or `clearNuxtData` and it will be reset to its default value rather than simply unset.
+
+##### Reasons for Change
+
+Often users set an appropriately empty value, such as an empty array, to avoid the need to check for `null`/`undefined` when iterating over it. This should be respected when resetting/clearing the data.
+
+##### Migration Steps
+
+If you encounter any issues you can revert back to the previous behavior, for now, with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ experimental: {
+ resetAsyncDataToUndefined: true,
+ }
+})
+```
+
+Please report an issue if you are doing so, as we do not plan to keep this as configurable.
+
+#### Shallow Data Reactivity in `useAsyncData` and `useFetch`
+
+π¦ **Impact Level**: Minimal
+
+The `data` object returned from `useAsyncData`, `useFetch`, `useLazyAsyncData` and `useLazyFetch` is now a `shallowRef` rather than a `ref`.
+
+##### What Changed
+
+When new data is fetched, anything depending on `data` will still be reactive because the entire object is replaced. But if your code changes a property _within_ that data structure, this will not trigger any reactivity in your app.
+
+##### Reasons for Change
+
+This brings a **significant** performance improvement for deeply nested objects and arrays because Vue does not need to watch every single property/array for modification. In most cases, `data` should also be immutable.
+
+##### Migration Steps
+
+In most cases, no migration steps are required, but if you rely on the reactivity of the data object then you have two options:
+
+1. You can granularly opt in to deep reactivity on a per-composable basis:
+ ```diff
+ - const { data } = useFetch('/api/test')
+ + const { data } = useFetch('/api/test', { deep: true })
+ ```
+1. You can change the default behavior on a project-wide basis (not recommended):
+ ```ts twoslash [nuxt.config.ts]
+ export default defineNuxtConfig({
+ experimental: {
+ defaults: {
+ useAsyncData: {
+ deep: true
+ }
+ }
+ }
+ })
+ ```
+
+#### Absolute Watch Paths in `builder:watch`
+
+π¦ **Impact Level**: Minimal
+
+##### What Changed
+
+The Nuxt `builder:watch` hook now emits a path which is absolute rather than relative to your project `srcDir`.
+
+##### Reasons for Change
+
+This allows us to support watching paths which are outside your `srcDir`, and offers better support for layers and other more complex patterns.
+
+##### Migration Steps
+
+We have already proactively migrated the public Nuxt modules which we are aware use this hook. See [issue #25339](https://github.com/nuxt/nuxt/issues/25339).
+
+However, if you are a module author using the `builder:watch` hook and wishing to remain backwards/forwards compatible, you can use the following code to ensure that your code works the same in both Nuxt v3 and Nuxt v4:
+
+ ```diff
++ import { relative, resolve } from 'node:fs'
+ // ...
+ nuxt.hook('builder:watch', async (event, path) => {
++ path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
+ // ...
+ })
+```
+
+#### Directory index scanning
+
+π¦ **Impact Level**: Medium
+
+##### What Changed
+
+Child folders in your `middleware/` folder are also scanned for `index` files and these are now also registered as middleware in your project.
+
+##### Reasons for Change
+
+Nuxt scans a number of folders automatically, including `middleware/` and `plugins/`.
+
+Child folders in your `plugins/` folder are scanned for `index` files and we wanted to make this behavior consistent between scanned directories.
+
+##### Migration Steps
+
+Probably no migration is necessary but if you wish to revert to previous behavior you can add a hook to filter out these middleware:
+
+```ts
+export default defineNuxtConfig({
+ hooks: {
+ 'app:resolve'(app) {
+ app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
+ }
+ }
+})
+```
+
+#### Template Compilation Changes
+
+π¦ **Impact Level**: Minimal
+
+##### What Changed
+
+Previously, Nuxt used `lodash/template` to compile templates located on the file system using the `.ejs` file format/syntax.
+
+In addition, we provided some template utilities (`serialize`, `importName`, `importSources`) which could be used for code-generation within these templates, which are now being removed.
+
+##### Reasons for Change
+
+In Nuxt v3 we moved to a 'virtual' syntax with a `getContents()` function which is much more flexible and performant.
+
+In addition, `lodash/template` has had a succession of security issues. These do not really apply to Nuxt projects because it is being used at build-time, not runtime, and by trusted code. However, they still appear in security audits. Moreover, `lodash` is a hefty dependency and is unused by most projects.
+
+Finally, providing code serialization functions directly within Nuxt is not ideal. Instead, we maintain projects like [unjs/knitwork](http://github.com/unjs/knitwork) which can be dependencies of your project, and where security issues can be reported/resolved directly without requiring an upgrade of Nuxt itself.
+
+##### Migration Steps
+
+We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:
+
+* Moving your string interpolation logic directly into `getContents()`.
+* Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
+* Continuing to use `lodash`, as a dependency of _your_ project rather than Nuxt:
+
+```diff
++ import { readFileSync } from 'node:fs'
++ import { template } from 'lodash-es'
+ // ...
+ addTemplate({
+ fileName: 'appinsights-vue.js'
+ options: { /* some options */ },
+- src: resolver.resolve('./runtime/plugin.ejs'),
++ getContents({ options }) {
++ const contents = readFileSync(resolver.resolve('./runtime/plugin.ejs'), 'utf-8')
++ return template(contents)({ options })
++ },
+ })
+```
+
+Finally, if you are using the template utilities (`serialize`, `importName`, `importSources`), you can replace them as follows with utilities from `knitwork`:
+
+```ts
+import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'
+
+const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"{(.+)}"(?=,?$)/gm, r => JSON.parse(r).replace(/^{(.*)}$/, '$1'))
+
+const importSources = (sources: string | string[], { lazy = false } = {}) => {
+ return toArray(sources).map((src) => {
+ if (lazy) {
+ return `const ${genSafeVariableName(src)} = ${genDynamicImport(src, { comment: `webpackChunkName: ${JSON.stringify(src)}` })}`
+ }
+ return genImport(src, genSafeVariableName(src))
+ }).join('\n')
+}
+
+const importName = genSafeVariableName
+```
+
+#### Removal of Experimental Features
+
+π¦ **Impact Level**: Minimal
+
+##### What Changed
+
+Four experimental features are no longer configurable in Nuxt 4:
+
+* `treeshakeClientOnly` will be `true` (default since v3.0)
+* `configSchema` will be `true` (default since v3.3)
+* `polyfillVueUseHead` will be `false` (default since v3.4)
+* `respectNoSSRHeader` will be `false` (default since v3.4)
+
+##### Reasons for Change
+
+These options have been set to their current values for some time and we do not have a reason to believe that they need to remain configurable.
+
+##### Migration Steps
+
+* `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
+
+* `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
## Nuxt 2 vs Nuxt 3
@@ -26,7 +470,7 @@ In the table below, there is a quick comparison between 3 versions of Nuxt:
Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3
-------------------------|-----------------|------------------|---------
Vue | 2 | 2 | 3
-Stability | π Stable | π Semi-stable | π Stable
+Stability | π Stable | π Stable | π Stable
Performance | π Fast | βοΈ Faster | π Fastest
Nitro Engine | β | β
| β
ESM support | π Partial | π Better | β
diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.md
index f7a4d317ac..1af58ad887 100644
--- a/docs/1.getting-started/2.installation.md
+++ b/docs/1.getting-started/2.installation.md
@@ -6,14 +6,14 @@ navigation.icon: i-ph-play-duotone
## Play Online
-You can start playing with Nuxt 3 in your browser using our online sandboxes:
+If you just want to play around with Nuxt in your browser without setting up a project, you can use one of our online sandboxes:
::card-group
:card{title="Open on StackBlitz" icon="i-simple-icons-stackblitz" to="https://nuxt.new/s/v3" target="_blank"}
:card{title="Open on CodeSandbox" icon="i-simple-icons-codesandbox" to="https://nuxt.new/c/v3" target="_blank"}
::
-Start with one of our starters and themes directly by opening [nuxt.new](https://nuxt.new).
+Or follow the steps below to set up a new Nuxt project on your computer.
## New Project
@@ -22,7 +22,7 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/
#### Prerequisites
- **Node.js** - [`v18.0.0`](https://nodejs.org/en) or newer
-- **Text editor** - We recommend [Visual Studio Code](https://code.visualstudio.com/) with the [Volar Extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
+- **Text editor** - We recommend [Visual Studio Code](https://code.visualstudio.com/) with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously known as Volar)
- **Terminal** - In order to run Nuxt commands
::note
@@ -30,17 +30,6 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/
:summary[Additional notes for an optimal setup:]
- **Node.js**: Make sure to use an even numbered version (18, 20, etc)
- **Nuxtr**: Install the community-developed [Nuxtr extension](https://marketplace.visualstudio.com/items?itemName=Nuxtr.nuxtr-vscode)
- - **Volar**: Either enable [**Take Over Mode**](https://vuejs.org/guide/typescript/overview.html#volar-takeover-mode) (recommended) or add the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin)
-
- If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files in your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file:
-
- ```ts twoslash [nuxt.config.ts]
- export default defineNuxtConfig({
- typescript: {
- shim: false
- }
- })
- ```
::
::
@@ -62,6 +51,10 @@ bunx nuxi@latest init An example v4 folder structure.
+ +```sh +.output/ +.nuxt/ +app/ + assets/ + components/ + composables/ + layouts/ + middleware/ + pages/ + plugins/ + utils/ + app.config.ts + app.vue + router.options.ts +modules/ +node_modules/ +public/ +server/ + api/ + middleware/ + plugins/ + routes/ + utils/ +nuxt.config.ts +``` + +
+
+
+
+
+```
+
```vue [layouts/default.vue]
diff --git a/docs/1.getting-started/4.styling.md b/docs/1.getting-started/4.styling.md
index b2437a9cef..aac7cc8166 100644
--- a/docs/1.getting-started/4.styling.md
+++ b/docs/1.getting-started/4.styling.md
@@ -113,7 +113,8 @@ export default defineNuxtConfig({
head: {
link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }]
}
-}})
+ }
+})
```
### Dynamically Adding Stylesheets
@@ -153,15 +154,15 @@ To use a preprocessor like SCSS, Sass, Less or Stylus, install it first.
::code-group
```bash [Sass & SCSS]
-npm install sass
+npm install -D sass
```
```bash [Less]
-npm install less
+npm install -D less
```
```bash [Stylus]
-npm install stylus
+npm install -D stylus
```
::
@@ -243,7 +244,7 @@ Nuxt uses Vite by default. If you wish to use webpack instead, refer to each pre
## Single File Components (SFC) Styling
-One of the best things about Vue and SFC is how great it is at naturally dealing with styling. You can directly write CSS or preprocessor code in the style block of your components file, therefore you will have fantastic developer experience without having to use something like CSS-in-JS. However if you wish to use CSS-in-JS, you can find 3rd party libraries and modules that support it, such as [pinceau](https://pinceau.dev).
+One of the best things about Vue and SFC is how great it is at naturally dealing with styling. You can directly write CSS or preprocessor code in the style block of your components file, therefore you will have fantastic developer experience without having to use something like CSS-in-JS. However if you wish to use CSS-in-JS, you can find 3rd party libraries and modules that support it, such as [pinceau](https://github.com/Tahul/pinceau).
You can refer to the [Vue docs](https://vuejs.org/api/sfc-css-features.html) for a comprehensive reference about styling components in SFC.
@@ -421,7 +422,7 @@ For proper syntax highlighting in SFC, you can use the postcss lang attribute.
```vue
```
@@ -430,7 +431,7 @@ By default, Nuxt comes with the following plugins already pre-configured:
- [postcss-import](https://github.com/postcss/postcss-import): Improves the `@import` rule
- [postcss-url](https://github.com/postcss/postcss-url): Transforms `url()` statements
- [autoprefixer](https://github.com/postcss/autoprefixer): Automatically adds vendor prefixes
-- [cssnano](https://cssnano.co): Minification and purge
+- [cssnano](https://cssnano.github.io/cssnano): Minification and purge
## Leveraging Layouts For Multiple Styles
@@ -458,14 +459,14 @@ Use different styles for different layouts.
Nuxt isn't opinionated when it comes to styling and provides you with a wide variety of options. You can use any styling tool that you want, such as popular libraries like [UnoCSS](https://unocss.dev) or [Tailwind CSS](https://tailwindcss.com).
-The community and the Nuxt team have developed plenty of Nuxt modules to makes the integration easier.
+The community and the Nuxt team have developed plenty of Nuxt modules to make the integration easier.
You can discover them on the [modules section](/modules) of the website.
Here are a few modules to help you get started:
- [UnoCSS](/modules/unocss): Instant on-demand atomic CSS engine
- [Tailwind CSS](/modules/tailwindcss): Utility-first CSS framework
- [Fontaine](https://github.com/nuxt-modules/fontaine): Font metric fallback
-- [Pinceau](https://pinceau.dev): Adaptable styling framework
+- [Pinceau](https://github.com/Tahul/pinceau): Adaptable styling framework
- [Nuxt UI](https://ui.nuxt.com): A UI Library for Modern Web Apps
- [Panda CSS](https://panda-css.com/docs/installation/nuxt): CSS-in-JS engine that generates atomic CSS at build time
diff --git a/docs/1.getting-started/5.seo-meta.md b/docs/1.getting-started/5.seo-meta.md
index e77839558d..a1ebb2f457 100644
--- a/docs/1.getting-started/5.seo-meta.md
+++ b/docs/1.getting-started/5.seo-meta.md
@@ -6,7 +6,7 @@ navigation.icon: i-ph-file-search-duotone
## Defaults
-Out-of-the-box, Nuxt provides sane defaults, which you can override if needed.
+Out-of-the-box, Nuxt provides sensible defaults, which you can override if needed.
```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
@@ -174,7 +174,7 @@ You can use the `titleTemplate` option to provide a dynamic template for customi
The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function.
-If you want to use a function (for full control), then this cannot be set in your `nuxt.config`, and it is recommended instead to set it within your `app.vue` file, where it will apply to all pages on your site:
+If you want to use a function (for full control), then this cannot be set in your `nuxt.config`. It is recommended instead to set it within your `app.vue` file where it will apply to all pages on your site:
::code-group
diff --git a/docs/1.getting-started/6.data-fetching.md b/docs/1.getting-started/6.data-fetching.md
index 3e1cf5cd02..2297412b99 100644
--- a/docs/1.getting-started/6.data-fetching.md
+++ b/docs/1.getting-started/6.data-fetching.md
@@ -16,9 +16,9 @@ Both `useFetch` and `useAsyncData` share a common set of options and patterns th
Before that, it's imperative to know why these composables exist in the first place.
-## Why using specific composables?
+## Why use specific composables for data fetching?
-When using a framework like Nuxt that can perform calls and render pages on both client and server environments, some challenges must be addressed. This is why Nuxt provides composables to wrap your queries, instead of letting the developer rely on [`$fetch`](/docs/api/utils/dollarfetch) calls alone.
+Nuxt is a framework which can run isomorphic (or universal) code in both server and client environments. If the [`$fetch` function](/docs/api/utils/dollarfetch) is used to perform data fetching in the setup function of a Vue component, this may cause data to be fetched twice, once on the server (to render the HTML) and once again on the client (when the HTML is hydrated). This is why Nuxt offers specific data fetching composables so data is fetched only once.
### Network calls duplication
@@ -54,13 +54,17 @@ const { data: count } = await useFetch('/api/count')
This composable is a wrapper around the [`useAsyncData`](/docs/api/composables/use-async-data) composable and `$fetch` utility.
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=njsGVmcWviY" target="_blank"}
+Watch the video from Alexander Lichter to avoid using `useFetch` the wrong way!
+::
+
:read-more{to="/docs/api/composables/use-fetch"}
:link-example{to="/docs/examples/features/data-fetching"}
## `$fetch`
-Nuxt includes the `ofetch` library, and is auto-imported as the `$fetch` alias globally across your application. It's what `useFetch` uses behind the scenes.
+Nuxt includes the [ofetch](https://github.com/unjs/ofetch) library, and is auto-imported as the `$fetch` alias globally across your application. It's what `useFetch` uses behind the scenes.
```vue twoslash [pages/todos.vue]
```
-The `useAsyncData` composable is a great way to wrap and wait for multiple `useFetch` to be done, and then retrieve the results of each.
+The `useAsyncData` composable is a great way to wrap and wait for multiple `$fetch` requests to be completed, and then process the results.
```vue
+```
+
#### Watch
To re-run your fetching function each time other reactive values in your application change, use the `watch` option. You can use it for one or multiple _watchable_ elements.
@@ -599,3 +623,37 @@ const { data } = await useFetch('/api/superjson', {
})
```
+
+## Recipes
+
+### Consuming SSE (Server Sent Events) via POST request
+
+::tip
+If you're consuming SSE via GET request, you can use [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or VueUse composable [`useEventSource`](https://vueuse.org/core/useEventSource/).
+::
+
+When consuming SSE via POST request, you need to handle the connection manually. Here's how you can do it:
+
+```ts
+// Make a POST request to the SSE endpoint
+const response = await $fetch('/chats/ask-ai', {
+ method: 'POST',
+ body: {
+ query: "Hello AI, how are you?",
+ },
+ responseType: 'stream',
+})
+
+// Create a new ReadableStream from the response with TextDecoderStream to get the data as text
+const reader = response.pipeThrough(new TextDecoderStream()).getReader()
+
+// Read the chunk of data as we get it
+while (true) {
+ const { value, done } = await reader.read()
+
+ if (done)
+ break
+
+ console.log('Received:', value)
+}
+```
diff --git a/docs/1.getting-started/7.state-management.md b/docs/1.getting-started/7.state-management.md
index 1f58ce72c5..4957fb4a14 100644
--- a/docs/1.getting-started/7.state-management.md
+++ b/docs/1.getting-started/7.state-management.md
@@ -8,6 +8,10 @@ Nuxt provides the [`useState`](/docs/api/composables/use-state) composable to cr
[`useState`](/docs/api/composables/use-state) is an SSR-friendly [`ref`](https://vuejs.org/api/reactivity-core.html#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=mv0WcBABcIk" target="_blank"}
+Watch a video from Alexander Lichter about why and when to use `useState()`.
+::
+
::important
Because the data inside [`useState`](/docs/api/composables/use-state) will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.
::
@@ -130,12 +134,12 @@ export const useLocale = () => {
export const useDefaultLocale = (fallback = 'en-US') => {
const locale = ref(fallback)
- if (process.server) {
+ if (import.meta.server) {
const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
if (reqLocale) {
locale.value = reqLocale
}
- } else if (process.client) {
+ } else if (import.meta.client) {
const navLang = navigator.language
if (navLang) {
locale.value = navLang
@@ -192,7 +196,6 @@ const date = useLocaleDate(new Date('2016-10-26'))
By using [auto-imported composables](/docs/guide/directory-structure/composables) we can define global type-safe states and import them across the app.
```ts twoslash [composables/states.ts]
-export const useCounter = () => useState('counter', () => 0)
export const useColor = () => useState('color', () => 'pink')
```
@@ -209,6 +212,10 @@ const color = useColor() // Same as useState('color')
```
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=dZSNW07sO-A" target="_blank"}
+Watch a video from Daniel Roe on how to deal with global state and SSR in Nuxt.
+::
+
## Using third-party libraries
Nuxt **used to rely** on the Vuex library to provide global state management. If you are migrating from Nuxt 2, please head to [the migration guide](/docs/migration/configuration#vuex).
diff --git a/docs/1.getting-started/8.error-handling.md b/docs/1.getting-started/8.error-handling.md
index 7ede474f2f..c4b44a438d 100644
--- a/docs/1.getting-started/8.error-handling.md
+++ b/docs/1.getting-started/8.error-handling.md
@@ -7,15 +7,15 @@ navigation.icon: i-ph-bug-beetle-duotone
Nuxt 3 is a full-stack framework, which means there are several sources of unpreventable user runtime errors that can happen in different contexts:
- Errors during the Vue rendering lifecycle (SSR & CSR)
-- Errors during Nitro server lifecycle ([`server/`](/docs/guide/directory-structure/server) directory)
- Server and client startup errors (SSR + CSR)
+- Errors during Nitro server lifecycle ([`server/`](/docs/guide/directory-structure/server) directory)
- Errors downloading JS chunks
::tip
**SSR** stands for **Server-Side Rendering** and **CSR** for **Client-Side Rendering**.
::
-## Vue Rendering Lifecycle
+## Vue Errors
You can hook into Vue errors using [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
@@ -51,7 +51,7 @@ This includes:
- mounting the app (on client-side), though you should handle this case with `onErrorCaptured` or with `vue:error`
- processing the `app:mounted` hook
-## Nitro Server Lifecycle
+## Nitro Server Errors
You cannot currently define a server-side handler for these errors, but can render an error page, see the [Render an Error Page](#error-page) section.
@@ -125,6 +125,10 @@ When you are ready to remove the error page, you can call the [`clearError`](/do
Make sure to check before using anything dependent on Nuxt plugins, such as `$route` or `useRouter`, as if a plugin threw an error, then it won't be re-run until you clear the error.
::
+::note
+Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](#useerror) in middleware to check if an error is being handled.
+::
+
::note
If you are running on Node 16 and you set any cookies when rendering your error page, they will [overwrite cookies previously set](https://github.com/nuxt/nuxt/pull/20585). We recommend using a newer version of Node as Node 16 reached end-of-life in September 2023.
::
diff --git a/docs/1.getting-started/8.server.md b/docs/1.getting-started/8.server.md
index 94e2da9e7c..2a67cc3945 100644
--- a/docs/1.getting-started/8.server.md
+++ b/docs/1.getting-started/8.server.md
@@ -20,6 +20,10 @@ Using Nitro gives Nuxt superpowers:
Nitro is internally using [h3](https://github.com/unjs/h3), a minimal H(TTP) framework built for high performance and portability.
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=DkvgJa-X31k" target="_blank"}
+Watch a video from Alexander Lichter to understand the responsibilities of Nuxt and Nitro in your application.
+::
+
## Server Endpoints & Middleware
You can easily manage the server-only part of your Nuxt app, from API endpoints to middleware.
@@ -83,9 +87,9 @@ export default defineNuxtConfig({
Learn about all available route rules are available to customize the rendering mode of your routes.
::
-In addition, there are some route rules (for example, `ssr` and `experimentalNoScripts`) that are Nuxt specific to change the behavior when rendering your pages to HTML.
+In addition, there are some route rules (for example, `ssr`, `appMiddleware`, and `experimentalNoScripts`) that are Nuxt specific to change the behavior when rendering your pages to HTML.
-Some route rules (`redirect` and `prerender`) also affect client-side behavior.
+Some route rules (`appMiddleware`, `redirect` and `prerender`) also affect client-side behavior.
Nitro is used to build the app for server side rendering, as well as pre-rendering.
diff --git a/docs/1.getting-started/9.layers.md b/docs/1.getting-started/9.layers.md
index ed61136af1..7e05dadaf6 100644
--- a/docs/1.getting-started/9.layers.md
+++ b/docs/1.getting-started/9.layers.md
@@ -14,12 +14,13 @@ One of the core features of Nuxt 3 is the layers and extending support. You can
- Create Nuxt module presets
- Share standard setup across projects
- Create Nuxt themes
+- Enhance code organization by implementing a modular architecture and support Domain-Driven Design (DDD) pattern in large scale projects.
## Usage
You can extend a layer by adding the [extends](/docs/api/nuxt-config#extends) property to the [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file.
-```ts twoslash [nuxt.config.ts]
+```ts [nuxt.config.ts]
export default defineNuxtConfig({
extends: [
'../base', // Extend from a local layer
@@ -29,12 +30,29 @@ export default defineNuxtConfig({
})
```
+You can also pass an authentication token if you are extending from a private GitHub repository:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ extends: [
+ // per layer configuration
+ ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }]
+ ]
+})
+```
+
+Nuxt uses [unjs/c12](https://c12.unjs.io) and [unjs/giget](https://giget.unjs.io) for extending remote layers. Check the documentation for more information and all available options.
+
::read-more{to="/docs/guide/going-further/layers"}
Read more about layers in the **Layer Author Guide**.
::
::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=lnFCM7c9f7I" target="_blank"}
-Watch Learn Vue video about Nuxt Layers.
+Watch a video from Learn Vue about Nuxt Layers.
+::
+
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=fr5yo3aVkfA" target="_blank"}
+Watch a video from Alexander Lichter about Nuxt Layers.
::
## Examples
diff --git a/docs/1.getting-started/9.prerendering.md b/docs/1.getting-started/9.prerendering.md
new file mode 100644
index 0000000000..ee63d7b285
--- /dev/null
+++ b/docs/1.getting-started/9.prerendering.md
@@ -0,0 +1,177 @@
+---
+title: "Prerendering"
+description: Nuxt allows pages to be statically rendered at build time to improve certain performance or SEO metrics
+navigation.icon: i-ph-code-block-duotone
+---
+
+Nuxt allows for select pages from your application to be rendered at build time. Nuxt will serve the prebuilt pages when requested instead of generating them on the fly.
+
+:read-more{title="Nuxt rendering modes" to="/docs/guide/concepts/rendering"}
+
+## Crawl-based Pre-rendering
+
+Use the [`nuxi generate` command](/docs/api/commands/generate) to build and pre-render your application using the [Nitro](/docs/guide/concepts/server-engine) crawler. This command is similar to `nuxt build` with the `nitro.static` option set to `true`, or running `nuxt build --prerender`.
+
+This will build your site, stand up a nuxt instance, and, by default, prerender the root page `/` along with any of your site's pages it links to, any of your site's pages they link to, and so on.
+
+```bash [Terminal]
+npx nuxi generate
+```
+
+You can now deploy the `.output/public` directory to any static hosting service or preview it locally with `npx serve .output/public`.
+
+Working of the Nitro crawler:
+
+1. Load the HTML of your application's root route (`/`), any non-dynamic pages in your `~/pages` directory, and any other routes in the `nitro.prerender.routes` array.
+2. Save the HTML and `payload.json` to the `~/.output/public/` directory to be served statically.
+3. Find all anchor tags (``) in the HTML to navigate to other routes.
+4. Repeat steps 1-3 for each anchor tag found until there are no more anchor tags to crawl.
+
+This is important to understand since pages that are not linked to a discoverable page can't be pre-rendered automatically.
+
+::read-more{to="/docs/api/commands/generate#nuxi-generate"}
+Read more about the `nuxi generate` command.
+::
+
+### Selective Pre-rendering
+
+You can manually specify routes that [Nitro](/docs/guide/concepts/server-engine) will fetch and pre-render during the build or ignore routes that you don't want to pre-render like `/dynamic` in the `nuxt.config` file:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ nitro: {
+ prerender: {
+ routes: ["/user/1", "/user/2"],
+ ignore: ["/dynamic"],
+ },
+ },
+});
+```
+
+You can combine this with the `crawlLinks` option to pre-render a set of routes that the crawler can't discover like your `/sitemap.xml` or `/robots.txt`:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ nitro: {
+ prerender: {
+ crawlLinks: true,
+ routes: ["/sitemap.xml", "/robots.txt"],
+ },
+ },
+});
+```
+
+Setting `nitro.prerender` to `true` is similar to `nitro.prerender.crawlLinks` to `true`.
+
+::read-more{to="https://nitro.unjs.io/config#prerender"}
+Read more about pre-rendering in the Nitro documentation.
+::
+
+Lastly, you can manually configure this using routeRules.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ routeRules: {
+ // Set prerender to true to configure it to be prerendered
+ "/rss.xml": { prerender: true },
+ // Set it to false to configure it to be skipped for prerendering
+ "/this-DOES-NOT-get-prerendered": { prerender: false },
+ // Everything under /blog gets prerendered as long as it
+ // is linked to from another page
+ "/blog/**": { prerender: true },
+ },
+});
+```
+
+::read-more{to="https://nitro.unjs.io/config/#routerules"}
+Read more about Nitro's `routeRules` configuration.
+::
+
+As a shorthand, you can also configure this in a page file using [`defineRouteRules`](/docs/api/utils/define-route-rules).
+
+::read-more{to="/docs/guide/going-further/experimental-features#inlinerouterules" icon="i-ph-star-duotone"}
+This feature is experimental and in order to use it you must enable the `experimental.inlineRouteRules` option in your `nuxt.config`.
+::
+
+```vue [pages/index.vue]
+
+
+
+ `{lang=ts} - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)
Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).
diff --git a/docs/2.guide/1.concepts/8.typescript.md b/docs/2.guide/1.concepts/8.typescript.md
index e2718dc55f..4e07f35631 100644
--- a/docs/2.guide/1.concepts/8.typescript.md
+++ b/docs/2.guide/1.concepts/8.typescript.md
@@ -9,22 +9,26 @@ By default, Nuxt doesn't check types when you run [`nuxi dev`](/docs/api/command
To enable type-checking at build or development time, install `vue-tsc` and `typescript` as development dependency:
+::alert{type="warning"}
+You may experience issues with the latest `vue-tsc` and `vite-plugin-checker`, used internally when type checking. For now, you may need to stay on v1 of `vue-tsc`, and follow these upstream issues for updates: [fi3ework/vite-plugin-checker#306](https://github.com/fi3ework/vite-plugin-checker/issues/306) and [vuejs/language-tools#3969](https://github.com/vuejs/language-tools/issues/3969).
+::
+
::code-group
```bash [yarn]
- yarn add --dev vue-tsc typescript
+ yarn add --dev vue-tsc@^1 typescript
```
```bash [npm]
- npm install --save-dev vue-tsc typescript
+ npm install --save-dev vue-tsc@^1 typescript
```
```bash [pnpm]
- pnpm add -D vue-tsc typescript
+ pnpm add -D vue-tsc@^1 typescript
```
```bash [bun]
- bun add -D vue-tsc typescript
+ bun add -D vue-tsc@^1 typescript
```
::
@@ -61,6 +65,10 @@ This file contains the recommended basic TypeScript configuration for your proje
[Read more about how to extend this configuration](/docs/guide/directory-structure/tsconfig).
+::tip{icon="i-ph-video-duotone" to="https://youtu.be/umLI7SlPygY" target="_blank"}
+Watch a video from Daniel Roe explaining built-in Nuxt aliases.
+::
+
::note
Nitro also [auto-generates types](/docs/guide/concepts/server-engine#typed-api-routes) for API routes. Plus, Nuxt also generates types for globally available components and [auto-imports from your composables](/docs/guide/directory-structure/composables), plus other core functionality.
::
@@ -72,18 +80,18 @@ Overwriting options such as `"compilerOptions.paths"` with your own configuratio
In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the [`alias` property](/docs/api/nuxt-config#alias) within your `nuxt.config`. `nuxi` will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
::
-## Stricter Checks
+## Strict Checks
TypeScript comes with certain checks to give you more safety and analysis of your program.
-Once youβve converted your codebase to TypeScript and felt familiar with it, you can start enabling these checks for greater safety ([read more](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks)).
+[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt 3 to give you greater type safety.
-In order to enable strict type checking, you have to update `nuxt.config`:
+If you are currently converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting `strict` to `false` in your `nuxt.config`:
```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
typescript: {
- strict: true
+ strict: false
}
})
```
diff --git a/docs/2.guide/1.concepts/9.code-style.md b/docs/2.guide/1.concepts/9.code-style.md
index 3b9e27bcbd..2a6a32afb3 100644
--- a/docs/2.guide/1.concepts/9.code-style.md
+++ b/docs/2.guide/1.concepts/9.code-style.md
@@ -5,76 +5,20 @@ description: "Nuxt supports ESLint out of the box"
## ESLint
-The recommended approach for Nuxt is to enable ESLint support using [`@nuxt/eslint-config`](https://github.com/nuxt/eslint-config).
+The recommended approach for Nuxt is to enable ESLint support using the [`@nuxt/eslint`](https://eslint.nuxt.com/packages/module) module, that will setup project-aware ESLint configuration for you.
-At the moment, this configuration will not format your files; you can set up Prettier or another tool to do so.
+:::callout{icon="i-ph-lightbulb-duotone"}
+The module is designed for the [new ESLint flat config format](https://eslint.org/docs/latest/use/configure/configuration-files-new) with is the [default format since ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/).
-::alert{type=info}
-We're currently working to refactor the Nuxt ESLint configuration. Subscribe to the [Nuxt ESLint roadmap](https://github.com/nuxt/eslint-config/issues/303) to follow updates.
-::
+If you are using the legacy `.eslintrc` config, you will need to [configure manually with `@nuxt/eslint-config`](https://eslint.nuxt.com/packages/config#legacy-config-format). We highly recommend you to migrate over the flat config to be future-proof.
+:::
-### Install Dependencies
+## Quick Setup
-Install both ESLint and the Nuxt configuration as development dependencies.
-
-::code-group
-
-```bash [yarn]
-yarn add --dev eslint @nuxt/eslint-config
+```bash
+npx nuxi module add eslint
```
-```bash [npm]
-npm install --save-dev eslint @nuxt/eslint-config
-```
+Start your Nuxt app, a `eslint.config.mjs` file will be generated under your project root. You can customize it as needed.
-```bash [pnpm]
-pnpm add -D eslint @nuxt/eslint-config
-```
-
-```bash [bun]
-bun add -D eslint @nuxt/eslint-config
-```
-
-::
-
-### Configuration
-
-Add `.eslintrc.cjs` to the root folder of your Nuxt app.
-
-```js
-module.exports = {
- root: true,
- extends: ['@nuxt/eslint-config'],
-}
-```
-
-### Modify package.json
-
-Add the below to lint commands to your `package.json` script section:
-
-```json
- "scripts": {
- ...
- "lint": "eslint .",
- "lint:fix": "eslint . --fix",
- ...
- },
-```
-
-Run the `lint` command to check if the code style is correct or run `lint:fix` to automatically fix issues.
-
-### Configuring VS Code
-
-Install the [VS Code ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint).
-
-In VS Code press `ctrl+shift+p` (`cmd+shift+p` on Mac) to open the command prompt, find `Open Workspace Settings (JSON)`, add the below lines to the JSON and save:
-
-```json
-{
- "editor.codeActionsOnSave": {
- "source.fixAll.eslint": "explicit"
- }
-}
-```
-
-You're good to go! On save, your files will be linted and auto-fixed.
+You can learn more about the module and customizations in [Nuxt ESLint's documentation](https://eslint.nuxt.com/packages/module).
diff --git a/docs/2.guide/2.directory-structure/1.components.md b/docs/2.guide/2.directory-structure/1.components.md
index 655cb98bd9..0cdf5cb4b6 100644
--- a/docs/2.guide/2.directory-structure/1.components.md
+++ b/docs/2.guide/2.directory-structure/1.components.md
@@ -244,6 +244,10 @@ This feature only works with Nuxt auto-imports and `#components` imports. Explic
`.client` components are rendered only after being mounted. To access the rendered template using `onMounted()`, add `await nextTick()` in the callback of the `onMounted()` hook.
::
+::read-more{to="/docs/api/components/client-only"}
+You can also achieve a similar result with the `` component.
+::
+
## Server Components
Server components allow server-rendering individual components within your client-side apps. It's possible to use server components within Nuxt, even if you are generating a static site. That makes it possible to build complex sites that mix dynamic components, server-rendered HTML and even static chunks of markup.
@@ -255,7 +259,7 @@ Watch Learn Vue video about Nuxt Server Components.
::
::tip{icon="i-ph-article-duotone" to="https://roe.dev/blog/nuxt-server-components" target="_blank"}
-Read Daniel Roe's guide to Nuxt server components
+Read Daniel Roe's guide to Nuxt Server Components.
::
### Standalone server components
@@ -295,6 +299,10 @@ Now you can register server-only components with the `.server` suffix and use th
Server-only components use [``](/docs/api/components/nuxt-island) under the hood, meaning that `lazy` prop and `#fallback` slot are both passed down to it.
+::alert{type=warning}
+Server components (and islands) must have a single root element. (HTML comments are considered elements as well.)
+::
+
::alert{type=warning}
Most features for server-only components and island components, such as slots and client components, are only available for single file components.
::
@@ -318,7 +326,7 @@ You can partially hydrate a component by setting a `nuxt-client` attribute on th
```
::alert{type=info}
-This only works within a server component.Β Slots for client components are not available yet.
+This only works within a server component.Β Slots for client components are working only with `experimental.componentIsland.selectiveClient` set to `'deep'` and since they are rendered server-side, they are not interactive once client-side.
::
#### Server Component Context
@@ -357,89 +365,12 @@ In this case, the `.server` + `.client` components are two 'halves' of a compone
```
-## `` Component
+## Built-In Nuxt Components
-Nuxt provides the [``](/docs/api/components/client-only) component for purposely rendering a component only on client side.
+There are a number of components that Nuxt provides, including `` and ``. You can read more about them in the API documentation.
-```vue [pages/example.vue]
-
- ` is mounted on client side.
-
-```vue [pages/example.vue]
-
- ` Component
-
-Nuxt provides the `` component to render a component only during development.
-
-The content will not be included in production builds and tree-shaken.
-
-```vue [pages/example.vue]
-
- ` Component
-
-Nuxt provides the `` component to render its content on the client if any of its children trigger an error in SSR.
-You can specify a `fallbackTag` to make it render a specific tag if it fails to render on the server.
-
-```vue [pages/example.vue]
-
- ` compon
```
+```vue {}[pages/parent/child.vue]
+
+```
+
### Child Route Keys
If you want more control over when the `` component is re-rendered (for example, for transitions), you can either pass a string or function via the `pageKey` prop, or you can define a `key` value via `definePageMeta`:
@@ -208,7 +216,7 @@ If you want more control over when the `` component is re-rendered (fo
Or alternatively:
-```vue twoslash {}[pages/child.vue]
+```vue twoslash {}[pages/parent/child.vue]
```
+## Client-Only Pages
+
+You can define a page as [client only](/docs/guide/directory-structure/components#client-components) by giving it a `.client.vue` suffix. None of the content of this page will be rendered on the server.
+
## Server-Only Pages
You can define a page as [server only](/docs/guide/directory-structure/components#server-components) by giving it a `.server.vue` suffix. While you will be able to navigate to the page using client-side navigation, controlled by `vue-router`, it will be rendered with a server component automatically, meaning the code required to render the page will not be in your client-side bundle.
-::note
-You will also need to enable `experimental.componentIslands` in order to make this possible.
+::alert{type=warning}
+Server-only pages must have a single root element. (HTML comments are considered elements as well.)
::
## Custom Routing
diff --git a/docs/2.guide/2.directory-structure/1.plugins.md b/docs/2.guide/2.directory-structure/1.plugins.md
index 995e6212d1..a30be3eac6 100644
--- a/docs/2.guide/2.directory-structure/1.plugins.md
+++ b/docs/2.guide/2.directory-structure/1.plugins.md
@@ -76,9 +76,14 @@ export default defineNuxtPlugin({
})
```
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=2aXZyXB1QGQ" target="_blank"}
+Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins.
+::
+
::note
-If you are using the object-syntax, the properties may be statically analyzed in future to produce a more optimized build. So you should not define them at runtime. :br
-For example, setting `enforce: process.server ? 'pre' : 'post'` would defeat any future optimization Nuxt is able to do for your plugins.
+If you are using the object-syntax, the properties are statically analyzed to produce a more optimized build. So you should not define them at runtime. :br
+For example, setting `enforce: import.meta.server ? 'pre' : 'post'` would defeat any future optimization Nuxt is able to do for your plugins.
+Nuxt does statically pre-load any hook listeners when using object-syntax, allowing you to define hooks without needing to worry about order of plugin registration.
::
## Registration Order
@@ -117,7 +122,7 @@ export default defineNuxtPlugin({
### Plugins With Dependencies
-If a plugin needs to await a parallel plugin before it runs, you can add the plugin's name to the `dependsOn` array.
+If a plugin needs to wait for another plugin before it runs, you can add the plugin's name to the `dependsOn` array.
```ts twoslash [plugins/depending-on-my-plugin.ts]
export default defineNuxtPlugin({
diff --git a/docs/2.guide/2.directory-structure/2.env.md b/docs/2.guide/2.directory-structure/2.env.md
index 660a8138d5..0a39c625a3 100644
--- a/docs/2.guide/2.directory-structure/2.env.md
+++ b/docs/2.guide/2.directory-structure/2.env.md
@@ -33,11 +33,25 @@ npx nuxi dev --dotenv .env.local
When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.
-## Production Preview
+## Production
**After your server is built**, you are responsible for setting environment variables when you run the server.
-Your `.env` file will not be read at this point. How you do this is different for every environment.
+Your `.env` files will not be read at this point. How you do this is different for every environment.
+
+This design decision was made to ensure compatibility across various deployment environments, some of which may not have a traditional file system available, such as serverless platforms or edge networks like Cloudflare Workers.
+
+Since `.env` files are not used in production, you must explicitly set environment variables using the tools and methods provided by your hosting environment. Here are some common approaches:
+
+* You can pass the environment variables as arguments using the terminal:
+
+ `$ DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`
+
+* You can set environment variables in shell configuration files like `.bashrc` or `.profile`.
+
+* Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.
+
+## Production Preview
For local production preview purpose, we recommend using [`nuxi preview`](/docs/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.
diff --git a/docs/2.guide/2.directory-structure/3.app-config.md b/docs/2.guide/2.directory-structure/3.app-config.md
index d8eb2ce4be..93c15381f8 100644
--- a/docs/2.guide/2.directory-structure/3.app-config.md
+++ b/docs/2.guide/2.directory-structure/3.app-config.md
@@ -99,7 +99,7 @@ Nuxt uses a custom merging strategy for the `AppConfig` within [the layers](/doc
This strategy is implemented using a [Function Merger](https://github.com/unjs/defu#function-merger), which allows defining a custom merging strategy for every key in `app.config` that has an array as value.
::note
-The Function Merger should only be used in the base `app.config` of your application.
+The function merger can only be used in the extended layers and not the main `app.config` in project.
::
Here's an example of how you can use:
diff --git a/docs/2.guide/2.directory-structure/3.nuxt-config.md b/docs/2.guide/2.directory-structure/3.nuxt-config.md
index d41971142e..1174095d2b 100644
--- a/docs/2.guide/2.directory-structure/3.nuxt-config.md
+++ b/docs/2.guide/2.directory-structure/3.nuxt-config.md
@@ -33,7 +33,7 @@ Discover all the available options in the **Nuxt configuration** documentation.
To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/guide/directory-structure/env), [`.nuxtignore`](/docs/guide/directory-structure/nuxtignore) and `.nuxtrc` dotfiles.
-The `.nuxtrc` file is a file that can be used to configure Nuxt with a fla syntax, it is based on [`unjs/rc9`](https://github.com/unjs/rc9).
+The `.nuxtrc` file can be used to configure Nuxt with a flat syntax. It is based on [`unjs/rc9`](https://github.com/unjs/rc9).
``` [.nuxtrc]
ssr=false
diff --git a/docs/2.guide/3.going-further/1.experimental-features.md b/docs/2.guide/3.going-further/1.experimental-features.md
index fd6ad8d44a..9105b2ebfa 100644
--- a/docs/2.guide/3.going-further/1.experimental-features.md
+++ b/docs/2.guide/3.going-further/1.experimental-features.md
@@ -306,6 +306,10 @@ Out of the box, this will enable typed usage of [`navigateTo`](/docs/api/utils/n
You can even get typed params within a page by using `const route = useRoute('route-name')`.
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=SXk-L19gTZk" target="_blank"}
+Watch a video from Daniel Roe explaining type-safe routing in Nuxt.
+::
+
## watcher
Set an alternative watcher that will be used as the watching service for Nuxt.
@@ -340,6 +344,10 @@ export default defineNuxtConfig({
})
```
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=1jUupYHVvrU" target="_blank"}
+Watch a video from Alexander Lichter about the experimental `sharedPrerenderData` setting.
+::
+
It is particularly important when enabling this feature to make sure that any unique key of your data
is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch
data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch`
@@ -378,6 +386,16 @@ This option allows exposing some route metadata defined in `definePageMeta` at b
This only works with static or strings/arrays rather than variables or conditional assignment. See [original issue](https://github.com/nuxt/nuxt/issues/24770) for more information and context.
+You can disable this feature if it causes issues in your project.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ experimental: {
+ scanPageMeta: false
+ }
+})
+```
+
## cookieStore
Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.
diff --git a/docs/2.guide/3.going-further/1.features.md b/docs/2.guide/3.going-further/1.features.md
index e43c6dda2d..02056f1e12 100644
--- a/docs/2.guide/3.going-further/1.features.md
+++ b/docs/2.guide/3.going-further/1.features.md
@@ -37,6 +37,47 @@ export default defineNuxtConfig({
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+.
+::
+
+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: {
+ compileTemplate: true,
+ templateUtils: true,
+ relativeWatchPaths: true,
+ defaults: {
+ useAsyncData: {
+ deep: true
+ }
+ }
+ },
+ unhead: {
+ renderSSRHeadOptions: {
+ omitLineBreaks: false
+ }
+ }
+})
+```
+
### typescriptBundlerResolution
This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting
diff --git a/docs/2.guide/3.going-further/10.runtime-config.md b/docs/2.guide/3.going-further/10.runtime-config.md
index f4ca19cd94..9a1832ad50 100644
--- a/docs/2.guide/3.going-further/10.runtime-config.md
+++ b/docs/2.guide/3.going-further/10.runtime-config.md
@@ -61,6 +61,10 @@ Setting the default of `runtimeConfig` values to *differently named environment
It is advised to use environment variables that match the structure of your `runtimeConfig` object.
::
+::tip{icon="i-ph-video-duotone" to="https://youtu.be/_FYV5WfiWvs" target="_blank"}
+Watch a video from Alexander Lichter showcasing the top mistake developers make using runtimeConfig.
+::
+
#### Example
```sh [.env]
@@ -98,7 +102,7 @@ The behavior is different between the client-side and server-side:
const config = useRuntimeConfig()
console.log('Runtime config:', config)
-if (process.server) {
+if (import.meta.server) {
console.log('API secret:', config.apiSecret)
}
@@ -164,3 +168,7 @@ declare module 'nuxt/schema' {
// 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`.
+::
diff --git a/docs/2.guide/3.going-further/3.modules.md b/docs/2.guide/3.going-further/3.modules.md
index f7eae0f03f..8c354e5e21 100644
--- a/docs/2.guide/3.going-further/3.modules.md
+++ b/docs/2.guide/3.going-further/3.modules.md
@@ -30,6 +30,10 @@ This will create a `my-module` project with all the boilerplate necessary to dev
Learn how to perform basic tasks with the module starter.
+::tip{icon="i-ph-video-duotone" to="https://vueschool.io/lessons/navigating-the-official-starter-template" target="_blank"}
+Watch Vue School video about Nuxt module starter template.
+::
+
#### How to Develop
While your module source code lives inside the `src` directory, in most cases, to develop a module, you need a Nuxt application. That's what the `playground` directory is about. It's a Nuxt application you can tinker with that is already configured to run with your module.
@@ -72,7 +76,7 @@ Before publishing your module to npm, makes sure you have an [npmjs.com](https:/
While you can publish your module by bumping its version and using the `npm publish` command, the module starter comes with a release script that helps you make sure you publish a working version of your module to npm and more.
-To use the release script, first, commit all your changes (we recommend you follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) to also take advantage of automatic version bump and changelog update), then run the release script with `npm run release`.
+To use the release script, first, commit all your changes (we recommend you follow [Conventional Commits](https://www.conventionalcommits.org) to also take advantage of automatic version bump and changelog update), then run the release script with `npm run release`.
When running the release script, the following will happen:
@@ -255,6 +259,10 @@ export default defineNuxtModule({
When you need to handle more complex configuration alterations, you should consider using [defu](https://github.com/unjs/defu).
+::tip{icon="i-ph-video-duotone" to="https://vueschool.io/lessons/extending-and-altering-nuxt-configuration-and-options" target="_blank"}
+Watch Vue School video about altering Nuxt configuration.
+::
+
#### Exposing Options to Runtime
Because modules aren't part of the application runtime, their options aren't either. However, in many cases, you might need access to some of these module options within your runtime code. We recommend exposing the needed config using Nuxt's [`runtimeConfig`](/docs/api/nuxt-config#runtimeconfig).
@@ -288,6 +296,10 @@ Be careful not to expose any sensitive module configuration on the public runtim
:read-more{to="/docs/guide/going-further/runtime-config"}
+::tip{icon="i-ph-video-duotone" to="https://vueschool.io/lessons/passing-and-exposing-module-options" target="_blank"}
+Watch Vue School video about passing and exposing Nuxt module options.
+::
+
#### Injecting Plugins With `addPlugin`
Plugins are a common way for a module to add runtime logic. You can use the `addPlugin` utility to register them from your module.
@@ -511,6 +523,10 @@ export default defineNuxtModule({
:read-more{to="/docs/api/advanced/hooks"}
+::tip{icon="i-ph-video-duotone" to="https://vueschool.io/lessons/nuxt-lifecycle-hooks" target="_blank"}
+Watch Vue School video about using Nuxt lifecycle hooks in modules.
+::
+
::note
**Module cleanup**
:br
@@ -733,6 +749,10 @@ The module starter comes with a default set of tools and configurations (e.g. ES
[Nuxt Module ecosystem](/modules) represents more than 15 million monthly NPM downloads and provides extended functionalities and integrations with all sort of tools. You can be part of this ecosystem!
+::tip{icon="i-ph-video-duotone" to="https://vueschool.io/lessons/exploring-nuxt-modules-ecosystem-and-module-types" target="_blank"}
+Watch Vue School video about Nuxt module types.
+::
+
### Module Types
**Official modules** are modules prefixed (scoped) with `@nuxt/` (e.g. [`@nuxt/content`](https://content.nuxtjs.org)). They are made and maintained actively by the Nuxt team. Like with the framework, contributions from the community are more than welcome to help make them better!
diff --git a/docs/2.guide/3.going-further/4.kit.md b/docs/2.guide/3.going-further/4.kit.md
index 0610737513..226762b899 100644
--- a/docs/2.guide/3.going-further/4.kit.md
+++ b/docs/2.guide/3.going-further/4.kit.md
@@ -15,6 +15,10 @@ Discover all Nuxt Kit utilities.
You can install the latest Nuxt Kit by adding it to the `dependencies` section of your `package.json`. However, please consider always explicitly installing the `@nuxt/kit` package even if it is already installed by Nuxt.
+::note
+`@nuxt/kit` and `@nuxt/schema` are key dependencies for Nuxt. If you are installing it separately, make sure that the versions of `@nuxt/kit` and `@nuxt/schema` are equal to or greater than your `nuxt` version to avoid any unexpected behavior.
+::
+
```json [package.json]
{
"dependencies": {
diff --git a/docs/2.guide/3.going-further/7.layers.md b/docs/2.guide/3.going-further/7.layers.md
index 4533abfe49..3285135cfd 100644
--- a/docs/2.guide/3.going-further/7.layers.md
+++ b/docs/2.guide/3.going-further/7.layers.md
@@ -100,6 +100,10 @@ export default defineNuxtConfig({
If you want to extend a private remote source, you need to add the environment variable `GIGET_AUTH=` to provide a token.
::
+::tip
+If you want to extend a remote source from a self-hosted GitHub or GitLab instance, you need to supply its URL with the `GIGET_GITHUB_URL=` or `GIGET_GITLAB_URL=` environment variable - or directly configure it with [the `auth` option](https://github.com/unjs/c12#extending-config-layer-from-remote-sources) in your `nuxt.config`.
+::
+
::note
When using git remote sources, if a layer has npm dependencies and you wish to install them, you can do so by specifying `install: true` in your layer options.
diff --git a/docs/2.guide/3.going-further/9.debugging.md b/docs/2.guide/3.going-further/9.debugging.md
index 0771c6d959..59558ba67d 100644
--- a/docs/2.guide/3.going-further/9.debugging.md
+++ b/docs/2.guide/3.going-further/9.debugging.md
@@ -38,6 +38,10 @@ It is possible to debug your Nuxt app in your IDE while you are developing it.
You may need to update the config below with a path to your web browser. For more information, visit the [VS Code documentation about debug configuration](https://go.microsoft.com/fwlink/?linkid=830387).
+::important
+If you use `pnpm`, you will need to have `nuxi` installed as a devDependency for the configuration below to work.
+::
+
```json5
{
// Use IntelliSense to learn about possible attributes.
diff --git a/docs/2.guide/3.going-further/8.custom-routing.md b/docs/2.guide/4.recipes/1.custom-routing.md
similarity index 97%
rename from docs/2.guide/3.going-further/8.custom-routing.md
rename to docs/2.guide/4.recipes/1.custom-routing.md
index b8f39b048d..b3e408c2a3 100644
--- a/docs/2.guide/3.going-further/8.custom-routing.md
+++ b/docs/2.guide/4.recipes/1.custom-routing.md
@@ -105,7 +105,7 @@ export default defineNuxtConfig({
const resolver = createResolver(import.meta.url)
// add a route
files.push({
- path: resolver.resolve('./runtime/app/router-options')
+ path: resolver.resolve('./runtime/app/router-options'),
optional: true
})
}
@@ -172,6 +172,6 @@ import { createMemoryHistory } from 'vue-router'
export default {
// https://router.vuejs.org/api/interfaces/routeroptions.html
- history: base => process.client ? createMemoryHistory(base) : null /* default */
+ history: base => import.meta.client ? createMemoryHistory(base) : null /* default */
}
```
diff --git a/docs/2.guide/4.recipes/2.vite-plugin.md b/docs/2.guide/4.recipes/2.vite-plugin.md
new file mode 100644
index 0000000000..6a9b1e8a28
--- /dev/null
+++ b/docs/2.guide/4.recipes/2.vite-plugin.md
@@ -0,0 +1,65 @@
+---
+navigation.title: 'Vite Plugins'
+title: Using Vite Plugins in Nuxt
+description: Learn how to integrate Vite plugins into your Nuxt project.
+---
+
+While Nuxt modules offer extensive functionality, sometimes a specific Vite plugin might meet your needs more directly.
+
+First, we need to install the Vite plugin, for our example, we'll use `@rollup/plugin-yaml`:
+
+::code-group
+
+ ```bash [npm]
+ npm install @rollup/plugin-yaml
+ ```
+
+ ```bash [yarn]
+ yarn add @rollup/plugin-yaml
+ ```
+
+ ```bash [pnpm]
+ pnpm add @rollup/plugin-yaml
+ ```
+
+ ```bash [bun]
+ bun add @rollup/plugin-yaml
+ ```
+
+::
+
+Next, we need to import and add it to our [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) file:
+
+```ts [nuxt.config.ts]
+import yaml from '@rollup/plugin-yaml'
+
+export default defineNuxtConfig({
+ vite: {
+ plugins: [
+ yaml()
+ ]
+ }
+})
+```
+
+Now we installed and configured our Vite plugin, we can start using YAML files directly in our project.
+
+For example, we can have a `config.yaml` that stores configuration data and import this data in our Nuxt components:
+
+::code-group
+
+```yaml [data/hello.yaml]
+greeting: "Hello, Nuxt with Vite!"
+```
+
+```vue [components/Hello.vue]
+
+
+
+ (
+ url: string | (() => string),
+ options: Omit, 'default'> & { default: () => T | Ref },
+) {
+ return useFetch(url, {
+ ...options,
+ $fetch: useNuxtApp().$api
+ })
+}
+```
+
+Let's use the new composable and have a nice and clean component:
+
+```vue [app.vue]
+
+```
+
+::callout{icon="i-simple-icons-youtube" color="red" to="https://www.youtube.com/watch?v=jXH8Tr-exhI"}
+Watch a video about custom `$fetch` and Repository Pattern in Nuxt.
+::
+
+::note
+We are currently discussing to find a cleaner way to let you create a custom fetcher, see https://github.com/nuxt/nuxt/issues/14736.
+::
diff --git a/docs/2.guide/4.recipes/_dir.yml b/docs/2.guide/4.recipes/_dir.yml
new file mode 100644
index 0000000000..b63c755e5f
--- /dev/null
+++ b/docs/2.guide/4.recipes/_dir.yml
@@ -0,0 +1,3 @@
+title: Recipes
+titleTemplate: '%s Β· Recipes'
+icon: i-ph-cooking-pot-duotone
diff --git a/docs/3.api/1.components/1.client-only.md b/docs/3.api/1.components/1.client-only.md
index 481ab8ab9c..86e56d2547 100644
--- a/docs/3.api/1.components/1.client-only.md
+++ b/docs/3.api/1.components/1.client-only.md
@@ -8,7 +8,11 @@ links:
size: xs
---
-The `` component renders its slot only in client-side. To import a component only on the client, register the component in a client-side only plugin.
+The `` component is used for purposely rendering a component only on client side.
+
+::note
+The content of the default slot will be tree-shaken out of the server build. (This does mean that any CSS used by components within it may not be inlined when rendering the initial HTML.)
+::
## Props
@@ -19,6 +23,7 @@ The `` component renders its slot only in client-side. To import a c
@@ -28,14 +33,16 @@ The `` component renders its slot only in client-side. To import a c
## Slots
-- `#fallback`: specify a content to be displayed server-side.
+- `#fallback`: specify a content to be rendered on the server and displayed until `` is mounted in the browser.
-```vue
+```vue [pages/example.vue]
-
+
+
+
+ '
+description: Render components only during development with the component.
+links:
+ - label: Source
+ icon: i-simple-icons-github
+ to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/dev-only.ts
+ size: xs
+---
+
+Nuxt provides the `` component to render a component only during development.
+
+The content will not be included in production builds.
+
+```vue [pages/example.vue]
+
+ ` component to render its content on the client if any of its children trigger an error in SSR.
+
::note{to="/docs/guide/going-further/experimental-features#clientfallback"}
This component is experimental and in order to use it you must enable the `experimental.clientFallback` option in your `nuxt.config`.
::
+```vue [pages/example.vue]
+
+ '
+description: 'Add a hidden element with the page title for assistive technologies.'
+navigation:
+ badge: New
+links:
+ - label: Source
+ icon: i-simple-icons-github
+ to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-route-announcer.ts
+ size: xs
+---
+
+::important
+This component is available in Nuxt v3.12+.
+::
+
+## Usage
+
+Add `
+
+
+```
+
+## Slots
+
+You can pass custom HTML or components through the route announcer default slot.
+
+```vue
+
+
+
+
+
+```
+
+## Props
+
+- `atomic`: Controls if screen readers announce only changes or the entire content. Set to true for full content readout on updates, false for changes only. (default `false`)
+- `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)
+
+::callout
+This component is optional. :br
+To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-route-announcer.ts).
+::
+
+::callout
+You can hook into the underlying announcer instance using [the `useRouteAnnouncer` composable](/docs/api/composables/use-route-announcer), which allows you to set a custom announcement message.
+::
diff --git a/docs/3.api/1.components/2.nuxt-page.md b/docs/3.api/1.components/2.nuxt-page.md
index dd57c2fb0c..c8930e350c 100644
--- a/docs/3.api/1.components/2.nuxt-page.md
+++ b/docs/3.api/1.components/2.nuxt-page.md
@@ -86,6 +86,18 @@ function logFoo () {
````
+````vue [my-page.vue]
+
+````
+
## Custom Props
In addition, `` also accepts custom props that you may need to pass further down the hierarchy.
diff --git a/docs/3.api/1.components/3.nuxt-layout.md b/docs/3.api/1.components/3.nuxt-layout.md
index cc8bf04191..1ff8168ade 100644
--- a/docs/3.api/1.components/3.nuxt-layout.md
+++ b/docs/3.api/1.components/3.nuxt-layout.md
@@ -55,6 +55,10 @@ Please note the layout name is normalized to kebab-case, so if your layout file
Read more about dynamic layouts.
::
+- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/guide/directory-structure/layouts) directory.
+ - **type**: `string`
+ - **default**: `null`
+
## Additional Props
`NuxtLayout` also accepts any additional props that you may need to pass to the layout. These custom props are then made accessible as attributes.
@@ -83,6 +87,8 @@ console.log(layoutCustomProps.title) // I am a custom layout
`
+
+
+```
+
+This will be translated to:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+ routeRules: {
+ "/": { prerender: true },
+ },
+});
+```
+
+## Runtime prerender configuration
+
+### `prerenderRoutes`
+
+You can use this at runtime within a [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context) to add more routes for Nitro to prerender.
+
+```vue [pages/index.vue]
+
+
+
+ Homepage
+Pre-rendered at build time
+
+
+
+```
+
+:read-more{title="prerenderRoutes" to="/docs/api/utils/prerender-routes"}
+
+### `prerender:routes` Nuxt hook
+
+This is called before prerendering for additional routes to be registered.
+
+```ts [nitro.config.ts]
+export default defineNuxtConfig({
+ hooks: {
+ async "prerender:routes"(ctx) {
+ const { pages } = await fetch("https://api.some-cms.com/pages").then(
+ (res) => res.json(),
+ );
+ for (const page of pages) {
+ ctx.routes.add(`/${page.name}`);
+ }
+ },
+ },
+});
+```
+
+### `prerender:generate` Nitro hook
+
+This is called for each route during prerendering. You can use this for fine grained handling of each route that gets prerendered.
+
+```ts [nitro.config.ts]
+export default defineNuxtConfig({
+ nitro: {
+ hooks: {
+ "prerender:generate"(route) {
+ if (route.route?.includes("private")) {
+ route.skip = true;
+ }
+ },
+ },
+ },
+});
+```
diff --git a/docs/2.guide/0.index.md b/docs/2.guide/0.index.md
index b45915e129..a93d01cdb6 100644
--- a/docs/2.guide/0.index.md
+++ b/docs/2.guide/0.index.md
@@ -16,4 +16,7 @@ surround: false
::card{icon="i-ph-star-duotone" title="Going Further" to="/docs/guide/going-further"}
Master Nuxt with advanced concepts like experimental features, hooks, modules, and more.
::
+ ::card{icon="i-ph-book-open-duotone" title="Recipes" to="/docs/guide/recipes"}
+ Find solutions to common problems and learn how to implement them in your Nuxt project.
+ ::
::
diff --git a/docs/2.guide/1.concepts/1.auto-imports.md b/docs/2.guide/1.concepts/1.auto-imports.md
index b26265d3c6..a7e24cd843 100644
--- a/docs/2.guide/1.concepts/1.auto-imports.md
+++ b/docs/2.guide/1.concepts/1.auto-imports.md
@@ -60,6 +60,10 @@ That means that (with very few exceptions) you cannot use them outside a Nuxt pl
If you get an error message like `Nuxt instance is unavailable` then it probably means you are calling a Nuxt composable in the wrong place in the Vue or Nuxt lifecycle.
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=ofuKRZLtOdY" target="_blank"}
+Watch a video from Alexander Lichter about handling async code in composables and fixing `Nuxt instance is unavailable` in your app.
+::
+
::read-more{to="/docs/guide/going-further/experimental-features#asynccontext" icon="i-ph-star-duotone"}
Checkout the `asyncContext` experimental feature to use Nuxt composables in async functions.
::
@@ -84,7 +88,7 @@ export const useMyComposable = () => {
```ts twoslash [composables/example.ts]
export const useMyComposable = () => {
// Because your composable is called in the right place in the lifecycle,
- // useRuntimeConfig will also work
+ // useRuntimeConfig will work here
const config = useRuntimeConfig()
// ...
@@ -168,3 +172,7 @@ export default defineNuxtConfig({
}
})
```
+
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=FT2LQJ2NvVI" target="_blank"}
+Watch a video from Alexander Lichter on how to easily set up custom auto imports.
+::
diff --git a/docs/2.guide/1.concepts/2.vuejs-development.md b/docs/2.guide/1.concepts/2.vuejs-development.md
index 83ef27cde3..2725ffea36 100644
--- a/docs/2.guide/1.concepts/2.vuejs-development.md
+++ b/docs/2.guide/1.concepts/2.vuejs-development.md
@@ -1,6 +1,6 @@
---
title: 'Vue.js Development'
-description: "Nuxt uses Vue.js and adds features such as component auto-imports, file-based routing and composables for a SSR-friendly usage."
+description: "Nuxt uses Vue.js and adds features such as component auto-imports, file-based routing and composables for an SSR-friendly usage."
---
Nuxt integrates Vue 3, the new major release of Vue that enables new patterns for Nuxt users.
diff --git a/docs/2.guide/1.concepts/3.rendering.md b/docs/2.guide/1.concepts/3.rendering.md
index 3c4fa6ca56..8bfe220a30 100644
--- a/docs/2.guide/1.concepts/3.rendering.md
+++ b/docs/2.guide/1.concepts/3.rendering.md
@@ -69,6 +69,36 @@ If you do use `ssr: false`, you should also place an HTML file in `~/app/spa-loa
:read-more{title="SPA Loading Template" to="/docs/api/configuration/nuxt-config#spaloadingtemplate"}
::
+::tip{to="https://www.youtube.com/watch?v=7Lr0QTP1Ro8" icon="i-logos-youtube-icon" target="_blank"}
+Watch a video from Alexander Lichter about **Building a plain SPA with Nuxt!?**.
+::
+
+### Deploying a Static Client-Rendered App
+
+If you deploy your app to [static hosting](/docs/getting-started/deployment#static-hosting) with the `nuxi generate` or `nuxi build --prerender` commands, then by default, Nuxt will render every page as a separate static HTML file.
+
+If you are using purely client-side rendering, then this might be unnecessary. You might only need a single `index.html` file, plus `200.html` and `404.html` fallbacks, which you can tell your static web host to serve up for all requests.
+
+In order to achieve this we can change how the routes are prerendered. Just add this to [your hooks](/docs/api/advanced/hooks#nuxt-hooks-build-time) in your `nuxt.config.ts`:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+ hooks: {
+ 'prerender:routes' ({ routes }) {
+ routes.clear() // Do not generate any routes (except the defaults)
+ }
+ },
+})
+```
+
+This will produce three files:
+
+- `index.html`
+- `200.html`
+- `404.html`
+
+The `200.html` and `404.html` might be useful for the hosting provider you are using.
+
## Hybrid Rendering
Hybrid rendering allows different caching rules per route using **Route Rules** and decides how the server should respond to a new request on a given URL.
@@ -109,10 +139,11 @@ The different properties you can use are the following:
- `ssr: boolean`{lang=ts} - Disables server-side rendering for sections of your app and make them SPA-only with `ssr: false`
- `cors: boolean`{lang=ts} - Automatically adds cors headers with `cors: true` - you can customize the output by overriding with `headers`
- `headers: object`{lang=ts} - Add specific headers to sections of your site - for example, your assets
-- `swr: number|boolean`{lang=ts} - Add cache headers to the server response and cache it on the server or reverse proxy for a configurable TTL (time to live). The `node-server` preset of Nitro is able to cache the full response. When the TTL expired, the cached response will be sent while the page will be regenerated in the background. If true is used, a `stale-while-revalidate` header is added without a MaxAge.
-- `isr: number|boolean`{lang=ts} - The behavior is the same as `swr` except that we are able to add the response to the CDN cache on platforms that support this (currently Netlify or Vercel). If `true` is used, the content persists until the next deploy inside the CDN.
-- `prerender:boolean`{lang=ts} - Prerenders routes at build time and includes them in your build as static assets
+- `swr: number | boolean`{lang=ts} - Add cache headers to the server response and cache it on the server or reverse proxy for a configurable TTL (time to live). The `node-server` preset of Nitro is able to cache the full response. When the TTL expired, the cached response will be sent while the page will be regenerated in the background. If true is used, a `stale-while-revalidate` header is added without a MaxAge.
+- `isr: number | boolean`{lang=ts} - The behavior is the same as `swr` except that we are able to add the response to the CDN cache on platforms that support this (currently Netlify or Vercel). If `true` is used, the content persists until the next deploy inside the CDN.
+- `prerender: boolean`{lang=ts} - Prerenders routes at build time and includes them in your build as static assets
- `experimentalNoScripts: boolean`{lang=ts} - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
+- `appMiddleware: string | string[] | RecordThis will register other routes for prerendering when prerendered
+
-
-
-
-
-
-```
-
-Use a slot as fallback until `
-
-
-
-
-
-```
-
-
-
-
-## `Loading comments...
- -
-
-
-
-
-
-```
-
-## `
-
-
-
-
-```
## Library Authors
diff --git a/docs/2.guide/2.directory-structure/1.middleware.md b/docs/2.guide/2.directory-structure/1.middleware.md
index 22c63eb24a..64e66ecf6d 100644
--- a/docs/2.guide/2.directory-structure/1.middleware.md
+++ b/docs/2.guide/2.directory-structure/1.middleware.md
@@ -125,15 +125,19 @@ However, if you want to avoid this behaviour you can do so:
```ts twoslash [middleware/example.ts]
export default defineNuxtRouteMiddleware(to => {
// skip middleware on server
- if (process.server) return
+ if (import.meta.server) return
// skip middleware on client side entirely
- if (process.client) return
+ if (import.meta.client) return
// or only skip middleware on initial client load
const nuxtApp = useNuxtApp()
- if (process.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) return
+ if (import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) return
})
```
+::note
+Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/getting-started/error-handling#useerror) in middleware to check if an error is being handled.
+::
+
## Adding Middleware Dynamically
It is possible to add global or named route middleware manually using the [`addRouteMiddleware()`](/docs/api/utils/add-route-middleware) helper function, such as from within a plugin.
diff --git a/docs/2.guide/2.directory-structure/1.modules.md b/docs/2.guide/2.directory-structure/1.modules.md
index b98df654e6..ce9de8f9f2 100644
--- a/docs/2.guide/2.directory-structure/1.modules.md
+++ b/docs/2.guide/2.directory-structure/1.modules.md
@@ -46,7 +46,11 @@ export default defineEventHandler(() => {
When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available.
-Local modules are registered in alphabetical order. You can change the order by adding a number to the front of each directory name:
+Modules are executed in the following sequence:
+- First, the modules defined in [`nuxt.config.ts`](/docs/api/nuxt-config#modules-1) are loaded.
+- Then, modules found in the `modules/` directory are executed, and they load in alphabetical order.
+
+You can change the order of local module by adding a number to the front of each directory name:
```bash [Directory structure]
modules/
@@ -56,3 +60,7 @@ modules/
```
:read-more{to="/docs/guide/going-further/modules"}
+
+::tip{icon="i-ph-video-duotone" to="https://vueschool.io/lessons/creating-your-first-module-from-scratch" target="_blank"}
+Watch Vue School video about Nuxt private modules.
+::
diff --git a/docs/2.guide/2.directory-structure/1.pages.md b/docs/2.guide/2.directory-structure/1.pages.md
index 2332295f8a..ef83deb8da 100644
--- a/docs/2.guide/2.directory-structure/1.pages.md
+++ b/docs/2.guide/2.directory-structure/1.pages.md
@@ -6,7 +6,7 @@ navigation.icon: i-ph-folder-duotone
---
::note
-To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/guide/directory-structure/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`app/router.options.ts`](/docs/guide/directory-structure/pages#router-options).
+To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/guide/directory-structure/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`app/router.options.ts`](/docs/guide/going-further/custom-routing#using-approuteroptions).
::
## Usage
@@ -57,7 +57,7 @@ If you are using [`app.vue`](/docs/guide/directory-structure/app), make sure to
```
-Pages **must have a single root element** to allow [route transitions](/docs/getting-started/transitions) between pages, HTML comments are considered elements as well.
+Pages **must have a single root element** to allow [route transitions](/docs/getting-started/transitions) between pages. HTML comments are considered elements as well.
This means that when the route is server-rendered, or statically generated, you will be able to see its contents correctly, but when you navigate towards that route during client-side navigation the transition between routes will fail and you'll see that the route will not be rendered.
@@ -193,6 +193,14 @@ To display the `child.vue` component, you have to insert the `{{ config.greeting }}
+ +``` + +:: diff --git a/docs/2.guide/4.recipes/3.custom-usefetch.md b/docs/2.guide/4.recipes/3.custom-usefetch.md new file mode 100644 index 0000000000..e27af2712f --- /dev/null +++ b/docs/2.guide/4.recipes/3.custom-usefetch.md @@ -0,0 +1,105 @@ +--- +navigation.title: 'Custom useFetch' +title: Custom useFetch in Nuxt +description: How to create a custom fetcher for calling your external API in Nuxt 3. +--- + +When working with Nuxt, you might be making the frontend and fetching an external API, and you might want to set some default options for fetching from your API. + +The [`$fetch`](/docs/api/utils/dollarfetch) utility function (used by the [`useFetch`](/docs/api/composables/use-fetch) composable) is intentionally not globally configurable. This is important so that fetching behavior throughout your application remains consistent, and other integrations (like modules) can rely on the behavior of core utilities like `$fetch`. + +However, Nuxt provides a way to create a custom fetcher for your API (or multiple fetchers if you have multiple APIs to call). + +## Custom `$fetch` + +Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/guide/directory-structure/plugins). + +::note +`$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips). +:: + +Let's pretend here that: +- The main API is https://api.nuxt.com +- We are storing the JWT token in a session with [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils) +- If the API responds with a `401` status code, we redirect the user to the `/login` page + +```ts [plugins/api.ts] +export default defineNuxtPlugin(() => { + const { session } = useUserSession() + + const api = $fetch.create({ + baseURL: 'https://api.nuxt.com', + onRequest({ request, options, error }) { + if (session.value?.token) { + const headers = options.headers ||= {} + if (Array.isArray(headers)) { + headers.push(['Authorization', `Bearer ${session.value?.token}`]) + } else if (headers instanceof Headers) { + headers.set('Authorization', `Bearer ${session.value?.token}`) + } else { + headers.Authorization = `Bearer ${session.value?.token}` + } + } + }, + async onResponseError({ response }) { + if (response.status === 401) { + await navigateTo('/login') + } + } + }) + + // Expose to useNuxtApp().$api + return { + provide: { + api + } + } +}) +``` + +With this Nuxt plugin, `$api` is exposed from `useNuxtApp()` to make API calls directly from the Vue components: + +```vue [app.vue] + +``` + +::callout +Wrapping with [`useAsyncData`](/docs/api/composables/use-async-data) **avoid double data fetching when doing server-side rendering** (server & client on hydration). +:: + +## Custom `useFetch` + +Now that `$api` has the logic we want, let's create a `useAPI` composable to replace the usage of `useAsyncData` + `$api`: + +```ts [composables/useAPI.ts] +import type { UseFetchOptions } from 'nuxt/app' + +export function useAPILoading comments...
diff --git a/docs/3.api/1.components/1.dev-only.md b/docs/3.api/1.components/1.dev-only.md new file mode 100644 index 0000000000..a65b5cbc56 --- /dev/null +++ b/docs/3.api/1.components/1.dev-only.md @@ -0,0 +1,51 @@ +--- +title: '
+
+
+
+
+
+```
+
+## Slots
+
+- `#fallback`: if you ever require to have a replacement during production.
+
+```vue
+
+
+
+
+
+
+
+```
diff --git a/docs/3.api/1.components/1.nuxt-client-fallback.md b/docs/3.api/1.components/1.nuxt-client-fallback.md
index 1f07dd09fa..22d9d6b6f0 100644
--- a/docs/3.api/1.components/1.nuxt-client-fallback.md
+++ b/docs/3.api/1.components/1.nuxt-client-fallback.md
@@ -12,10 +12,25 @@ links:
size: xs
---
+Nuxt provides the `
+
+
+
+
+```
+
## Events
- `@ssr-error`: Event emitted when a child triggers an error in SSR. Note that this will only be triggered on the server.
@@ -30,7 +45,7 @@ This component is experimental and in order to use it you must enable the `exper
## Props
-- `placeholderTag` | `fallbackTag`: Specify a fallback tag to be rendered if the slot fails to render.
+- `placeholderTag` | `fallbackTag`: Specify a fallback tag to be rendered if the slot fails to render on the server.
- **type**: `string`
- **default**: `div`
- `placeholder` | `fallback`: Specify fallback content to be rendered if the slot fails to render.
diff --git a/docs/3.api/1.components/12.nuxt-route-announcer.md b/docs/3.api/1.components/12.nuxt-route-announcer.md
new file mode 100644
index 0000000000..b53f9fa925
--- /dev/null
+++ b/docs/3.api/1.components/12.nuxt-route-announcer.md
@@ -0,0 +1,56 @@
+---
+title: '{{ message }} was loaded.
+ +
@@ -93,13 +99,27 @@ console.log(layoutCustomProps.title) // I am a custom layout
```
+```vue [layouts/custom.vue]
+
+
+ default layout
+
-````
+```
+
+```vue [layouts/default.vue]
+
+
+
+ ` component to link to another page of the ap
```
+### Passing Params to Dynamic Routes
+
+In this example, we pass the `id` param to link to the route `~/pages/posts/[id].vue`.
+
+```vue [pages/index.vue]
+
+
+ Post 123
+
+
+```
+
+::tip
+Check out the Pages panel in Nuxt DevTools to see the route name and the params it might take.
+::
+
### Handling 404s
When using `` for `/public` directory files or when pointing to a different app on the same domain, you should use the `external` prop.
diff --git a/docs/3.api/1.components/5.nuxt-loading-indicator.md b/docs/3.api/1.components/5.nuxt-loading-indicator.md
index e22b582422..ad2f6936cb 100644
--- a/docs/3.api/1.components/5.nuxt-loading-indicator.md
+++ b/docs/3.api/1.components/5.nuxt-loading-indicator.md
@@ -30,6 +30,7 @@ You can pass custom HTML or components through the loading indicator's default s
## Props
- `color`: The color of the loading bar. It can be set to `false` to turn off explicit color styling.
+- `errorColor`: The color of the loading bar when `error` is set to `true`.
- `height`: Height of the loading bar, in pixels (default `3`).
- `duration`: Duration of the loading bar, in milliseconds (default `2000`).
- `throttle`: Throttle the appearing and hiding, in milliseconds (default `200`).
diff --git a/docs/3.api/1.components/8.nuxt-island.md b/docs/3.api/1.components/8.nuxt-island.md
index ae2df6cd05..2ede46ad88 100644
--- a/docs/3.api/1.components/8.nuxt-island.md
+++ b/docs/3.api/1.components/8.nuxt-island.md
@@ -12,10 +12,6 @@ When rendering an island component, the content of the island component is stati
Changing the island component props triggers a refetch of the island component to re-render it again.
-::read-more{to="/docs/guide/going-further/experimental-features#componentislands" icon="i-ph-star-duotone"}
-This component is experimental and in order to use it you must enable the `experimental.componentIslands` option in your `nuxt.config`.
-::
-
::note
Global styles of your application are sent with the response.
::
@@ -63,3 +59,11 @@ Some slots are reserved to `NuxtIsland` for special cases.
- `refresh()`
- **type**: `() => Promise`
- **description**: force refetch the server component by refetching it.
+
+## Events
+
+- `error`
+ - **parameters**:
+ - **error**:
+ - **type**: `unknown`
+ - **description**: emitted when when `NuxtIsland` fails to fetch the new island.
diff --git a/docs/3.api/2.composables/on-prehydrate.md b/docs/3.api/2.composables/on-prehydrate.md
new file mode 100644
index 0000000000..1f034d6cec
--- /dev/null
+++ b/docs/3.api/2.composables/on-prehydrate.md
@@ -0,0 +1,61 @@
+---
+title: "onPrehydrate"
+description: "Use onPrehydrate to run a callback on the client immediately before
+Nuxt hydrates the page."
+links:
+ - label: Source
+ icon: i-simple-icons-github
+ to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ssr.ts
+ size: xs
+---
+
+::important
+This composable is available in Nuxt v3.12+.
+::
+
+`onPrehydrate` is a composable lifecycle hook that allows you to run a callback on the client immediately before
+Nuxt hydrates the page.
+
+::note
+This is an advanced utility and should be used with care. For example, [`nuxt-time`](https://github.com/danielroe/nuxt-time/pull/251) and [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode/blob/main/src/script.js) manipulate the DOM to avoid hydration mismatches.
+::
+
+## Usage
+
+`onPrehydrate` can be called directly in the setup function of a Vue component (for example, in `
+
+
+ = {
deep?: boolean
dedupe?: 'cancel' | 'defer'
default?: () => DataT | Ref | null
- transform?: (input: DataT) => DataT
+ transform?: (input: DataT) => DataT | Promise
pick?: string[]
watch?: WatchSource[]
- getCachedData?: (key: string) => DataT
+ getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT
}
type AsyncData = {
@@ -130,6 +130,7 @@ type AsyncData = {
pending: Ref
refresh: (opts?: AsyncDataExecuteOptions) => Promise
execute: (opts?: AsyncDataExecuteOptions) => Promise
+ clear: () => void
error: Ref
status: Ref
};
diff --git a/docs/3.api/2.composables/use-cookie.md b/docs/3.api/2.composables/use-cookie.md
index 4319f7f05b..804d3e2784 100644
--- a/docs/3.api/2.composables/use-cookie.md
+++ b/docs/3.api/2.composables/use-cookie.md
@@ -59,13 +59,10 @@ Use these options to set the expiration of the cookie.
The given number will be converted to an integer by rounding down. By default, no maximum age is set.
`expires`: Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).
-By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and
-will delete it on a condition like exiting a web browser application.
+By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application.
::note
-The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
-`maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this,
-so if both are set, they should point to the same date and time!
+The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time!
::
::note
@@ -74,22 +71,29 @@ If neither of `expires` and `maxAge` is set, the cookie will be session-only and
### `httpOnly`
-Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6). When truthy,
-the `HttpOnly` attribute is set; otherwise it is not. By default, the `HttpOnly` attribute is not set.
+Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6). When truthy, the `HttpOnly` attribute is set; otherwise it is not. By default, the `HttpOnly` attribute is not set.
::warning
-Be careful when setting this to `true`, as compliant clients will not allow client-side
-JavaScript to see the cookie in `document.cookie`.
+Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
::
### `secure`
-Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy,
-the `Secure` attribute is set; otherwise it is not. By default, the `Secure` attribute is not set.
+Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy, the `Secure` attribute is set; otherwise it is not. By default, the `Secure` attribute is not set.
::warning
-Be careful when setting this to `true`, as compliant clients will not send the cookie back to
-the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.
+Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.
+::
+
+### `partitioned`
+
+Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1) attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the `Partitioned` attribute is not set.
+
+::note
+This is an attribute that has not yet been fully standardized, and may change in the future.
+This also means many clients may ignore this attribute until they understand it.
+
+More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
::
### `domain`
@@ -114,23 +118,18 @@ More information about the different enforcement levels can be found in [the spe
### `encode`
-Specifies a function that will be used to encode a cookie's value. Since the value of a cookie
-has a limited character set (and must be a simple string), this function can be used to encode
-a value into a string suited for a cookie's value.
+Specifies a function that will be used to encode a cookie's value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value.
The default encoder is the `JSON.stringify` + `encodeURIComponent`.
### `decode`
-Specifies a function that will be used to decode a cookie's value. Since the value of a cookie
-has a limited character set (and must be a simple string), this function can be used to decode
-a previously encoded cookie value into a JavaScript string or other object.
+Specifies a function that will be used to decode a cookie's value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object.
The default decoder is `decodeURIComponent` + [destr](https://github.com/unjs/destr).
::note
-If an error is thrown from this function, the original, non-decoded cookie value will
-be returned as the cookie's value.
+If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value.
::
### `default`
diff --git a/docs/3.api/2.composables/use-fetch.md b/docs/3.api/2.composables/use-fetch.md
index 96bfa3850e..84a73d0fc9 100644
--- a/docs/3.api/2.composables/use-fetch.md
+++ b/docs/3.api/2.composables/use-fetch.md
@@ -1,6 +1,6 @@
---
title: 'useFetch'
-description: 'Fetch data from an API endpoint with a SSR-friendly composable.'
+description: 'Fetch data from an API endpoint with an SSR-friendly composable.'
links:
- label: Source
icon: i-simple-icons-github
@@ -66,6 +66,10 @@ const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
`useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
::
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=njsGVmcWviY" target="_blank"}
+Watch the video from Alexander Lichter to avoid using `useFetch` the wrong way!
+::
+
:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
:read-more{to="/docs/getting-started/data-fetching"}
@@ -83,6 +87,8 @@ const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
- `headers`: Request headers.
- `baseURL`: Base URL for the request.
- `timeout`: Milliseconds to automatically abort request
+ - `cache`: Handles cache control according to [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache)
+ - You can pass boolean to disable the cache or you can pass one of the following values: `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`.
::note
All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -97,7 +103,7 @@ All fetch options can be given a `computed` or `ref` value. These will be watche
- `transform`: a function that can be used to alter `handler` function result after resolving
- `getCachedData`: Provide a function which returns cached data. A _null_ or _undefined_ return value will trigger a fetch. By default, this is: `key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key]`, which only caches data when `payloadExtraction` is enabled.
- `pick`: only pick specified keys in this array from the `handler` function result
- - `watch`: watch an array of reactive sources and auto-refresh the fetch result when they change. Fetch options and URL are watched by default. You can completely ignore reactive sources by using `watch: false`. Together with `immediate: false`, this allows for a fully-manual `useFetch`.
+ - `watch`: watch an array of reactive sources and auto-refresh the fetch result when they change. Fetch options and URL are watched by default. You can completely ignore reactive sources by using `watch: false`. Together with `immediate: false`, this allows for a fully-manual `useFetch`. (You can [see an example here](/docs/getting-started/data-fetching#watch) of using `watch`.)
- `deep`: return data in a deep ref object (it is `true` by default). It can be set to `false` to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive.
- `dedupe`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
- `cancel` - cancels existing requests when a new one is made
@@ -107,6 +113,10 @@ All fetch options can be given a `computed` or `ref` value. These will be watche
If you provide a function or ref as the `url` parameter, or if you provide functions as arguments to the `options` parameter, then the `useFetch` call will not match other `useFetch` calls elsewhere in your codebase, even if the options seem to be identical. If you wish to force a match, you may provide your own key in `options`.
::
+::note
+If you use `useFetch` to call an (external) HTTPS URL with a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
+::
+
::tip{icon="i-simple-icons-youtube" color="gray" to="https://www.youtube.com/watch?v=aQPR0xn-MMk" target="_blank"}
Learn how to use `transform` and `getCachedData` to avoid superfluous calls to an API and cache data for visitors on the client.
::
@@ -144,11 +154,11 @@ type UseFetchOptions = {
server?: boolean
lazy?: boolean
immediate?: boolean
- getCachedData?: (key: string) => DataT
+ getCachedData?: (key: string, nuxtApp: NuxtApp) => DataT
deep?: boolean
dedupe?: 'cancel' | 'defer'
default?: () => DataT
- transform?: (input: DataT) => DataT
+ transform?: (input: DataT) => DataT | Promise
pick?: string[]
watch?: WatchSource[] | false
}
@@ -158,6 +168,7 @@ type AsyncData = {
pending: Ref
refresh: (opts?: AsyncDataExecuteOptions) => Promise
execute: (opts?: AsyncDataExecuteOptions) => Promise
+ clear: () => void
error: Ref
status: Ref
}
diff --git a/docs/3.api/2.composables/use-id.md b/docs/3.api/2.composables/use-id.md
index 63a470a5db..6a29535f88 100644
--- a/docs/3.api/2.composables/use-id.md
+++ b/docs/3.api/2.composables/use-id.md
@@ -1,6 +1,11 @@
---
title: "useId"
description: Generate an SSR-friendly unique identifier that can be passed to accessibility attributes.
+links:
+ - label: Source
+ icon: i-simple-icons-github
+ to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/id.ts
+ size: xs
---
::important
@@ -19,11 +24,15 @@ const id = useId()
`
- **description**: The loading state
+### `error`
+
+- **type**: `Ref`
+- **description**: The error state
+
### `progress`
- **type**: `Ref`
@@ -39,7 +44,7 @@ Set `isLoading` to true and start to increase the `progress` value.
### `finish()`
-Set the `progress` value to `100`, stop all timers and intervals then reset the loading state `500` ms later.
+Set the `progress` value to `100`, stop all timers and intervals then reset the loading state `500` ms later. `finish` accepts a `{ force: true }` option to skip the interval before the state is reset, and `{ error: true }` to change the loading bar color and set the error property to true.
### `clear()`
diff --git a/docs/3.api/2.composables/use-nuxt-app.md b/docs/3.api/2.composables/use-nuxt-app.md
index 20fcefccd7..860cb89c22 100644
--- a/docs/3.api/2.composables/use-nuxt-app.md
+++ b/docs/3.api/2.composables/use-nuxt-app.md
@@ -18,6 +18,14 @@ const nuxtApp = useNuxtApp()
If runtime context is unavailable in your scope, `useNuxtApp` will throw an exception when called. You can use [`tryUseNuxtApp`](#tryusenuxtapp) instead for composables that do not require `nuxtApp`, or to simply check if context is available or not without an exception.
+
+
## Methods
### `provide (name, value)`
@@ -51,7 +59,7 @@ export default defineNuxtPlugin((nuxtApp) => {
})
nuxtApp.hook('vue:error', (..._args) => {
console.log('vue:error')
- // if (process.client) {
+ // if (import.meta.client) {
// console.log(..._args)
// }
})
@@ -120,7 +128,7 @@ Nuxt exposes the following properties through `ssrContext`:
export const useColor = () => useState('color', () => 'pink')
export default defineNuxtPlugin((nuxtApp) => {
- if (process.server) {
+ if (import.meta.server) {
const color = useColor()
}
})
@@ -128,9 +136,13 @@ Nuxt exposes the following properties through `ssrContext`:
It is also possible to use more advanced types, such as `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError`.
- Since [Nuxt v3.4](https://nuxt.com/blog/v3-4#payload-enhancements), it is possible to define your own serializer/deserializer for types that are not supported by Nuxt.
+ Since [Nuxt v3.4](https://nuxt.com/blog/v3-4#payload-enhancements), it is possible to define your own reducer/reviver for types that are not supported by Nuxt.
- In the example below, we define a serializer for the [Luxon](https://moment.github.io/luxon/#/) DateTime class.
+ ::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=8w6ffRBs8a4" target="_blank"}
+ Watch a video from Alexander Lichter about serializing payloads, especially with regards to classes.
+ ::
+
+ In the example below, we define a reducer (or a serializer) and a reviver (or deserializer) for the [Luxon](https://moment.github.io/luxon/#/) DateTime class, using a payload plugin.
```ts [plugins/date-time-payload.ts]
/**
@@ -159,7 +171,7 @@ export default defineComponent({
setup (_props, { slots, emit }) {
const nuxtApp = useNuxtApp()
onErrorCaptured((err) => {
- if (process.client && !nuxtApp.isHydrating) {
+ if (import.meta.client && !nuxtApp.isHydrating) {
// ...
}
})
@@ -278,3 +290,7 @@ export function useStandType() {
}
}
```
+
+
diff --git a/docs/3.api/2.composables/use-preview-mode.md b/docs/3.api/2.composables/use-preview-mode.md
new file mode 100644
index 0000000000..34450bc339
--- /dev/null
+++ b/docs/3.api/2.composables/use-preview-mode.md
@@ -0,0 +1,99 @@
+---
+title: "usePreviewMode"
+description: "Use usePreviewMode to check and control preview mode in Nuxt"
+links:
+ - label: Source
+ icon: i-simple-icons-github
+ to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/preview.ts
+ size: xs
+---
+
+# `usePreviewMode`
+
+Preview mode allows you to see how your changes would be displayed on a live site without revealing them to users.
+
+You can use the built-in `usePreviewMode` composable to access and control preview state in Nuxt. If the composable detects preview mode it will automatically force any updates necessary for [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch) to rerender preview content.
+
+```js
+const { enabled, state } = usePreviewMode()
+```
+
+## Options
+
+### Custom `enable` check
+
+You can specify a custom way to enable preview mode. By default the `usePreviewMode` composable will enable preview mode if there is a `preview` param in url that is equal to `true` (for example, `http://localhost:3000?preview=true`). You can wrap the `usePreviewMode` into custom composable, to keep options consistent across usages and prevent any errors.
+
+```js
+export function useMyPreviewMode () {
+ return usePreviewMode({
+ shouldEnable: () => {
+ return !!route.query.customPreview
+ }
+ });
+}
+```
+
+### Modify default state
+
+`usePreviewMode` will try to store the value of a `token` param from url in state. You can modify this state and it will be available for all [`usePreviewMode`](/docs/api/composables/use-preview-mode) calls.
+
+```js
+const data1 = ref('data1')
+
+const { enabled, state } = usePreviewMode({
+ getState: (currentState) => {
+ return { data1, data2: 'data2' }
+ }
+})
+```
+
+::note
+The `getState` function will append returned values to current state, so be careful not to accidentally overwrite important state.
+::
+
+## Example
+
+The example below creates a page where part of a content is rendered only in preview mode.
+
+```vue [pages/some-page.vue]
+
+
+
+ `](/docs/api/components/nuxt-route-announcer) and controllable.
+It hooks into Unhead's [`dom:rendered`](https://unhead.unjs.io/api/core/hooks#dom-hooks) to read the page's title and set it as the announcer message.
+
+## Parameters
+
+- `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`).
+
+## Properties
+
+### `message`
+
+- **type**: `Ref`
+- **description**: The message to announce
+
+### `politeness`
+
+- **type**: `Ref`
+- **description**: Screen reader announcement urgency level `off`, `polite`, or `assertive`
+
+## Methods
+
+### `set(message, politeness = "polite")`
+
+Sets the message to announce with its urgency level.
+
+### `polite(message)`
+
+Sets the message with `politeness = "polite"`
+
+### `assertive(message)`
+
+Sets the message with `politeness = "assertive"`
+
+## Example
+
+```ts
+
+```
diff --git a/docs/3.api/2.composables/use-seo-meta.md b/docs/3.api/2.composables/use-seo-meta.md
index 8c48d200f5..e28debae32 100644
--- a/docs/3.api/2.composables/use-seo-meta.md
+++ b/docs/3.api/2.composables/use-seo-meta.md
@@ -46,6 +46,6 @@ useSeoMeta({
## Parameters
-There are over 100 parameters. See the [full list of parameters in the source code](https://github.com/harlan-zw/zhead/blob/main/src/metaFlat.ts).
+There are over 100 parameters. See the [full list of parameters in the source code](https://github.com/harlan-zw/zhead/blob/main/packages/zhead/src/metaFlat.ts#L1035).
:read-more{to="/docs/getting-started/seo-meta"}
diff --git a/docs/3.api/2.composables/use-state.md b/docs/3.api/2.composables/use-state.md
index dccccae072..513bd407c6 100644
--- a/docs/3.api/2.composables/use-state.md
+++ b/docs/3.api/2.composables/use-state.md
@@ -25,6 +25,10 @@ Because the data inside `useState` will be serialized to JSON, it is important t
`useState` is a reserved function name transformed by the compiler, so you should not name your own function `useState`.
::
+::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=mv0WcBABcIk" target="_blank"}
+Watch a video from Alexander Lichter about why and when to use `useState()`.
+::
+
## Using `shallowRef`
If you don't need your state to be deeply reactive, you can combine `useState` with [`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref). This can improve performance when your state contains large objects and arrays.
diff --git a/docs/3.api/3.utils/$fetch.md b/docs/3.api/3.utils/$fetch.md
index 3a52ae3c78..ff0ed5cf05 100644
--- a/docs/3.api/3.utils/$fetch.md
+++ b/docs/3.api/3.utils/$fetch.md
@@ -55,3 +55,7 @@ function contactForm() {
::tip
`$fetch` is the preferred way to make HTTP calls in Nuxt instead of [@nuxt/http](https://github.com/nuxt/http) and [@nuxtjs/axios](https://github.com/nuxt-community/axios-module) that are made for Nuxt 2.
::
+
+::note
+If you use `$fetch` to call an (external) HTTPS URL with a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
+::
diff --git a/docs/3.api/3.utils/define-page-meta.md b/docs/3.api/3.utils/define-page-meta.md
index 074229ae36..5bf32546d8 100644
--- a/docs/3.api/3.utils/define-page-meta.md
+++ b/docs/3.api/3.utils/define-page-meta.md
@@ -129,7 +129,7 @@ interface PageMeta {
- **Type**: `boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean`
- Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in `~/app/router.options.ts` (see [docs](/docs/guide/directory-structure/pages/#router-options)) for more info.
+ Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in `~/app/router.options.ts` (see [custom routing](/docs/guide/going-further/custom-routing#using-approuteroptions)) for more info.
**`[key: string]`**
@@ -200,7 +200,7 @@ The two routes "/test-category" and "/1234-post" match both `[postId]-[postSlug]
To make sure that we are only matching digits (`\d+`) for `postId` in the `[postId]-[postSlug]` route, we can add the following to the `[postId]-[postSlug].vue` page template:
-```vue [pages/[postId]-[postSlug].vue]
+```vue [pages/[postId\\]-[postSlug\\].vue]
```
+::warning
+Possible breaking change: `head` receives the nuxt app but cannot access the component instance. If the code in your `head` tries to access the data object through `this` or `this.$data`, you will need to migrate to the `useHead` composable.
+::
+
## Title Template
If you want to use a function (for full control), then this cannot be set in your nuxt.config, and it is recommended instead to set it within your `/layouts` directory.
diff --git a/docs/7.migration/2.configuration.md b/docs/7.migration/2.configuration.md
index 1ee7a3d042..13508d7339 100644
--- a/docs/7.migration/2.configuration.md
+++ b/docs/7.migration/2.configuration.md
@@ -57,6 +57,45 @@ Nuxt configuration will be loaded using [`unjs/jiti`](https://github.com/unjs/ji
::
+1. If you were using `router.routeNameSplitter` you can achieve same result by updating route name generation logic in the new `pages:extend` hook:
+
+ ::code-group
+
+ ```ts [Nuxt 2]
+ export default {
+ router: {
+ routeNameSplitter: '/'
+ }
+ }
+ ```
+
+ ```ts [Nuxt 3]
+ import { createResolver } from '@nuxt/kit'
+
+ export default defineNuxtConfig({
+ hooks: {
+ 'pages:extend' (routes) {
+ const routeNameSplitter = '/'
+ const root = createResolver(import.meta.url).resolve('./pages')
+
+ function updateName(routes) {
+ if (!routes) return
+
+ for (const route of routes) {
+ const relativePath = route.file.substring(root.length + 1)
+ route.name = relativePath.slice(0, -4).replace(/\/index$/, '').replace(/\//g, routeNameSplitter)
+
+ updateName(route.children)
+ }
+ }
+ updateName(routes)
+ },
+ },
+ })
+ ```
+
+ ::
+
#### ESM Syntax
Nuxt 3 is an [ESM native framework](/docs/guide/concepts/esm). Although [`unjs/jiti`](https://github.com/unjs/jiti) provides semi compatibility when loading `nuxt.config` file, avoid any usage of `require` and `module.exports` in this file.
diff --git a/eslint.config.mjs b/eslint.config.mjs
new file mode 100644
index 0000000000..c4e282b673
--- /dev/null
+++ b/eslint.config.mjs
@@ -0,0 +1,224 @@
+// @ts-check
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
+// @ts-expect-error missing types
+import noOnlyTests from 'eslint-plugin-no-only-tests'
+import typegen from 'eslint-typegen'
+// @ts-expect-error missing types
+import perfectionist from 'eslint-plugin-perfectionist'
+
+export default createConfigForNuxt({
+ features: {
+ stylistic: {
+ commaDangle: 'always-multiline',
+ },
+ tooling: true,
+ },
+})
+ .prepend(
+ {
+ // Ignores have to be a separate object to be treated as global ignores
+ // Don't add other attributes to this object
+ ignores: [
+ 'packages/schema/schema/**',
+ 'packages/nuxt/src/app/components/welcome.vue',
+ 'packages/nuxt/src/app/components/error-*.vue',
+ 'packages/nuxt/src/core/runtime/nitro/error-*',
+ ],
+ },
+ {
+ languageOptions: {
+ globals: {
+ $fetch: 'readonly',
+ NodeJS: 'readonly',
+ },
+ },
+ name: 'local/settings',
+ settings: {
+ jsdoc: {
+ ignoreInternal: true,
+ tagNamePreference: {
+ note: 'note',
+ warning: 'warning',
+ },
+ },
+ },
+ },
+ )
+
+ .override('nuxt/javascript', {
+ rules: {
+ 'curly': ['error', 'all'], // Including if blocks with a single statement
+ 'dot-notation': 'error',
+ 'no-console': ['warn', { allow: ['warn', 'error', 'debug'] }],
+ 'no-lonely-if': 'error', // No single if in an "else" block
+ 'no-useless-rename': 'error',
+ 'object-shorthand': 'error',
+ 'prefer-const': ['error', { destructuring: 'any', ignoreReadBeforeAssign: false }],
+ 'require-await': 'error',
+ 'sort-imports': ['error', { ignoreDeclarationSort: true }],
+ },
+ })
+
+ .override('nuxt/typescript/rules', {
+ rules: {
+ '@typescript-eslint/ban-ts-comment': [
+ 'error',
+ {
+ 'ts-expect-error': 'allow-with-description',
+ 'ts-ignore': true,
+ },
+ ],
+ '@typescript-eslint/no-dynamic-delete': 'off',
+ '@typescript-eslint/no-unused-vars': [
+ 'error',
+ {
+ argsIgnorePattern: '^_',
+ ignoreRestSiblings: true,
+ varsIgnorePattern: '^_',
+ },
+ ],
+ '@typescript-eslint/triple-slash-reference': 'off',
+ '@typescript-eslint/unified-signatures': 'off',
+ ...{
+ // TODO: Discuss if we want to enable this
+ '@typescript-eslint/ban-types': 'off',
+ // TODO: Discuss if we want to enable this
+ '@typescript-eslint/no-explicit-any': 'off',
+ // TODO: Discuss if we want to enable this
+ '@typescript-eslint/no-invalid-void-type': 'off',
+ },
+ },
+ })
+
+ .override('nuxt/tooling/unicorn', {
+ rules: {
+ 'unicorn/no-new-array': 'off',
+ 'unicorn/prefer-dom-node-text-content': 'off',
+ },
+ })
+
+ .override('nuxt/vue/rules', {
+ rules: {
+
+ },
+ })
+
+ // Stylistic rules
+ .override('nuxt/stylistic', {
+ rules: {
+ '@stylistic/brace-style': ['error', '1tbs', { allowSingleLine: true }],
+ '@stylistic/indent-binary-ops': 'off',
+ '@stylistic/max-statements-per-line': 'off',
+ '@stylistic/operator-linebreak': 'off',
+ '@stylistic/quote-props': ['error', 'consistent'],
+ '@stylistic/space-before-function-paren': ['error', 'always'],
+ },
+ })
+
+ // Append local rules
+ .append(
+ {
+ files: ['**/*.vue', '**/*.ts', '**/*.mts', '**/*.js', '**/*.cjs', '**/*.mjs'],
+ name: 'local/rules',
+ rules: {
+ 'import/no-restricted-paths': [
+ 'error',
+ {
+ zones: [
+ {
+ from: 'packages/nuxt/src/!(core)/**/*',
+ message: 'core should not directly import from modules.',
+ target: 'packages/nuxt/src/core',
+ },
+ {
+ from: 'packages/nuxt/src/!(app)/**/*',
+ message: 'app should not directly import from modules.',
+ target: 'packages/nuxt/src/app',
+ },
+ {
+ from: 'packages/nuxt/src/app/**/index.ts',
+ message: 'should not import from barrel/index files',
+ target: 'packages/nuxt/src',
+ },
+ {
+ from: 'packages/nitro',
+ message: 'nitro should not directly import other packages.',
+ target: 'packages/!(nitro)/**/*',
+ },
+ ],
+ },
+ ],
+ 'import/order': [
+ 'error',
+ {
+ pathGroups: [
+ {
+ group: 'external',
+ pattern: '#vue-router',
+ },
+ ],
+ },
+ ],
+ 'jsdoc/check-tag-names': [
+ 'error',
+ {
+ definedTags: [
+ 'experimental',
+ '__NO_SIDE_EFFECTS__',
+ ],
+ },
+ ],
+ },
+ },
+ {
+ files: ['packages/nuxt/src/app/**', 'test/**', '**/runtime/**', '**/*.test.ts'],
+ name: 'local/disables/client-console',
+ rules: {
+ 'no-console': 'off',
+ },
+ },
+ {
+ files: ['**/fixtures/**', '**/fixture/**'],
+ name: 'local/disables/fixtures',
+ rules: {
+ '@typescript-eslint/no-unused-vars': 'off',
+ '@typescript-eslint/triple-slash-reference': 'off',
+ 'vue/multi-word-component-names': 'off',
+ 'vue/valid-v-for': 'off',
+ },
+ },
+ {
+ files: ['test/**', '**/*.test.ts'],
+ name: 'local/disables/tests',
+ plugins: {
+ 'no-only-tests': noOnlyTests,
+ },
+ rules: {
+ '@typescript-eslint/no-explicit-any': 'off',
+ 'no-console': 'off',
+ 'no-only-tests/no-only-tests': 'error',
+ },
+ },
+ // Sort rule keys in eslint config
+ {
+ files: ['**/eslint.config.mjs'],
+ name: 'local/sort-eslint-config',
+ plugins: {
+ perfectionist,
+ },
+ rules: {
+ 'perfectionist/sort-objects': 'error',
+ },
+ },
+ {
+ files: ['packages/nuxt/src/app/components/welcome.vue'],
+ rules: {
+ 'vue/multi-word-component-names': 'off',
+ },
+ },
+ )
+
+ // Generate type definitions for the eslint config
+ .onResolved((configs) => {
+ return typegen(configs)
+ })
diff --git a/knip.json b/knip.json
index 2ce29ce41d..dd2512b5cd 100644
--- a/knip.json
+++ b/knip.json
@@ -1,9 +1,11 @@
{
- "$schema": "https://unpkg.com/knip@2/schema.json",
+ "$schema": "https://unpkg.com/knip@5/schema.json",
"workspaces": {
".": {
"entry": [
- "scripts/*"
+ "scripts/*",
+ "test/*",
+ "test/fixtures/*"
]
},
"packages/*": {
diff --git a/lychee.toml b/lychee.toml
index a1d4196550..b7cdde5945 100644
--- a/lychee.toml
+++ b/lychee.toml
@@ -11,5 +11,8 @@ exclude = [
"https://twitter.nuxt.dev/",
"https://github.com/nuxt/translations/discussions/4",
"https://stackoverflow.com/help/minimal-reproducible-example",
- "(https?:\/\/github\.com\/)(.*\/)(generate)",
+ # TODO: remove when their SSL certificate is valid again
+ "https://www.conventionalcommits.org",
+ # single-quotes are required for regexp
+ '(https?:\/\/github\.com\/)(.*\/)(generate)',
]
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 3bcf682df1..694788ebb0 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -3,13 +3,14 @@
import { addPluginTemplate } from 'nuxt/kit'
export default defineNuxtConfig({
+ typescript: { shim: process.env.DOCS_TYPECHECK === 'true' },
pages: process.env.DOCS_TYPECHECK === 'true',
modules: [
function () {
addPluginTemplate({
filename: 'plugins/my-plugin.mjs',
- getContents: () => `export default defineNuxtPlugin({ name: 'my-plugin' })`
+ getContents: () => 'export default defineNuxtPlugin({ name: \'my-plugin\' })',
})
- }
+ },
],
})
diff --git a/package.json b/package.json
index faeaca21e6..03e833fefe 100644
--- a/package.json
+++ b/package.json
@@ -12,87 +12,90 @@
"build:stub": "pnpm dev:prepare",
"cleanup": "rimraf 'packages/**/node_modules' 'playground/node_modules' 'node_modules'",
"dev": "pnpm play",
- "dev:prepare": "pnpm --filter './packages/**' prepack --stub",
- "lint": "eslint --ext .vue,.ts,.js,.mjs .",
- "lint:fix": "eslint --ext .vue,.ts,.js,.mjs . --fix",
+ "dev:prepare": "pnpm --filter './packages/**' prepack --stub && pnpm --filter './packages/ui-templates' build",
+ "lint": "eslint . --cache",
+ "lint:fix": "eslint . --cache --fix",
"lint:docs": "markdownlint ./docs && case-police 'docs/**/*.md' *.md",
"lint:docs:fix": "markdownlint ./docs --fix && case-police 'docs/**/*.md' *.md --fix",
"lint:knip": "pnpx knip",
"play": "nuxi dev playground",
"play:build": "nuxi build playground",
+ "play:generate": "nuxi generate playground",
"play:preview": "nuxi preview playground",
"test": "pnpm test:fixtures && pnpm test:fixtures:dev && pnpm test:fixtures:webpack && pnpm test:unit && pnpm test:runtime && pnpm test:types && pnpm typecheck",
"test:prepare": "jiti ./test/prepare.ts",
"test:fixtures": "pnpm test:prepare && vitest run --dir test",
"test:fixtures:dev": "TEST_ENV=dev pnpm test:fixtures",
"test:fixtures:webpack": "TEST_BUILDER=webpack pnpm test:fixtures",
- "test:runtime": "vitest -c vitest.nuxt.config.ts --coverage",
+ "test:runtime": "vitest -c vitest.nuxt.config.ts",
"test:types": "pnpm --filter './test/fixtures/**' test:types",
- "test:unit": "vitest run packages/ --coverage",
+ "test:unit": "vitest run packages/",
"typecheck": "tsc --noEmit",
"typecheck:docs": "DOCS_TYPECHECK=true pnpm nuxi prepare && nuxt-content-twoslash verify --content-dir docs"
},
"resolutions": {
"@nuxt/kit": "workspace:*",
"@nuxt/schema": "workspace:*",
+ "@nuxt/ui-templates": "workspace:*",
"@nuxt/vite-builder": "workspace:*",
"@nuxt/webpack-builder": "workspace:*",
- "rollup": "^4.12.0",
+ "magic-string": "^0.30.10",
"nuxt": "workspace:*",
- "vite": "5.1.4",
- "vue": "3.4.20",
- "magic-string": "^0.30.7"
+ "rollup": "^4.18.0",
+ "vite": "5.3.0",
+ "vue": "3.4.27"
},
"devDependencies": {
- "@codspeed/vitest-plugin": "3.1.0",
- "@nuxt/eslint-config": "0.2.0",
+ "@eslint/js": "9.4.0",
+ "@nuxt/eslint-config": "0.3.13",
"@nuxt/kit": "workspace:*",
- "@nuxt/test-utils": "3.11.0",
+ "@nuxt/test-utils": "3.13.1",
"@nuxt/webpack-builder": "workspace:*",
- "@testing-library/vue": "8.0.2",
+ "@testing-library/vue": "8.1.0",
+ "@types/eslint__js": "8.42.3",
"@types/fs-extra": "11.0.4",
- "@types/node": "20.11.20",
+ "@types/node": "20.14.2",
"@types/semver": "7.5.8",
- "@vitest/coverage-v8": "1.3.1",
- "@vue/test-utils": "2.4.4",
+ "@unhead/schema": "1.9.13",
+ "@vitejs/plugin-vue": "5.0.4",
+ "@vitest/coverage-v8": "1.6.0",
+ "@vue/test-utils": "2.4.6",
"case-police": "0.6.1",
"changelogen": "0.5.5",
"consola": "3.2.3",
- "devalue": "4.3.2",
- "eslint": "8.57.0",
- "eslint-plugin-import": "2.29.1",
- "eslint-plugin-jsdoc": "48.2.0",
+ "devalue": "5.0.0",
+ "eslint": "9.4.0",
"eslint-plugin-no-only-tests": "3.1.0",
- "eslint-plugin-unicorn": "51.0.1",
- "execa": "8.0.1",
+ "eslint-plugin-perfectionist": "2.11.0",
+ "eslint-typegen": "0.2.4",
+ "execa": "9.2.0",
"fs-extra": "11.2.0",
"globby": "14.0.1",
"h3": "1.11.1",
- "happy-dom": "13.6.2",
- "jiti": "1.21.0",
- "markdownlint-cli": "0.39.0",
- "nitropack": "2.8.1",
- "nuxi": "3.10.1",
+ "happy-dom": "14.12.0",
+ "jiti": "1.21.6",
+ "markdownlint-cli": "0.41.0",
+ "nitropack": "2.9.6",
+ "nuxi": "3.12.0",
"nuxt": "workspace:*",
"nuxt-content-twoslash": "0.0.10",
- "ofetch": "1.3.3",
+ "ofetch": "1.3.4",
"pathe": "1.1.2",
- "playwright-core": "1.41.2",
- "rimraf": "5.0.5",
- "semver": "7.6.0",
+ "playwright-core": "1.44.1",
+ "rimraf": "5.0.7",
+ "semver": "7.6.2",
"std-env": "3.7.0",
- "typescript": "5.3.3",
- "ufo": "1.4.0",
- "vitest": "1.3.1",
+ "typescript": "5.4.5",
+ "ufo": "1.5.3",
+ "vitest": "1.6.0",
"vitest-environment-nuxt": "1.0.0",
- "vue": "3.4.20",
- "vue-eslint-parser": "9.4.2",
- "vue-router": "4.3.0",
- "vue-tsc": "2.0.1"
+ "vue": "3.4.27",
+ "vue-router": "4.3.3",
+ "vue-tsc": "2.0.21"
},
- "packageManager": "pnpm@8.15.4",
+ "packageManager": "pnpm@9.3.0",
"engines": {
- "node": "^14.18.0 || >=16.10.0"
+ "node": "^16.10.0 || >=18.0.0"
},
"version": ""
}
diff --git a/packages/kit/build.config.ts b/packages/kit/build.config.ts
index a2f84767f8..10db295927 100644
--- a/packages/kit/build.config.ts
+++ b/packages/kit/build.config.ts
@@ -3,14 +3,14 @@ import { defineBuildConfig } from 'unbuild'
export default defineBuildConfig({
declaration: true,
entries: [
- 'src/index'
+ 'src/index',
],
externals: [
'@nuxt/schema',
'nitropack',
'webpack',
'vite',
- 'h3'
+ 'h3',
],
- failOnWarn: false
+ failOnWarn: false,
})
diff --git a/packages/kit/package.json b/packages/kit/package.json
index 1c9f641547..310931589b 100644
--- a/packages/kit/package.json
+++ b/packages/kit/package.json
@@ -1,6 +1,6 @@
{
"name": "@nuxt/kit",
- "version": "3.10.3",
+ "version": "3.12.1",
"repository": {
"type": "git",
"url": "git+https://github.com/nuxt/nuxt.git",
@@ -27,22 +27,24 @@
},
"dependencies": {
"@nuxt/schema": "workspace:*",
- "c12": "^1.9.0",
+ "c12": "^1.11.1",
"consola": "^3.2.3",
"defu": "^6.1.4",
+ "destr": "^2.0.3",
"globby": "^14.0.1",
"hash-sum": "^2.0.0",
"ignore": "^5.3.1",
- "jiti": "^1.21.0",
- "knitwork": "^1.0.0",
- "mlly": "^1.6.1",
+ "jiti": "^1.21.6",
+ "klona": "^2.0.6",
+ "knitwork": "^1.1.0",
+ "mlly": "^1.7.1",
"pathe": "^1.1.2",
- "pkg-types": "^1.0.3",
+ "pkg-types": "^1.1.1",
"scule": "^1.3.0",
- "semver": "^7.6.0",
- "ufo": "^1.4.0",
+ "semver": "^7.6.2",
+ "ufo": "^1.5.3",
"unctx": "^2.3.1",
- "unimport": "^3.7.1",
+ "unimport": "^3.7.2",
"untyped": "^1.4.2"
},
"devDependencies": {
@@ -50,11 +52,11 @@
"@types/lodash-es": "4.17.12",
"@types/semver": "7.5.8",
"lodash-es": "4.17.21",
- "nitropack": "2.8.1",
+ "nitropack": "2.9.6",
"unbuild": "latest",
- "vite": "5.1.4",
- "vitest": "1.3.1",
- "webpack": "5.90.3"
+ "vite": "5.3.0",
+ "vitest": "1.6.0",
+ "webpack": "5.92.0"
},
"engines": {
"node": "^14.18.0 || >=16.10.0"
diff --git a/packages/kit/src/build.ts b/packages/kit/src/build.ts
index 92c066eb2d..0a186f63b7 100644
--- a/packages/kit/src/build.ts
+++ b/packages/kit/src/build.ts
@@ -42,7 +42,7 @@ export interface ExtendViteConfigOptions extends ExtendConfigOptions {}
*/
export function extendWebpackConfig (
fn: ((config: WebpackConfig) => void),
- options: ExtendWebpackConfigOptions = {}
+ options: ExtendWebpackConfigOptions = {},
) {
const nuxt = useNuxt()
@@ -74,7 +74,7 @@ export function extendWebpackConfig (
*/
export function extendViteConfig (
fn: ((config: ViteConfig) => void),
- options: ExtendViteConfigOptions = {}
+ options: ExtendViteConfigOptions = {},
) {
const nuxt = useNuxt()
diff --git a/packages/kit/src/compatibility.ts b/packages/kit/src/compatibility.ts
index d3d6e55875..b2720f05c9 100644
--- a/packages/kit/src/compatibility.ts
+++ b/packages/kit/src/compatibility.ts
@@ -1,9 +1,15 @@
import satisfies from 'semver/functions/satisfies.js' // npm/node-semver#381
+import { readPackageJSON } from 'pkg-types'
import type { Nuxt, NuxtCompatibility, NuxtCompatibilityIssues } from '@nuxt/schema'
import { useNuxt } from './context'
export function normalizeSemanticVersion (version: string) {
- return version.replace(/-[0-9]+\.[0-9a-f]+/, '') // Remove edge prefix
+ return version.replace(/-\d+\.[0-9a-f]+/, '') // Remove edge prefix
+}
+
+const builderMap = {
+ '@nuxt/vite-builder': 'vite',
+ '@nuxt/webpack-builder': 'webpack',
}
/**
@@ -18,7 +24,7 @@ export async function checkNuxtCompatibility (constraints: NuxtCompatibility, nu
if (!satisfies(normalizeSemanticVersion(nuxtVersion), constraints.nuxt, { includePrerelease: true })) {
issues.push({
name: 'nuxt',
- message: `Nuxt version \`${constraints.nuxt}\` is required but currently using \`${nuxtVersion}\``
+ message: `Nuxt version \`${constraints.nuxt}\` is required but currently using \`${nuxtVersion}\``,
})
}
}
@@ -30,16 +36,38 @@ export async function checkNuxtCompatibility (constraints: NuxtCompatibility, nu
if (bridgeRequirement === true && !hasBridge) {
issues.push({
name: 'bridge',
- message: 'Nuxt bridge is required'
+ message: 'Nuxt bridge is required',
})
} else if (bridgeRequirement === false && hasBridge) {
issues.push({
name: 'bridge',
- message: 'Nuxt bridge is not supported'
+ message: 'Nuxt bridge is not supported',
})
}
}
+ // Builder compatibility check
+ if (constraints.builder && typeof nuxt.options.builder === 'string') {
+ const currentBuilder = builderMap[nuxt.options.builder] || nuxt.options.builder
+ if (currentBuilder in constraints.builder) {
+ const constraint = constraints.builder[currentBuilder]!
+ if (constraint === false) {
+ issues.push({
+ name: 'builder',
+ message: `Not compatible with \`${nuxt.options.builder}\`.`,
+ })
+ } else {
+ const builderVersion = await readPackageJSON(nuxt.options.builder, { url: nuxt.options.modulesDir }).then(r => r.version).catch(() => undefined)
+ if (builderVersion && !satisfies(normalizeSemanticVersion(builderVersion), constraint, { includePrerelease: true })) {
+ issues.push({
+ name: 'builder',
+ message: `Not compatible with \`${builderVersion}\` of \`${currentBuilder}\`. This module requires \`${constraint}\`.`,
+ })
+ }
+ }
+ }
+ }
+
// Allow extending compatibility checks
await nuxt.callHook('kit:compatibility', constraints, issues)
diff --git a/packages/kit/src/components.ts b/packages/kit/src/components.ts
index 047da47f91..49bc6d91e2 100644
--- a/packages/kit/src/components.ts
+++ b/packages/kit/src/components.ts
@@ -48,7 +48,8 @@ export async function addComponent (opts: AddComponentOptions) {
mode: 'all',
shortPath: opts.filePath,
priority: 0,
- ...opts
+ meta: {},
+ ...opts,
}
nuxt.hook('components:extend', (components: Component[]) => {
diff --git a/packages/kit/src/ignore.test.ts b/packages/kit/src/ignore.test.ts
index a37b65c82c..adc100a594 100644
--- a/packages/kit/src/ignore.test.ts
+++ b/packages/kit/src/ignore.test.ts
@@ -1,11 +1,23 @@
-import { describe, expect, it } from 'vitest'
-import { resolveGroupSyntax } from './ignore.js'
+import { describe, expect, it, vi } from 'vitest'
+import type { Nuxt, NuxtOptions } from '@nuxt/schema'
+import { isIgnored, resolveGroupSyntax, resolveIgnorePatterns } from './ignore.js'
+import * as context from './context.js'
+
+describe('isIgnored', () => {
+ it('should populate _ignore', () => {
+ const mockNuxt = { options: { ignore: ['my-dir'] } as NuxtOptions } as Nuxt
+ vi.spyOn(context, 'tryUseNuxt').mockReturnValue(mockNuxt)
+
+ expect(isIgnored('my-dir/my-file.ts')).toBe(true)
+ expect(resolveIgnorePatterns()?.includes('my-dir')).toBe(true)
+ })
+})
describe('resolveGroupSyntax', () => {
it('should resolve single group syntax', () => {
expect(resolveGroupSyntax('**/*.{spec}.{js,ts}')).toStrictEqual([
'**/*.spec.js',
- '**/*.spec.ts'
+ '**/*.spec.ts',
])
})
@@ -14,13 +26,13 @@ describe('resolveGroupSyntax', () => {
'**/*.spec.js',
'**/*.spec.ts',
'**/*.test.js',
- '**/*.test.ts'
+ '**/*.test.ts',
])
})
it('should do nothing with normal globs', () => {
expect(resolveGroupSyntax('**/*.spec.js')).toStrictEqual([
- '**/*.spec.js'
+ '**/*.spec.js',
])
})
})
diff --git a/packages/kit/src/ignore.ts b/packages/kit/src/ignore.ts
index bc93e8cd7a..9dcdc32cf2 100644
--- a/packages/kit/src/ignore.ts
+++ b/packages/kit/src/ignore.ts
@@ -28,6 +28,8 @@ export function isIgnored (pathname: string): boolean {
return !!(relativePath && nuxt._ignore.ignores(relativePath))
}
+const NEGATION_RE = /^(!?)(.*)$/
+
export function resolveIgnorePatterns (relativePath?: string): string[] {
const nuxt = tryUseNuxt()
@@ -36,22 +38,26 @@ export function resolveIgnorePatterns (relativePath?: string): string[] {
return []
}
- if (!nuxt._ignorePatterns) {
- nuxt._ignorePatterns = nuxt.options.ignore.flatMap(s => resolveGroupSyntax(s))
+ const ignorePatterns = nuxt.options.ignore.flatMap(s => resolveGroupSyntax(s))
- const nuxtignoreFile = join(nuxt.options.rootDir, '.nuxtignore')
- if (existsSync(nuxtignoreFile)) {
- const contents = readFileSync(nuxtignoreFile, 'utf-8')
- nuxt._ignorePatterns.push(...contents.trim().split(/\r?\n/))
- }
+ const nuxtignoreFile = join(nuxt.options.rootDir, '.nuxtignore')
+ if (existsSync(nuxtignoreFile)) {
+ const contents = readFileSync(nuxtignoreFile, 'utf-8')
+ ignorePatterns.push(...contents.trim().split(/\r?\n/))
}
if (relativePath) {
// Map ignore patterns based on if they start with * or !*
- return nuxt._ignorePatterns.map(p => p[0] === '*' || (p[0] === '!' && p[1] === '*') ? p : relative(relativePath, resolve(nuxt.options.rootDir, p)))
+ return ignorePatterns.map((p) => {
+ const [_, negation = '', pattern] = p.match(NEGATION_RE) || []
+ if (pattern[0] === '*') {
+ return p
+ }
+ return negation + relative(relativePath, resolve(nuxt.options.rootDir, pattern || p))
+ })
}
- return nuxt._ignorePatterns
+ return ignorePatterns
}
/**
diff --git a/packages/kit/src/index.ts b/packages/kit/src/index.ts
index da2fe614ad..405de8606a 100644
--- a/packages/kit/src/index.ts
+++ b/packages/kit/src/index.ts
@@ -10,6 +10,7 @@ export * from './loader/nuxt'
// Utils
export * from './imports'
+export { updateRuntimeConfig, useRuntimeConfig } from './runtime-config'
export * from './build'
export * from './compatibility'
export * from './components'
@@ -20,7 +21,7 @@ export * from './pages'
export * from './plugin'
export * from './resolve'
export * from './nitro'
-export * from './template'
+export { addTemplate, addTypeTemplate, normalizeTemplate, updateTemplates, writeTypes } from './template'
export * from './logger'
// Internal Utils
@@ -30,7 +31,7 @@ export {
requireModule,
importModule,
tryImportModule,
- tryRequireModule
+ tryRequireModule,
} from './internal/cjs'
export type { ResolveModuleOptions, RequireModuleOptions } from './internal/cjs'
export { tryResolveModule } from './internal/esm'
diff --git a/packages/kit/src/internal/cjs.ts b/packages/kit/src/internal/cjs.ts
index 0b9b2d1d2b..7e30acfec7 100644
--- a/packages/kit/src/internal/cjs.ts
+++ b/packages/kit/src/internal/cjs.ts
@@ -66,14 +66,14 @@ export function getModulePaths (paths?: string[] | string) {
global.__NUXT_PREPATHS__,
paths || [],
process.cwd(),
- global.__NUXT_PATHS__
+ global.__NUXT_PATHS__,
).filter(Boolean) as string[]
}
/** @deprecated Do not use CJS utils */
export function resolveModule (id: string, opts: ResolveModuleOptions = {}) {
return normalize(_require.resolve(id, {
- paths: getModulePaths(opts.paths)
+ paths: getModulePaths(opts.paths),
}))
}
diff --git a/packages/kit/src/internal/template.ts b/packages/kit/src/internal/template.ts
index 389e457d1c..5b40a2a214 100644
--- a/packages/kit/src/internal/template.ts
+++ b/packages/kit/src/internal/template.ts
@@ -9,7 +9,7 @@ import { toArray } from '../utils'
/** @deprecated */
// TODO: Remove support for compiling ejs templates in v4
-export async function compileTemplate (template: NuxtTemplate, ctx: any) {
+export async function compileTemplate (template: NuxtTemplate, ctx: any) {
const data = { ...ctx, options: template.options }
if (template.src) {
try {
@@ -27,7 +27,7 @@ export async function compileTemplate (template: NuxtTemplate, ctx: any) {
}
/** @deprecated */
-const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"{(.+)}"(?=,?$)/gm, r => JSON.parse(r).replace(/^{(.*)}$/, '$1'))
+const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"\{(.+)\}"(?=,?$)/gm, r => JSON.parse(r).replace(/^\{(.*)\}$/, '$1'))
/** @deprecated */
const importSources = (sources: string | string[], { lazy = false } = {}) => {
diff --git a/packages/kit/src/layout.ts b/packages/kit/src/layout.ts
index 91e50310c4..bf86c443c9 100644
--- a/packages/kit/src/layout.ts
+++ b/packages/kit/src/layout.ts
@@ -16,7 +16,7 @@ export function addLayout (this: any, template: NuxtTemplate | string, name?: st
const layout = (nuxt.options as any).layouts[layoutName]
if (layout) {
return logger.warn(
- `Not overriding \`${layoutName}\` (provided by \`${layout}\`) with \`${src || filename}\`.`
+ `Not overriding \`${layoutName}\` (provided by \`${layout}\`) with \`${src || filename}\`.`,
)
}
(nuxt.options as any).layouts[layoutName] = `./${filename}`
@@ -31,12 +31,12 @@ export function addLayout (this: any, template: NuxtTemplate | string, name?: st
if (layoutName in app.layouts) {
const relativePath = relative(nuxt.options.srcDir, app.layouts[layoutName].file)
return logger.warn(
- `Not overriding \`${layoutName}\` (provided by \`~/${relativePath}\`) with \`${src || filename}\`.`
+ `Not overriding \`${layoutName}\` (provided by \`~/${relativePath}\`) with \`${src || filename}\`.`,
)
}
app.layouts[layoutName] = {
file: join('#build', filename),
- name: layoutName
+ name: layoutName,
}
})
}
diff --git a/packages/kit/src/loader/config.ts b/packages/kit/src/loader/config.ts
index a4bce4f0c4..b2c4d1b883 100644
--- a/packages/kit/src/loader/config.ts
+++ b/packages/kit/src/loader/config.ts
@@ -1,23 +1,36 @@
-import { resolve } from 'pathe'
import type { JSValue } from 'untyped'
import { applyDefaults } from 'untyped'
-import type { LoadConfigOptions } from 'c12'
+import type { ConfigLayer, ConfigLayerMeta, LoadConfigOptions } from 'c12'
import { loadConfig } from 'c12'
import type { NuxtConfig, NuxtOptions } from '@nuxt/schema'
import { NuxtConfigSchema } from '@nuxt/schema'
+import { globby } from 'globby'
+import defu from 'defu'
-export interface LoadNuxtConfigOptions extends LoadConfigOptions {}
+export interface LoadNuxtConfigOptions extends Omit, 'overrides'> {
+ overrides?: Exclude['overrides'], Promise | Function>
+}
+
+const layerSchemaKeys = ['future', 'srcDir', 'rootDir', 'dir']
+const layerSchema = Object.fromEntries(Object.entries(NuxtConfigSchema).filter(([key]) => layerSchemaKeys.includes(key)))
export async function loadNuxtConfig (opts: LoadNuxtConfigOptions): Promise {
+ // Automatically detect and import layers from `~~/layers/` directory
+ opts.overrides = defu(opts.overrides, {
+ _extends: await globby('layers/*', {
+ onlyDirectories: true,
+ cwd: opts.cwd || process.cwd(),
+ }),
+ });
(globalThis as any).defineNuxtConfig = (c: any) => c
const result = await loadConfig({
name: 'nuxt',
configFile: 'nuxt.config',
rcFile: '.nuxtrc',
- extend: { extendKey: ['theme', 'extends'] },
+ extend: { extendKey: ['theme', 'extends', '_extends'] },
dotenv: true,
globalRc: true,
- ...opts
+ ...opts,
})
delete (globalThis as any).defineNuxtConfig
const { configFile, layers = [], cwd } = result
@@ -28,15 +41,25 @@ export async function loadNuxtConfig (opts: LoadNuxtConfigOptions): Promise[] = []
+ const processedLayers = new Set()
for (const layer of layers) {
+ // Resolve `rootDir` & `srcDir` of layers
layer.config = layer.config || {}
- layer.config.rootDir = layer.config.rootDir ?? layer.cwd
- layer.config.srcDir = resolve(layer.config.rootDir!, layer.config.srcDir!)
+ layer.config.rootDir = layer.config.rootDir ?? layer.cwd!
+
+ // Only process/resolve layers once
+ if (processedLayers.has(layer.config.rootDir)) { continue }
+ processedLayers.add(layer.config.rootDir)
+
+ // Normalise layer directories
+ layer.config = await applyDefaults(layerSchema, layer.config as NuxtConfig & Record) as unknown as NuxtConfig
+
+ // Filter layers
+ if (!layer.configFile || layer.configFile.endsWith('.nuxtrc')) { continue }
+ _layers.push(layer)
}
- // Filter layers
- const _layers = layers.filter(layer => layer.configFile && !layer.configFile.endsWith('.nuxtrc'))
;(nuxtConfig as any)._layers = _layers
// Ensure at least one layer remains (without nuxt.config)
@@ -45,8 +68,8 @@ export async function loadNuxtConfig (opts: LoadNuxtConfigOptions): Promise {
throw new Error(`Cannot find any nuxt version from ${opts.cwd}`)
}
const pkg = await readPackageJSON(nearestNuxtPkg)
- const majorVersion = pkg.version ? parseInt(pkg.version.split('.')[0]) : ''
+ const majorVersion = pkg.version ? Number.parseInt(pkg.version.split('.')[0]) : ''
const rootDir = pathToFileURL(opts.cwd || process.cwd()).href
@@ -51,7 +51,7 @@ export async function loadNuxt (opts: LoadNuxtOptions): Promise {
for: opts.dev ? 'dev' : 'build',
configOverrides: opts.overrides,
ready: opts.ready,
- envConfig: opts.dotenv // TODO: Backward format conversion
+ envConfig: opts.dotenv, // TODO: Backward format conversion
})
// Mock new hookable methods
diff --git a/packages/kit/src/logger.test.ts b/packages/kit/src/logger.test.ts
index a3cc49541d..44aa6ed3cd 100644
--- a/packages/kit/src/logger.test.ts
+++ b/packages/kit/src/logger.test.ts
@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from 'vitest'
import { consola } from 'consola'
import { logger, useLogger } from './logger'
-vi.mock("consola", () => {
- const logger = {} as any;
+vi.mock('consola', () => {
+ const logger = {} as any
- logger.create = vi.fn(() => ({...logger}));
- logger.withTag = vi.fn(() => ({...logger}));
-
- return { consola: logger };
+ logger.create = vi.fn(() => ({ ...logger }))
+ logger.withTag = vi.fn(() => ({ ...logger }))
+
+ return { consola: logger }
})
describe('logger', () => {
@@ -20,29 +20,28 @@ describe('logger', () => {
describe('useLogger', () => {
it('should expose consola when not passing a tag', () => {
- expect(useLogger()).toBe(consola);
- });
+ expect(useLogger()).toBe(consola)
+ })
it('should create a new instance when passing a tag', () => {
- const logger = vi.mocked(consola);
-
- const instance = useLogger("tag");
+ const logger = vi.mocked(consola)
- expect(instance).toEqual(logger);
- expect(instance).not.toBe(logger);
- expect(logger.create).toBeCalledWith({});
- expect(logger.withTag).toBeCalledWith("tag");
- });
+ const instance = useLogger('tag')
+
+ expect(instance).toEqual(logger)
+ expect(instance).not.toBe(logger)
+ expect(logger.create).toBeCalledWith({})
+ expect(logger.withTag).toBeCalledWith('tag')
+ })
it('should create a new instance when passing a tag and options', () => {
- const logger = vi.mocked(consola);
-
- const instance = useLogger("tag", { level: 0 });
+ const logger = vi.mocked(consola)
- expect(instance).toEqual(logger);
- expect(instance).not.toBe(logger);
- expect(logger.create).toBeCalledWith({ level: 0 });
- expect(logger.withTag).toBeCalledWith("tag");
- });
+ const instance = useLogger('tag', { level: 0 })
+ expect(instance).toEqual(logger)
+ expect(instance).not.toBe(logger)
+ expect(logger.create).toBeCalledWith({ level: 0 })
+ expect(logger.withTag).toBeCalledWith('tag')
+ })
})
diff --git a/packages/kit/src/logger.ts b/packages/kit/src/logger.ts
index be95003480..8572b11555 100644
--- a/packages/kit/src/logger.ts
+++ b/packages/kit/src/logger.ts
@@ -1,5 +1,5 @@
import { consola } from 'consola'
-import type { ConsolaOptions } from 'consola';
+import type { ConsolaOptions } from 'consola'
export const logger = consola
diff --git a/packages/kit/src/module/compatibility.test.ts b/packages/kit/src/module/compatibility.test.ts
index ce20f54f02..d298f800b9 100644
--- a/packages/kit/src/module/compatibility.test.ts
+++ b/packages/kit/src/module/compatibility.test.ts
@@ -10,21 +10,21 @@ describe('nuxt module compatibility', () => {
modules: [
defineNuxtModule({
meta: {
- name: 'nuxt-module-foo'
- }
+ name: 'nuxt-module-foo',
+ },
}),
[
defineNuxtModule({
meta: {
- name: 'module-instance-with-options'
- }
+ name: 'module-instance-with-options',
+ },
}),
{
- foo: 'bar'
- }
- ]
- ]
- }
+ foo: 'bar',
+ },
+ ],
+ ],
+ },
})
expect(hasNuxtModule('nuxt-module-foo', nuxt)).toStrictEqual(true)
expect(hasNuxtModule('module-instance-with-options', nuxt)).toStrictEqual(true)
@@ -35,8 +35,8 @@ describe('nuxt module compatibility', () => {
const module = defineNuxtModule({
meta: {
name: 'nuxt-module-foo',
- version: '1.0.0'
- }
+ version: '1.0.0',
+ },
})
expect(await getNuxtModuleVersion(module, nuxt)).toEqual('1.0.0')
await nuxt.close()
@@ -46,8 +46,8 @@ describe('nuxt module compatibility', () => {
const module = defineNuxtModule({
meta: {
name: 'nuxt-module-foo',
- version: '1.0.0'
- }
+ version: '1.0.0',
+ },
})
expect(await hasNuxtModuleCompatibility(module, '^1.0.0', nuxt)).toStrictEqual(true)
expect(await hasNuxtModuleCompatibility(module, '^2.0.0', nuxt)).toStrictEqual(false)
diff --git a/packages/kit/src/module/compatibility.ts b/packages/kit/src/module/compatibility.ts
index 666f4b4085..446e7e3fce 100644
--- a/packages/kit/src/module/compatibility.ts
+++ b/packages/kit/src/module/compatibility.ts
@@ -20,7 +20,7 @@ function resolveNuxtModuleEntryName (m: NuxtOptions['modules'][number]): string
* This will check both the installed modules and the modules to be installed. Note
* that it cannot detect if a module is _going to be_ installed programmatically by another module.
*/
-export function hasNuxtModule (moduleName: string, nuxt: Nuxt = useNuxt()) : boolean {
+export function hasNuxtModule (moduleName: string, nuxt: Nuxt = useNuxt()): boolean {
// check installed modules
return nuxt.options._installedModules.some(({ meta }) => meta.name === moduleName) ||
// check modules to be installed
@@ -36,7 +36,7 @@ export async function hasNuxtModuleCompatibility (module: string | NuxtModule, s
return false
}
return satisfies(normalizeSemanticVersion(version), semverVersion, {
- includePrerelease: true
+ includePrerelease: true,
})
}
diff --git a/packages/kit/src/module/define.ts b/packages/kit/src/module/define.ts
index 360d1a14db..ff2a56d2d4 100644
--- a/packages/kit/src/module/define.ts
+++ b/packages/kit/src/module/define.ts
@@ -73,8 +73,8 @@ export function defineNuxtModule (definition: Mo
const key = `nuxt:module:${uniqueKey || (Math.round(Math.random() * 10000))}`
const mark = performance.mark(key)
const res = await module.setup?.call(null as any, _options, nuxt) ?? {}
- const perf = performance.measure(key, mark?.name) // TODO: remove when Node 14 reaches EOL
- const setupTime = perf ? Math.round((perf.duration * 100)) / 100 : 0 // TODO: remove when Node 14 reaches EOL
+ const perf = performance.measure(key, mark.name)
+ const setupTime = Math.round((perf.duration * 100)) / 100
// Measure setup time
if (setupTime > 5000 && uniqueKey !== '@nuxt/telemetry') {
@@ -89,8 +89,8 @@ export function defineNuxtModule (definition: Mo
// Return module install result
return defu(res, {
timings: {
- setup: setupTime
- }
+ setup: setupTime,
+ },
})
}
@@ -138,10 +138,10 @@ function nuxt2Shims (nuxt: Nuxt) {
plugins: nuxt.options.plugins,
templates: [
...templates.templatesFiles,
- ...virtualTemplates
+ ...virtualTemplates,
],
- templateVars: templates.templateVars
- }
+ templateVars: templates.templateVars,
+ },
}
for await (const template of virtualTemplates) {
const contents = await compileTemplate({ ...template, src: '' }, context)
diff --git a/packages/kit/src/module/install.ts b/packages/kit/src/module/install.ts
index c1c0f8be29..beecd62aef 100644
--- a/packages/kit/src/module/install.ts
+++ b/packages/kit/src/module/install.ts
@@ -1,5 +1,5 @@
import { existsSync, promises as fsp, lstatSync } from 'node:fs'
-import type { ModuleMeta, Nuxt, NuxtModule } from '@nuxt/schema'
+import type { ModuleMeta, Nuxt, NuxtConfig, NuxtModule } from '@nuxt/schema'
import { dirname, isAbsolute, join, resolve } from 'pathe'
import { defu } from 'defu'
import { isNuxt2 } from '../compatibility'
@@ -12,7 +12,10 @@ import { logger } from '../logger'
const NODE_MODULES_RE = /[/\\]node_modules[/\\]/
/** Installs a module on a Nuxt instance. */
-export async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt: Nuxt = useNuxt()) {
+export async function installModule<
+ T extends string | NuxtModule,
+ Config extends Extract[number], [T, any]>,
+> (moduleToInstall: T, inlineOptions?: [Config] extends [never] ? any : Config[1], nuxt: Nuxt = useNuxt()) {
const { nuxtModule, buildTimeModuleMeta } = await loadNuxtModuleInstance(moduleToInstall, nuxt)
const localLayerModuleDirs = new Set()
@@ -38,15 +41,21 @@ export async function installModule (moduleToInstall: string | NuxtModule, inlin
nuxt.options.build.transpile.push(normalizeModuleTranspilePath(moduleToInstall))
const directory = getDirectory(moduleToInstall)
if (directory !== moduleToInstall && !localLayerModuleDirs.has(directory)) {
- nuxt.options.modulesDir.push(directory)
+ nuxt.options.modulesDir.push(resolve(directory, 'node_modules'))
}
}
nuxt.options._installedModules = nuxt.options._installedModules || []
+ const entryPath = typeof moduleToInstall === 'string' ? resolveAlias(moduleToInstall) : undefined
+
+ if (typeof moduleToInstall === 'string' && entryPath !== moduleToInstall) {
+ buildTimeModuleMeta.rawPath = moduleToInstall
+ }
+
nuxt.options._installedModules.push({
meta: defu(await nuxtModule.getMeta?.(), buildTimeModuleMeta),
timings: res.timings,
- entryPath: typeof moduleToInstall === 'string' ? resolveAlias(moduleToInstall) : undefined
+ entryPath,
})
}
@@ -74,9 +83,9 @@ export async function loadNuxtModuleInstance (nuxtModule: string | NuxtModule, n
const paths = [join(nuxtModule, 'nuxt'), join(nuxtModule, 'module'), nuxtModule]
let error: unknown
for (const path of paths) {
- const src = await resolvePath(path)
- // Prefer ESM resolution if possible
try {
+ const src = await resolvePath(path, { fallbackToOriginal: true })
+ // Prefer ESM resolution if possible
nuxtModule = await importModule(src, nuxt.options.modulesDir).catch(() => null) ?? requireModule(src, { paths: nuxt.options.modulesDir })
// nuxt-module-builder generates a module.json with metadata including the version
diff --git a/packages/kit/src/nitro.ts b/packages/kit/src/nitro.ts
index eddcb91f14..72b3ca93f3 100644
--- a/packages/kit/src/nitro.ts
+++ b/packages/kit/src/nitro.ts
@@ -14,7 +14,7 @@ function normalizeHandlerMethod (handler: NitroEventHandler) {
return {
method,
...handler,
- handler: normalize(handler.handler)
+ handler: normalize(handler.handler),
}
}
diff --git a/packages/kit/src/pages.ts b/packages/kit/src/pages.ts
index 3e36eb2c03..a5f7fc1d3e 100644
--- a/packages/kit/src/pages.ts
+++ b/packages/kit/src/pages.ts
@@ -53,12 +53,12 @@ export function addRouteMiddleware (input: NuxtMiddleware | NuxtMiddleware[], op
if (find >= 0) {
if (app.middleware[find].path === middleware.path) { continue }
if (options.override === true) {
- app.middleware[find] = middleware
+ app.middleware[find] = { ...middleware }
} else {
logger.warn(`'${middleware.name}' middleware already exists at '${app.middleware[find].path}'. You can set \`override: true\` to replace it.`)
}
} else {
- app.middleware.push(middleware)
+ app.middleware.push({ ...middleware })
}
}
})
diff --git a/packages/kit/src/plugin.ts b/packages/kit/src/plugin.ts
index 5421c3027f..8905c11274 100644
--- a/packages/kit/src/plugin.ts
+++ b/packages/kit/src/plugin.ts
@@ -3,7 +3,6 @@ import type { NuxtPlugin, NuxtPluginTemplate } from '@nuxt/schema'
import { useNuxt } from './context'
import { addTemplate } from './template'
import { resolveAlias } from './resolve'
-import { logger } from './logger'
/**
* Normalize a nuxt plugin object
@@ -20,12 +19,6 @@ export function normalizePlugin (plugin: NuxtPlugin | string): NuxtPlugin {
throw new Error('Invalid plugin. src option is required: ' + JSON.stringify(plugin))
}
- // TODO: only scan top-level files #18418
- const nonTopLevelPlugin = plugin.src.match(/\/plugins\/[^/]+\/index\.[^/]+$/i)
- if (nonTopLevelPlugin && nonTopLevelPlugin.length > 0 && !useNuxt().options.plugins.find(i => (typeof i === 'string' ? i : i.src).endsWith(nonTopLevelPlugin[0]))) {
- logger.warn(`[deprecation] You are using a plugin that is within a subfolder of your plugins directory without adding it to your config explicitly. You can move it to the top-level plugins directory, or include the file '~${nonTopLevelPlugin[0]}' in your plugins config (https://nuxt.com/docs/api/nuxt-config#plugins-1) to remove this warning.`)
- }
-
// Normalize full path to plugin
plugin.src = normalize(resolveAlias(plugin.src))
diff --git a/packages/kit/src/resolve.test.ts b/packages/kit/src/resolve.test.ts
new file mode 100644
index 0000000000..bcdb95486e
--- /dev/null
+++ b/packages/kit/src/resolve.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { resolve } from 'pathe'
+import { loadNuxt } from './loader/nuxt'
+import { findPath, resolvePath } from './resolve'
+import { defineNuxtModule } from './module/define'
+import { addTemplate } from './template'
+
+const nuxt = await loadNuxt({
+ overrides: {
+ modules: [
+ defineNuxtModule(() => {
+ addTemplate({
+ filename: 'my-template.mjs',
+ getContents: () => 'export const myUtil = () => \'hello\'',
+ })
+ }),
+ ],
+ },
+})
+
+describe('resolvePath', () => {
+ it('should resolve paths correctly', async () => {
+ expect(await resolvePath('.nuxt/app.config')).toBe(resolve(nuxt.options.buildDir, 'app.config'))
+ })
+})
+
+describe('findPath', () => {
+ it('should find paths correctly', async () => {
+ expect(await findPath(resolve(nuxt.options.buildDir, 'my-template'), { virtual: true })).toBe(resolve(nuxt.options.buildDir, 'my-template.mjs'))
+ })
+})
diff --git a/packages/kit/src/resolve.ts b/packages/kit/src/resolve.ts
index a768ba6509..392dec86d8 100644
--- a/packages/kit/src/resolve.ts
+++ b/packages/kit/src/resolve.ts
@@ -17,6 +17,19 @@ export interface ResolvePathOptions {
/** The file extensions to try. Default is Nuxt configured extensions. */
extensions?: string[]
+
+ /**
+ * Whether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).
+ * @default false
+ */
+ virtual?: boolean
+
+ /**
+ * Whether to fallback to the original path if the resolved path does not exist instead of returning the normalized input path.
+ *
+ * @default false
+ */
+ fallbackToOriginal?: boolean
}
/**
@@ -30,8 +43,13 @@ export async function resolvePath (path: string, opts: ResolvePathOptions = {}):
path = normalize(path)
// Fast return if the path exists
- if (isAbsolute(path) && existsSync(path) && !(await isDirectory(path))) {
- return path
+ if (isAbsolute(path)) {
+ if (opts?.virtual && existsInVFS(path)) {
+ return path
+ }
+ if (existsSync(path) && !(await isDirectory(path))) {
+ return path
+ }
}
// Use current nuxt options
@@ -49,6 +67,10 @@ export async function resolvePath (path: string, opts: ResolvePathOptions = {}):
}
// Check if resolvedPath is a file
+ if (opts?.virtual && existsInVFS(path, nuxt)) {
+ return path
+ }
+
let _isDir = false
if (existsSync(path)) {
_isDir = await isDirectory(path)
@@ -61,11 +83,17 @@ export async function resolvePath (path: string, opts: ResolvePathOptions = {}):
for (const ext of extensions) {
// path.[ext]
const pathWithExt = path + ext
+ if (opts?.virtual && existsInVFS(pathWithExt, nuxt)) {
+ return pathWithExt
+ }
if (existsSync(pathWithExt)) {
return pathWithExt
}
// path/index.[ext]
const pathWithIndex = join(path, 'index' + ext)
+ if (opts?.virtual && existsInVFS(pathWithIndex, nuxt)) {
+ return pathWithIndex
+ }
if (_isDir && existsSync(pathWithIndex)) {
return pathWithIndex
}
@@ -78,15 +106,24 @@ export async function resolvePath (path: string, opts: ResolvePathOptions = {}):
}
// Return normalized input
- return path
+ return opts.fallbackToOriginal ? _path : path
}
/**
* Try to resolve first existing file in paths
*/
export async function findPath (paths: string | string[], opts?: ResolvePathOptions, pathType: 'file' | 'dir' = 'file'): Promise {
+ const nuxt = opts?.virtual ? tryUseNuxt() : undefined
+
for (const path of toArray(paths)) {
const rPath = await resolvePath(path, opts)
+
+ // Check VFS
+ if (opts?.virtual && existsInVFS(rPath, nuxt)) {
+ return rPath
+ }
+
+ // Check file system
if (await existsSensitive(rPath)) {
const _isDir = await isDirectory(rPath)
if (!pathType || (pathType === 'file' && !_isDir) || (pathType === 'dir' && _isDir)) {
@@ -127,7 +164,7 @@ export function createResolver (base: string | URL): Resolver {
return {
resolve: (...path) => resolve(base as string, ...path),
- resolvePath: (path, opts) => resolvePath(path, { cwd: base as string, ...opts })
+ resolvePath: (path, opts) => resolvePath(path, { cwd: base as string, ...opts }),
}
}
@@ -160,6 +197,17 @@ async function isDirectory (path: string) {
return (await fsp.lstat(path)).isDirectory()
}
+function existsInVFS (path: string, nuxt = tryUseNuxt()) {
+ if (!nuxt) { return false }
+
+ if (path in nuxt.vfs) {
+ return true
+ }
+
+ const templates = nuxt.apps.default?.templates ?? nuxt.options.build.templates
+ return templates.some(template => template.dst === path)
+}
+
export async function resolveFiles (path: string, pattern: string | string[], opts: { followSymbolicLinks?: boolean } = {}) {
const files = await globby(pattern, { cwd: path, followSymbolicLinks: opts.followSymbolicLinks ?? true })
return files.map(p => resolve(path, p)).filter(p => !isIgnored(p)).sort()
diff --git a/packages/kit/src/runtime-config.ts b/packages/kit/src/runtime-config.ts
new file mode 100644
index 0000000000..034c59fa14
--- /dev/null
+++ b/packages/kit/src/runtime-config.ts
@@ -0,0 +1,103 @@
+import process from 'node:process'
+import destr from 'destr'
+import { snakeCase } from 'scule'
+import { klona } from 'klona'
+
+import defu from 'defu'
+import { useNuxt } from './context'
+import { useNitro } from './nitro'
+
+/**
+ * Access 'resolved' Nuxt runtime configuration, with values updated from environment.
+ *
+ * This mirrors the runtime behavior of Nitro.
+ */
+export function useRuntimeConfig () {
+ const nuxt = useNuxt()
+ return applyEnv(klona(nuxt.options.nitro.runtimeConfig!), {
+ prefix: 'NITRO_',
+ altPrefix: 'NUXT_',
+ envExpansion: nuxt.options.nitro.experimental?.envExpansion ?? !!process.env.NITRO_ENV_EXPANSION,
+ })
+}
+
+/**
+ * Update Nuxt runtime configuration.
+ */
+export function updateRuntimeConfig (runtimeConfig: Record) {
+ const nuxt = useNuxt()
+ Object.assign(nuxt.options.nitro.runtimeConfig as Record, defu(runtimeConfig, nuxt.options.nitro.runtimeConfig))
+
+ try {
+ return useNitro().updateConfig({ runtimeConfig })
+ } catch {
+ // Nitro is not yet initialised - we can safely ignore this error
+ }
+}
+
+/**
+ * https://github.com/unjs/nitro/blob/main/src/runtime/utils.env.ts.
+*
+ * These utils will be replaced by util exposed from nitropack. See https://github.com/unjs/nitro/pull/2404
+ * for more context and future plans.)
+ *
+ * @internal
+ */
+
+type EnvOptions = {
+ prefix?: string
+ altPrefix?: string
+ envExpansion?: boolean
+}
+
+function getEnv (key: string, opts: EnvOptions, env = process.env) {
+ const envKey = snakeCase(key).toUpperCase()
+ return destr(
+ env[opts.prefix + envKey] ?? env[opts.altPrefix + envKey],
+ )
+}
+
+function _isObject (input: unknown) {
+ return typeof input === 'object' && !Array.isArray(input)
+}
+
+function applyEnv (
+ obj: Record,
+ opts: EnvOptions,
+ parentKey = '',
+) {
+ for (const key in obj) {
+ const subKey = parentKey ? `${parentKey}_${key}` : key
+ const envValue = getEnv(subKey, opts)
+ if (_isObject(obj[key])) {
+ // Same as before
+ if (_isObject(envValue)) {
+ obj[key] = { ...(obj[key] as any), ...(envValue as any) }
+ applyEnv(obj[key], opts, subKey)
+ } else if (envValue === undefined) {
+ // If envValue is undefined
+ // Then proceed to nested properties
+ applyEnv(obj[key], opts, subKey)
+ } else {
+ // If envValue is a primitive other than undefined
+ // Then set objValue and ignore the nested properties
+ obj[key] = envValue ?? obj[key]
+ }
+ } else {
+ obj[key] = envValue ?? obj[key]
+ }
+ // Experimental env expansion
+ if (opts.envExpansion && typeof obj[key] === 'string') {
+ obj[key] = _expandFromEnv(obj[key])
+ }
+ }
+ return obj
+}
+
+const envExpandRx = /\{\{(.*?)\}\}/g
+
+function _expandFromEnv (value: string, env: Record = process.env) {
+ return value.replace(envExpandRx, (match, key) => {
+ return env[key] || match
+ })
+}
diff --git a/packages/kit/src/template.ts b/packages/kit/src/template.ts
index 3d3888fb71..1816ccf536 100644
--- a/packages/kit/src/template.ts
+++ b/packages/kit/src/template.ts
@@ -5,6 +5,7 @@ import type { Nuxt, NuxtTemplate, NuxtTypeTemplate, ResolvedNuxtTemplate, TSRefe
import { withTrailingSlash } from 'ufo'
import { defu } from 'defu'
import type { TSConfig } from 'pkg-types'
+import { gte } from 'semver'
import { readPackageJSON } from 'pkg-types'
import { tryResolveModule } from './internal/esm'
@@ -16,7 +17,7 @@ import { resolveNuxtModule } from './resolve'
/**
* Renders given template using lodash template during build into the project buildDir
*/
-export function addTemplate (_template: NuxtTemplate | string) {
+export function addTemplate (_template: NuxtTemplate | string) {
const nuxt = useNuxt()
// Normalize template
@@ -36,7 +37,7 @@ export function addTemplate (_template: NuxtTemplate | string) {
* Renders given types using lodash template during build into the project buildDir
* and register them as types.
*/
-export function addTypeTemplate (_template: NuxtTypeTemplate) {
+export function addTypeTemplate (_template: NuxtTypeTemplate) {
const nuxt = useNuxt()
const template = addTemplate(_template)
@@ -56,7 +57,7 @@ export function addTypeTemplate (_template: NuxtTypeTemplate) {
/**
* Normalize a nuxt template object
*/
-export function normalizeTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate {
+export function normalizeTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate {
if (!template) {
throw new Error('Invalid template: ' + JSON.stringify(template))
}
@@ -110,7 +111,8 @@ export function normalizeTemplate (template: NuxtTemplate | string): Resol
export async function updateTemplates (options?: { filter?: (template: ResolvedNuxtTemplate) => boolean }) {
return await tryUseNuxt()?.hooks.callHook('builder:generateApp', options)
}
-export async function writeTypes (nuxt: Nuxt) {
+
+export async function _generateTypes (nuxt: Nuxt) {
const nodeModulePaths = getModulePaths(nuxt.options.modulesDir)
const rootDirWithSlash = withTrailingSlash(nuxt.options.rootDir)
@@ -118,30 +120,53 @@ export async function writeTypes (nuxt: Nuxt) {
const modulePaths = await resolveNuxtModule(rootDirWithSlash,
nuxt.options._installedModules
.filter(m => m.entryPath)
- .map(m => getDirectory(m.entryPath))
+ .map(m => getDirectory(m.entryPath!)),
)
+ const isV4 = nuxt.options.future?.compatibilityVersion === 4
+
+ const hasTypescriptVersionWithModulePreserve = await readPackageJSON('typescript', { url: nuxt.options.modulesDir })
+ .then(r => r?.version && gte(r.version, '5.4.0'))
+ .catch(() => isV4)
+
+ // https://www.totaltypescript.com/tsconfig-cheat-sheet
const tsConfig: TSConfig = defu(nuxt.options.typescript?.tsConfig, {
compilerOptions: {
+ /* Base options: */
+ esModuleInterop: true,
+ skipLibCheck: true,
+ target: 'ESNext',
+ allowJs: true,
+ resolveJsonModule: true,
+ moduleDetection: 'force',
+ isolatedModules: true,
+ verbatimModuleSyntax: true,
+ /* Strictness */
+ strict: nuxt.options.typescript?.strict ?? true,
+ noUncheckedIndexedAccess: isV4,
forceConsistentCasingInFileNames: true,
+ noImplicitOverride: true,
+ /* If NOT transpiling with TypeScript: */
+ module: hasTypescriptVersionWithModulePreserve ? 'preserve' : 'ESNext',
+ noEmit: true,
+ /* If your code runs in the DOM: */
+ lib: [
+ 'ESNext',
+ 'dom',
+ 'dom.iterable',
+ ],
+ /* JSX support for Vue */
jsx: 'preserve',
jsxImportSource: 'vue',
- target: 'ESNext',
- module: 'ESNext',
- moduleResolution: nuxt.options.future?.typescriptBundlerResolution || (nuxt.options.experimental as any)?.typescriptBundlerResolution ? 'Bundler' : 'Node',
- skipLibCheck: true,
- isolatedModules: true,
- useDefineForClassFields: true,
- strict: nuxt.options.typescript?.strict ?? true,
- noImplicitThis: true,
- esModuleInterop: true,
+ /* remove auto-scanning for types */
types: [],
- verbatimModuleSyntax: true,
- allowJs: true,
- noEmit: true,
- resolveJsonModule: true,
+ /* add paths object for filling-in later */
+ paths: {},
+ /* Possibly consider removing the following in future */
+ moduleResolution: nuxt.options.future?.typescriptBundlerResolution || (nuxt.options.experimental as any)?.typescriptBundlerResolution ? 'Bundler' : 'Node', /* implied by module: preserve */
+ useDefineForClassFields: true, /* implied by target: es2022+ */
+ noImplicitThis: true, /* enabled with `strict` */
allowSyntheticDefaultImports: true,
- paths: {}
},
include: [
'./nuxt.d.ts',
@@ -152,19 +177,19 @@ export async function writeTypes (nuxt: Nuxt) {
.filter(srcOrCwd => !srcOrCwd.startsWith(rootDirWithSlash) || srcOrCwd.includes('node_modules'))
.map(srcOrCwd => join(relative(nuxt.options.buildDir, srcOrCwd), '**/*')),
...nuxt.options.typescript.includeWorkspace && nuxt.options.workspaceDir !== nuxt.options.rootDir ? [join(relative(nuxt.options.buildDir, nuxt.options.workspaceDir), '**/*')] : [],
- ...modulePaths.map(m => join(relativeWithDot(nuxt.options.buildDir, m), 'runtime'))
+ ...modulePaths.map(m => join(relativeWithDot(nuxt.options.buildDir, m), 'runtime')),
],
exclude: [
...nuxt.options.modulesDir.map(m => relativeWithDot(nuxt.options.buildDir, m)),
...modulePaths.map(m => join(relativeWithDot(nuxt.options.buildDir, m), 'runtime/server')),
// nitro generate output: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nitro.ts#L186
- relativeWithDot(nuxt.options.buildDir, resolve(nuxt.options.rootDir, 'dist'))
- ]
+ relativeWithDot(nuxt.options.buildDir, resolve(nuxt.options.rootDir, 'dist')),
+ ],
} satisfies TSConfig)
const aliases: Record = {
...nuxt.options.alias,
- '#build': nuxt.options.buildDir
+ '#build': nuxt.options.buildDir,
}
// Exclude bridge alias types to support Volar
@@ -200,7 +225,7 @@ export async function writeTypes (nuxt: Nuxt) {
} else {
const path = stats?.isFile()
// remove extension
- ? relativePath.replace(/(?<=\w)\.\w+$/g, '')
+ ? relativePath.replace(/\b\.\w+$/g, '')
// non-existent file probably shouldn't be resolved
: aliases[alias]
@@ -214,7 +239,7 @@ export async function writeTypes (nuxt: Nuxt) {
const references: TSReference[] = await Promise.all([
...nuxt.options.modules,
- ...nuxt.options._modules
+ ...nuxt.options._modules,
]
.filter(f => typeof f === 'string')
.map(async id => ({ types: (await readPackageJSON(id, { url: nodeModulePaths }).catch(() => null))?.name || id })))
@@ -228,7 +253,7 @@ export async function writeTypes (nuxt: Nuxt) {
tsConfig.compilerOptions!.paths[alias] = await Promise.all(paths.map(async (path: string) => {
if (!isAbsolute(path)) { return path }
const stats = await fsp.stat(path).catch(() => null /* file does not exist */)
- return relativeWithDot(nuxt.options.buildDir, stats?.isFile() ? path.replace(/(?<=\w)\.\w+$/g, '') /* remove extension */ : path)
+ return relativeWithDot(nuxt.options.buildDir, stats?.isFile() ? path.replace(/\b\.\w+$/g, '') /* remove extension */ : path)
}))
}
@@ -245,9 +270,18 @@ export async function writeTypes (nuxt: Nuxt) {
...declarations,
'',
'export {}',
- ''
+ '',
].join('\n')
+ return {
+ declaration,
+ tsConfig,
+ }
+}
+
+export async function writeTypes (nuxt: Nuxt) {
+ const { tsConfig, declaration } = await _generateTypes(nuxt)
+
async function writeFile () {
const GeneratedBy = '// Generated by nuxi'
diff --git a/packages/kit/src/utils.ts b/packages/kit/src/utils.ts
index 4cc2040ad9..72b096120b 100644
--- a/packages/kit/src/utils.ts
+++ b/packages/kit/src/utils.ts
@@ -1,3 +1,4 @@
+/** @since 3.9.0 */
export function toArray (value: T | T[]): T[] {
return Array.isArray(value) ? value : [value]
}
diff --git a/packages/kit/test/generate-types.spec.ts b/packages/kit/test/generate-types.spec.ts
new file mode 100644
index 0000000000..7ac10ba8d1
--- /dev/null
+++ b/packages/kit/test/generate-types.spec.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import type { Nuxt, NuxtConfig } from '@nuxt/schema'
+import { defu } from 'defu'
+
+import { _generateTypes } from '../src/template'
+
+type DeepPartial = {
+ [P in keyof T]?: T[P] extends Record ? DeepPartial : T[P]
+}
+
+const mockNuxt = {
+ options: {
+ rootDir: '/my-app',
+ srcDir: '/my-app',
+ alias: {
+ '~': '/my-app',
+ 'some-custom-alias': '/my-app/some-alias',
+ },
+ typescript: { includeWorkspace: false },
+ buildDir: '/my-app/.nuxt',
+ modulesDir: ['/my-app/node_modules', '/node_modules'],
+ modules: [],
+ _layers: [{ config: { srcDir: '/my-app' } }],
+ _installedModules: [],
+ _modules: [],
+ },
+ callHook: () => {},
+} satisfies DeepPartial as unknown as Nuxt
+
+const mockNuxtWithOptions = (options: NuxtConfig) => defu({ options }, mockNuxt) as Nuxt
+
+describe('tsConfig generation', () => {
+ it('should add correct relative paths for aliases', async () => {
+ const { tsConfig } = await _generateTypes(mockNuxt)
+ expect(tsConfig.compilerOptions?.paths).toMatchInlineSnapshot(`
+ {
+ "#build": [
+ ".",
+ ],
+ "some-custom-alias": [
+ "../some-alias",
+ ],
+ "~": [
+ "..",
+ ],
+ }
+ `)
+ })
+
+ it('should add exclude for module paths', async () => {
+ const { tsConfig } = await _generateTypes(mockNuxtWithOptions({
+ modulesDir: ['/my-app/modules/test/node_modules', '/my-app/modules/node_modules', '/my-app/node_modules/@some/module/node_modules'],
+ }))
+ expect(tsConfig.exclude).toMatchInlineSnapshot(`
+ [
+ "../modules/test/node_modules",
+ "../modules/node_modules",
+ "../node_modules/@some/module/node_modules",
+ "../node_modules",
+ "../../node_modules",
+ "../dist",
+ ]
+ `)
+ })
+})
diff --git a/packages/nuxt/.gitignore b/packages/nuxt/.gitignore
new file mode 100644
index 0000000000..95c0486757
--- /dev/null
+++ b/packages/nuxt/.gitignore
@@ -0,0 +1,6 @@
+src/app/components/error-404.vue
+src/app/components/error-500.vue
+src/app/components/error-dev.vue
+src/app/components/welcome.vue
+src/core/runtime/nitro/error-500.ts
+src/core/runtime/nitro/error-dev.ts
diff --git a/packages/nuxt/build.config.ts b/packages/nuxt/build.config.ts
index dfaf1d97a0..1f8a82cf20 100644
--- a/packages/nuxt/build.config.ts
+++ b/packages/nuxt/build.config.ts
@@ -13,23 +13,23 @@ export default defineBuildConfig({
'core',
'head',
'components',
- 'pages'
- ].map(name => ({ input: `src/${name}/runtime/`, outDir: `dist/${name}/runtime`, format: 'esm', ext: 'js' } as BuildEntry))
+ 'pages',
+ ].map(name => ({ input: `src/${name}/runtime/`, outDir: `dist/${name}/runtime`, format: 'esm', ext: 'js' } as BuildEntry)),
],
hooks: {
'mkdist:entry:options' (_ctx, _entry, mkdistOptions) {
mkdistOptions.addRelativeDeclarationExtensions = true
- }
+ },
},
dependencies: [
'nuxi',
'vue-router',
- 'ofetch'
+ 'ofetch',
],
externals: [
'nuxt',
'nuxt/schema',
'@vue/shared',
- '@unhead/vue'
- ]
+ '@unhead/vue',
+ ],
})
diff --git a/packages/nuxt/config.cjs b/packages/nuxt/config.cjs
index cfdf3f8aa9..f4540f1290 100644
--- a/packages/nuxt/config.cjs
+++ b/packages/nuxt/config.cjs
@@ -3,5 +3,5 @@ function defineNuxtConfig (config) {
}
module.exports = {
- defineNuxtConfig
+ defineNuxtConfig,
}
diff --git a/packages/nuxt/config.d.ts b/packages/nuxt/config.d.ts
index e78965c0a3..a9272be362 100644
--- a/packages/nuxt/config.d.ts
+++ b/packages/nuxt/config.d.ts
@@ -1,5 +1,6 @@
import type { NuxtConfig } from 'nuxt/schema'
import type { ConfigLayerMeta, DefineConfig } from 'c12'
+
export { NuxtConfig } from 'nuxt/schema'
export interface DefineNuxtConfig extends DefineConfig {}
diff --git a/packages/nuxt/package.json b/packages/nuxt/package.json
index 49c0d28790..bc9c2b3c14 100644
--- a/packages/nuxt/package.json
+++ b/packages/nuxt/package.json
@@ -1,6 +1,6 @@
{
"name": "nuxt",
- "version": "3.10.3",
+ "version": "3.12.1",
"repository": {
"type": "git",
"url": "git+https://github.com/nuxt/nuxt.git",
@@ -60,69 +60,74 @@
},
"dependencies": {
"@nuxt/devalue": "^2.0.2",
- "@nuxt/devtools": "^1.0.8",
+ "@nuxt/devtools": "^1.3.3",
"@nuxt/kit": "workspace:*",
"@nuxt/schema": "workspace:*",
- "@nuxt/telemetry": "^2.5.3",
- "@nuxt/ui-templates": "^1.3.1",
+ "@nuxt/telemetry": "^2.5.4",
"@nuxt/vite-builder": "workspace:*",
- "@unhead/dom": "^1.8.10",
- "@unhead/ssr": "^1.8.10",
- "@unhead/vue": "^1.8.10",
- "@vue/shared": "^3.4.20",
+ "@unhead/dom": "^1.9.13",
+ "@unhead/ssr": "^1.9.13",
+ "@unhead/vue": "^1.9.13",
+ "@vue/shared": "^3.4.27",
"acorn": "8.11.3",
- "c12": "^1.9.0",
+ "c12": "^1.11.1",
"chokidar": "^3.6.0",
- "cookie-es": "^1.0.0",
+ "cookie-es": "^1.1.0",
"defu": "^6.1.4",
"destr": "^2.0.3",
- "devalue": "^4.3.2",
- "esbuild": "^0.20.1",
+ "devalue": "^5.0.0",
+ "esbuild": "^0.21.5",
"escape-string-regexp": "^5.0.0",
"estree-walker": "^3.0.3",
"fs-extra": "^11.2.0",
"globby": "^14.0.1",
"h3": "^1.11.1",
"hookable": "^5.5.3",
- "jiti": "^1.21.0",
+ "ignore": "^5.3.1",
+ "jiti": "^1.21.6",
"klona": "^2.0.6",
- "knitwork": "^1.0.0",
- "magic-string": "^0.30.7",
- "mlly": "^1.6.1",
- "nitropack": "^2.8.1",
- "nuxi": "^3.10.1",
- "nypm": "^0.3.6",
- "ofetch": "^1.3.3",
+ "knitwork": "^1.1.0",
+ "magic-string": "^0.30.10",
+ "mlly": "^1.7.1",
+ "nitropack": "^2.9.6",
+ "nuxi": "^3.12.0",
+ "nypm": "^0.3.8",
+ "ofetch": "^1.3.4",
"ohash": "^1.1.3",
"pathe": "^1.1.2",
"perfect-debounce": "^1.0.0",
- "pkg-types": "^1.0.3",
- "radix3": "^1.1.0",
+ "pkg-types": "^1.1.1",
+ "radix3": "^1.1.2",
"scule": "^1.3.0",
+ "semver": "^7.6.2",
"std-env": "^3.7.0",
- "strip-literal": "^2.0.0",
- "ufo": "^1.4.0",
+ "strip-literal": "^2.1.0",
+ "ufo": "^1.5.3",
"ultrahtml": "^1.5.3",
"uncrypto": "^0.1.3",
"unctx": "^2.3.1",
"unenv": "^1.9.0",
- "unimport": "^3.7.1",
- "unplugin": "^1.7.1",
+ "unimport": "^3.7.2",
+ "unplugin": "^1.10.1",
"unplugin-vue-router": "^0.7.0",
+ "unstorage": "^1.10.2",
"untyped": "^1.4.2",
- "vue": "^3.4.20",
- "vue-bundle-renderer": "^2.0.0",
+ "vue": "^3.4.27",
+ "vue-bundle-renderer": "^2.1.0",
"vue-devtools-stub": "^0.1.0",
- "vue-router": "^4.3.0"
+ "vue-router": "^4.3.3"
},
"devDependencies": {
+ "@nuxt/scripts": "0.5.1",
+ "@nuxt/ui-templates": "1.3.4",
"@parcel/watcher": "2.4.1",
"@types/estree": "1.0.5",
"@types/fs-extra": "11.0.4",
"@vitejs/plugin-vue": "5.0.4",
+ "@vue/compiler-sfc": "3.4.27",
"unbuild": "latest",
- "vite": "5.1.4",
- "vitest": "1.3.1"
+ "vite": "5.3.0",
+ "vitest": "1.6.0"
},
"peerDependencies": {
"@parcel/watcher": "^2.1.0",
diff --git a/packages/nuxt/src/app/compat/idle-callback.ts b/packages/nuxt/src/app/compat/idle-callback.ts
index 01779dc1fe..12e01230e7 100644
--- a/packages/nuxt/src/app/compat/idle-callback.ts
+++ b/packages/nuxt/src/app/compat/idle-callback.ts
@@ -6,7 +6,7 @@ export const requestIdleCallback: Window['requestIdleCallback'] = import.meta.se
const start = Date.now()
const idleDeadline = {
didTimeout: false,
- timeRemaining: () => Math.max(0, 50 - (Date.now() - start))
+ timeRemaining: () => Math.max(0, 50 - (Date.now() - start)),
}
return setTimeout(() => { cb(idleDeadline) }, 1)
}))
diff --git a/packages/nuxt/src/app/compat/interval.ts b/packages/nuxt/src/app/compat/interval.ts
index 74adf6c39c..36017305c1 100644
--- a/packages/nuxt/src/app/compat/interval.ts
+++ b/packages/nuxt/src/app/compat/interval.ts
@@ -2,13 +2,15 @@ import { createError } from '../composables/error'
const intervalError = '[nuxt] `setInterval` should not be used on the server. Consider wrapping it with an `onNuxtReady`, `onBeforeMount` or `onMounted` lifecycle hook, or ensure you only call it in the browser by checking `import.meta.client`.'
-export const setInterval = import.meta.client ? window.setInterval : () => {
- if (import.meta.dev) {
- throw createError({
- statusCode: 500,
- message: intervalError
- })
- }
+export const setInterval = import.meta.client
+ ? window.setInterval
+ : () => {
+ if (import.meta.dev) {
+ throw createError({
+ statusCode: 500,
+ message: intervalError,
+ })
+ }
- console.error(intervalError)
-}
+ console.error(intervalError)
+ }
diff --git a/packages/nuxt/src/app/components/client-fallback.client.ts b/packages/nuxt/src/app/components/client-fallback.client.ts
index d1f249ba3f..f92dfb7a31 100644
--- a/packages/nuxt/src/app/components/client-fallback.client.ts
+++ b/packages/nuxt/src/app/components/client-fallback.client.ts
@@ -6,26 +6,26 @@ export default defineComponent({
inheritAttrs: false,
props: {
uid: {
- type: String
+ type: String,
},
fallbackTag: {
type: String,
- default: () => 'div'
+ default: () => 'div',
},
fallback: {
type: String,
- default: () => ''
+ default: () => '',
},
placeholder: {
- type: String
+ type: String,
},
placeholderTag: {
- type: String
+ type: String,
},
keepFallback: {
type: Boolean,
- default: () => false
- }
+ default: () => false,
+ },
},
emits: ['ssr-error'],
setup (props, ctx) {
@@ -49,5 +49,5 @@ export default defineComponent({
}
return ctx.slots.default?.()
}
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/client-fallback.server.ts b/packages/nuxt/src/app/components/client-fallback.server.ts
index 3b07745b38..c1bc3c3e02 100644
--- a/packages/nuxt/src/app/components/client-fallback.server.ts
+++ b/packages/nuxt/src/app/components/client-fallback.server.ts
@@ -1,6 +1,6 @@
import { defineComponent, getCurrentInstance, onErrorCaptured, ref } from 'vue'
import { ssrRenderAttrs, ssrRenderSlot, ssrRenderVNode } from 'vue/server-renderer'
-// eslint-disable-next-line
+
import { isPromise } from '@vue/shared'
import { useState } from '../composables/state'
import { useNuxtApp } from '../nuxt'
@@ -11,39 +11,40 @@ const NuxtClientFallbackServer = defineComponent({
inheritAttrs: false,
props: {
uid: {
- type: String
+ type: String,
},
fallbackTag: {
type: String,
- default: () => 'div'
+ default: () => 'div',
},
fallback: {
type: String,
- default: () => ''
+ default: () => '',
},
placeholder: {
- type: String
+ type: String,
},
placeholderTag: {
- type: String
+ type: String,
},
keepFallback: {
type: Boolean,
- default: () => false
- }
+ default: () => false,
+ },
},
emits: {
'ssr-error' (_error: unknown) {
return true
- }
+ },
},
async setup (props, ctx) {
const vm = getCurrentInstance()
const ssrFailed = ref(false)
const nuxtApp = useNuxtApp()
+ const error = useState(`${props.uid}`)
onErrorCaptured((err) => {
- useState(`${props.uid}`, () => true)
+ error.value = true
ssrFailed.value = true
ctx.emit('ssr-error', err)
return false
@@ -86,7 +87,7 @@ const NuxtClientFallbackServer = defineComponent({
push(ctx.ssrVNodes.getBuffer())
push('')
}
- }
+ },
})
export default NuxtClientFallbackServer
diff --git a/packages/nuxt/src/app/components/client-only.ts b/packages/nuxt/src/app/components/client-only.ts
index a526347122..5483dbe0c6 100644
--- a/packages/nuxt/src/app/components/client-only.ts
+++ b/packages/nuxt/src/app/components/client-only.ts
@@ -8,7 +8,7 @@ export const clientOnlySymbol: InjectionKey = Symbol.for('nuxt:client-o
export default defineComponent({
name: 'ClientOnly',
inheritAttrs: false,
- // eslint-disable-next-line vue/require-prop-types
+
props: ['fallback', 'placeholder', 'placeholderTag', 'fallbackTag'],
setup (_, { slots, attrs }) {
const mounted = ref(false)
@@ -28,12 +28,12 @@ export default defineComponent({
const fallbackTag = props.fallbackTag || props.placeholderTag || 'span'
return createElementBlock(fallbackTag, attrs, fallbackStr)
}
- }
+ },
})
const cache = new WeakMap()
-/*@__NO_SIDE_EFFECTS__*/
+/* @__NO_SIDE_EFFECTS__ */
export function createClientOnly (component: T) {
if (cache.has(component)) {
return cache.get(component)
diff --git a/packages/nuxt/src/app/components/dev-only.ts b/packages/nuxt/src/app/components/dev-only.ts
index 6c8ec7c5e9..a1446dd3dd 100644
--- a/packages/nuxt/src/app/components/dev-only.ts
+++ b/packages/nuxt/src/app/components/dev-only.ts
@@ -7,5 +7,5 @@ export default defineComponent({
return () => props.slots.default?.()
}
return () => props.slots.fallback?.()
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/island-renderer.ts b/packages/nuxt/src/app/components/island-renderer.ts
index 6fc2fd479d..59e767f867 100644
--- a/packages/nuxt/src/app/components/island-renderer.ts
+++ b/packages/nuxt/src/app/components/island-renderer.ts
@@ -10,8 +10,8 @@ export default defineComponent({
props: {
context: {
type: Object as () => { name: string, props?: Record },
- required: true
- }
+ required: true,
+ },
},
setup (props) {
const component = islandComponents[props.context.name] as ReturnType
@@ -19,7 +19,7 @@ export default defineComponent({
if (!component) {
throw createError({
statusCode: 404,
- statusMessage: `Island component not found: ${props.context.name}`
+ statusMessage: `Island component not found: ${props.context.name}`,
})
}
@@ -28,5 +28,5 @@ export default defineComponent({
})
return () => createVNode(component || 'span', { ...props.context.props, 'data-island-uid': '' })
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/nuxt-error-boundary.ts b/packages/nuxt/src/app/components/nuxt-error-boundary.ts
index 77659e2c29..ea54ff8393 100644
--- a/packages/nuxt/src/app/components/nuxt-error-boundary.ts
+++ b/packages/nuxt/src/app/components/nuxt-error-boundary.ts
@@ -5,7 +5,7 @@ export default defineComponent({
emits: {
error (_error: unknown) {
return true
- }
+ },
},
setup (_props, { slots, emit }) {
const error = ref(null)
@@ -25,5 +25,5 @@ export default defineComponent({
}
return () => error.value ? slots.error?.({ error, clearError }) : slots.default?.()
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/nuxt-error-page.vue b/packages/nuxt/src/app/components/nuxt-error-page.vue
index 50308e6604..14feb22ae0 100644
--- a/packages/nuxt/src/app/components/nuxt-error-page.vue
+++ b/packages/nuxt/src/app/components/nuxt-error-page.vue
@@ -6,7 +6,7 @@
import { defineAsyncComponent } from 'vue'
const props = defineProps({
- error: Object
+ error: Object,
})
// Deliberately prevent reactive update when error is cleared
@@ -26,7 +26,7 @@ const stacktrace = _error.stack
text,
internal: (line.includes('node_modules') && !line.includes('.cache')) ||
line.includes('internal') ||
- line.includes('new Promise')
+ line.includes('new Promise'),
}
}).map(i => `${i.text}`).join('\n')
: ''
@@ -40,10 +40,10 @@ const description = _error.message || _error.toString()
const stack = import.meta.dev && !is404 ? _error.description || `() : undefined
-async function loadComponents (source = '/', paths: NuxtIslandResponse['components']) {
+async function loadComponents (source = appBaseURL, paths: NuxtIslandResponse['components']) {
const promises = []
for (const component in paths) {
@@ -49,20 +48,24 @@ export default defineComponent({
props: {
name: {
type: String,
- required: true
+ required: true,
},
lazy: Boolean,
props: {
type: Object,
- default: () => undefined
+ default: () => undefined,
},
context: {
type: Object,
- default: () => ({})
+ default: () => ({}),
+ },
+ scopeId: {
+ type: String as PropType,
+ default: () => undefined,
},
source: {
type: String,
- default: () => undefined
+ default: () => undefined,
},
/**
* use the NuxtIslandResponse which has been cached if available
@@ -74,10 +77,11 @@ export default defineComponent({
},
dangerouslyLoadClientComponents: {
type: Boolean,
- default: false
- }
+ default: false,
+ },
},
- async setup (props, { slots, expose }) {
+ emits: ['error'],
+ async setup (props, { slots, expose, emit }) {
let canTeleport = import.meta.server
const teleportKey = ref(0)
const key = ref(0)
@@ -96,37 +100,41 @@ export default defineComponent({
onMounted(() => { mounted.value = true; teleportKey.value++ })
function setPayload (key: string, result: NuxtIslandResponse) {
+ const toRevive: Partial = {}
+ if (result.props) { toRevive.props = result.props }
+ if (result.slots) { toRevive.slots = result.slots }
+ if (result.components) { toRevive.components = result.components }
+
nuxtApp.payload.data[key] = {
__nuxt_island: {
key,
...(import.meta.server && import.meta.prerender)
? {}
: { params: { ...props.context, props: props.props ? JSON.stringify(props.props) : undefined } },
- result: {
- props: result.props,
- slots: result.slots,
- components: result.components
- }
+ result: toRevive,
},
- ...result
+ ...result,
}
}
- const payloads: Required> = {
- slots: {},
- components: {}
- }
+ const payloads: Partial> = {}
-
- if (nuxtApp.isHydrating) {
- payloads.slots = toRaw(nuxtApp.payload.data[`${props.name}_${hashId.value}`])?.slots ?? {}
- payloads.components = toRaw(nuxtApp.payload.data[`${props.name}_${hashId.value}`])?.components ?? {}
+ if (instance.vnode.el) {
+ const slots = toRaw(nuxtApp.payload.data[`${props.name}_${hashId.value}`])?.slots
+ if (slots) { payloads.slots = slots }
+ if (selectiveClient) {
+ const components = toRaw(nuxtApp.payload.data[`${props.name}_${hashId.value}`])?.components
+ if (components) { payloads.components = components }
+ }
}
const ssrHTML = ref('')
- if (import.meta.client && nuxtApp.isHydrating) {
- ssrHTML.value = getFragmentHTML(instance.vnode?.el ?? null, true)?.join('') || ''
+ if (import.meta.client && instance.vnode?.el) {
+ ssrHTML.value = getFragmentHTML(instance.vnode.el, true)?.join('') || ''
+ const key = `${props.name}_${hashId.value}`
+ nuxtApp.payload.data[key] ||= {}
+ nuxtApp.payload.data[key].html = ssrHTML.value
}
const uid = ref(ssrHTML.value.match(SSR_UID_RE)?.[1] ?? getId())
@@ -135,6 +143,10 @@ export default defineComponent({
const currentSlots = Object.keys(slots)
let html = ssrHTML.value
+ if (props.scopeId) {
+ html = html.replace(/^<[^> ]*/, full => full + ' ' + props.scopeId)
+ }
+
if (import.meta.client && !canLoadClientComponent.value) {
for (const [key, value] of Object.entries(payloads.components || {})) {
html = html.replace(new RegExp(` data-island-uid="${uid.value}" data-island-component="${key}"[^>]*>`), (full) => {
@@ -143,12 +155,15 @@ export default defineComponent({
}
}
- return html.replaceAll(SLOT_FALLBACK_RE, (full, slotName) => {
- if (!currentSlots.includes(slotName)) {
- return full + (payloads.slots[slotName]?.fallback || '')
- }
- return full
- })
+ if (payloads.slots) {
+ return html.replaceAll(SLOT_FALLBACK_RE, (full, slotName) => {
+ if (!currentSlots.includes(slotName)) {
+ return full + (payloads.slots?.[slotName]?.fallback || '')
+ }
+ return full
+ })
+ }
+ return html
})
const cHead = ref>>>({ link: [], style: [] })
@@ -157,7 +172,7 @@ export default defineComponent({
async function _fetchComponent (force = false) {
const key = `${props.name}_${hashId.value}`
- if (nuxtApp.payload.data[key]?.html && !force) { return nuxtApp.payload.data[key] }
+ if (!force && nuxtApp.payload.data[key]?.html) { return nuxtApp.payload.data[key] }
const url = remoteComponentIslands && props.source ? new URL(`/__nuxt_island/${key}.json`, props.source).href : `/__nuxt_island/${key}.json`
@@ -169,7 +184,7 @@ export default defineComponent({
// $fetch handles the app.baseURL in dev
const r = await eventFetch(withQuery(((import.meta.dev && import.meta.client) || props.source) ? url : joinURL(config.app.baseURL ?? '', url), {
...props.context,
- props: props.props ? JSON.stringify(props.props) : undefined
+ props: props.props ? JSON.stringify(props.props) : undefined,
}))
const result = import.meta.server || !import.meta.dev ? await r.json() : (r as FetchResponse)._data
// TODO: support passing on more headers
@@ -217,11 +232,12 @@ export default defineComponent({
}
} catch (e) {
error.value = e
+ emit('error', e)
}
}
expose({
- refresh: () => fetchComponent(true)
+ refresh: () => fetchComponent(true),
})
if (import.meta.hot) {
@@ -257,42 +273,50 @@ export default defineComponent({
// this is used to force trigger Teleport when vue makes the diff between old and new node
const isKeyOdd = teleportKey.value === 0 || !!(teleportKey.value && !(teleportKey.value % 2))
- if (uid.value && html.value && (import.meta.server || props.lazy ? canTeleport : mounted.value || nuxtApp.isHydrating)) {
+ if (uid.value && html.value && (import.meta.server || props.lazy ? canTeleport : (mounted.value || instance.vnode?.el))) {
for (const slot in slots) {
if (availableSlots.value.includes(slot)) {
teleports.push(createVNode(Teleport,
// use different selectors for even and odd teleportKey to force trigger the teleport
{ to: import.meta.client ? `${isKeyOdd ? 'div' : ''}[data-island-uid="${uid.value}"][data-island-slot="${slot}"]` : `uid=${uid.value};slot=${slot}` },
- { default: () => (payloads.slots[slot].props?.length ? payloads.slots[slot].props : [{}]).map((data: any) => slots[slot]?.(data)) })
+ { default: () => (payloads.slots?.[slot].props?.length ? payloads.slots[slot].props : [{}]).map((data: any) => slots[slot]?.(data)) }),
)
}
}
- if (import.meta.server) {
- for (const [id, info] of Object.entries(payloads.components ?? {})) {
- const { html } = info
- teleports.push(createVNode(Teleport, { to: `uid=${uid.value};client=${id}` }, {
- default: () => [createStaticVNode(html, 1)]
- }))
- }
- }
- if (selectiveClient && import.meta.client && canLoadClientComponent.value) {
- for (const [id, info] of Object.entries(payloads.components ?? {})) {
- const { props } = info
- const component = components!.get(id)!
- // use different selectors for even and odd teleportKey to force trigger the teleport
- const vnode = createVNode(Teleport, { to: `${isKeyOdd ? 'div' : ''}[data-island-uid='${uid.value}'][data-island-component="${id}"]` }, {
- default: () => {
- return [h(component, props)]
+ if (selectiveClient) {
+ if (import.meta.server) {
+ if (payloads.components) {
+ for (const [id, info] of Object.entries(payloads.components)) {
+ const { html, slots } = info
+ let replaced = html.replaceAll('data-island-uid', `data-island-uid="${uid.value}"`)
+ for (const slot in slots) {
+ replaced = replaced.replaceAll(`data-island-slot="${slot}">`, full => full + slots[slot])
+ }
+ teleports.push(createVNode(Teleport, { to: `uid=${uid.value};client=${id}` }, {
+ default: () => [createStaticVNode(replaced, 1)],
+ }))
}
- })
- teleports.push(vnode)
+ }
+ } else if (canLoadClientComponent.value && payloads.components) {
+ for (const [id, info] of Object.entries(payloads.components)) {
+ const { props, slots } = info
+ const component = components!.get(id)!
+ // use different selectors for even and odd teleportKey to force trigger the teleport
+ const vnode = createVNode(Teleport, { to: `${isKeyOdd ? 'div' : ''}[data-island-uid='${uid.value}'][data-island-component="${id}"]` }, {
+ default: () => {
+ return [h(component, props, Object.fromEntries(Object.entries(slots || {}).map(([k, v]) => ([k, () => createStaticVNode(` : PageMeta['layout'],
- default: null
+ default: null,
},
fallback: {
type: [String, Object] as unknown as () => unknown extends PageMeta['layout'] ? MaybeRef : PageMeta['layout'],
- default: null
- }
+ default: null,
+ },
},
setup (props, context) {
const nuxtApp = useNuxtApp()
@@ -94,12 +93,12 @@ export default defineComponent({
key: layout.value || undefined,
name: layout.value,
shouldProvide: !props.name,
- hasTransition: !!transitionProps
- }, context.slots)
- })
+ hasTransition: !!transitionProps,
+ }, context.slots),
+ }),
}).default()
}
- }
+ },
}) as unknown as DefineComponent<{
name?: (unknown extends PageMeta['layout'] ? MaybeRef : PageMeta['layout']) | undefined
}>
@@ -109,17 +108,17 @@ const LayoutProvider = defineComponent({
inheritAttrs: false,
props: {
name: {
- type: [String, Boolean] as unknown as () => string | false
+ type: [String, Boolean] as unknown as () => string | false,
},
layoutProps: {
- type: Object
+ type: Object,
},
hasTransition: {
- type: Boolean
+ type: Boolean,
},
shouldProvide: {
- type: Boolean
- }
+ type: Boolean,
+ },
},
setup (props, context) {
// Prevent reactivity when the page will be rerendered in a different suspense fork
@@ -127,7 +126,7 @@ const LayoutProvider = defineComponent({
const name = props.name
if (props.shouldProvide) {
provide(LayoutMetaSymbol, {
- isCurrent: (route: RouteLocationNormalizedLoaded) => name === (route.meta.layout ?? 'default')
+ isCurrent: (route: RouteLocationNormalizedLoaded) => name === (route.meta.layout ?? 'default'),
})
}
@@ -159,7 +158,7 @@ const LayoutProvider = defineComponent({
vnode = h(
LayoutLoader,
{ key: name, layoutProps: props.layoutProps, name },
- context.slots
+ context.slots,
)
return vnode
@@ -168,8 +167,8 @@ const LayoutProvider = defineComponent({
return h(
LayoutLoader,
{ key: name, layoutProps: props.layoutProps, name },
- context.slots
+ context.slots,
)
}
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/nuxt-link.ts b/packages/nuxt/src/app/components/nuxt-link.ts
index e3ecfd29a9..e4fa62d8a4 100644
--- a/packages/nuxt/src/app/components/nuxt-link.ts
+++ b/packages/nuxt/src/app/components/nuxt-link.ts
@@ -4,11 +4,11 @@ import type {
ComputedRef,
DefineComponent,
InjectionKey, PropType,
- VNodeProps
+ VNodeProps,
} from 'vue'
import { computed, defineComponent, h, inject, onBeforeUnmount, onMounted, provide, ref, resolveComponent } from 'vue'
-import type { RouteLocation, RouteLocationRaw, Router, RouterLinkProps } from '#vue-router'
-import { hasProtocol, joinURL, parseQuery, parseURL, withTrailingSlash, withoutTrailingSlash } from 'ufo'
+import type { RouteLocation, RouteLocationRaw, Router, RouterLink, RouterLinkProps, useLink } from '#vue-router'
+import { hasProtocol, joinURL, parseQuery, withQuery, withTrailingSlash, withoutTrailingSlash } from 'ufo'
import { preloadRouteComponents } from '../composables/preload'
import { onNuxtReady } from '../composables/ready'
import { navigateTo, useRouter } from '../composables/router'
@@ -23,30 +23,7 @@ const firstNonUndefined = (...args: (T | undefined)[]) => args.find(arg => a
const NuxtLinkDevKeySymbol: InjectionKey = Symbol('nuxt-link-dev-key')
/**
- * Create a NuxtLink component with given options as defaults.
- * @see https://nuxt.com/docs/api/components/nuxt-link
- */
-export interface NuxtLinkOptions extends
- Pick,
- Pick {
- /**
- * The name of the component.
- * @default "NuxtLink"
- */
- componentName?: string
- /**
- * A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable.
- */
- externalRelAttribute?: string | null
- /**
- * An option to either add or remove trailing slashes in the `href`.
- * If unset or not matching the valid values `append` or `remove`, it will be ignored.
- */
- trailingSlash?: 'append' | 'remove'
-}
-
-/**
- * is a drop-in replacement for both Vue Router's component and HTML's tag.
+ * `` is a drop-in replacement for both Vue Router's `` component and HTML's `` tag.
* @see https://nuxt.com/docs/api/components/nuxt-link
*/
export interface NuxtLinkProps extends Omit {
@@ -88,7 +65,30 @@ export interface NuxtLinkProps extends Omit {
noPrefetch?: boolean
}
- /*@__NO_SIDE_EFFECTS__*/
+/**
+ * Create a NuxtLink component with given options as defaults.
+ * @see https://nuxt.com/docs/api/components/nuxt-link
+ */
+export interface NuxtLinkOptions extends
+ Partial>,
+ Partial> {
+ /**
+ * The name of the component.
+ * @default "NuxtLink"
+ */
+ componentName?: string
+ /**
+ * A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable.
+ */
+ externalRelAttribute?: string | null
+ /**
+ * An option to either add or remove trailing slashes in the `href`.
+ * If unset or not matching the valid values `append` or `remove`, it will be ignored.
+ */
+ trailingSlash?: 'append' | 'remove'
+}
+
+/* @__NO_SIDE_EFFECTS__ */
export function defineNuxtLink (options: NuxtLinkOptions) {
const componentName = options.componentName || 'NuxtLink'
@@ -113,17 +113,92 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
const resolvedPath = {
...to,
- path: applyTrailingSlashBehavior(path, options.trailingSlash)
- }
-
- // named routes would otherwise always override trailing slash behavior
- if ('name' in resolvedPath) {
- delete resolvedPath.name
+ name: undefined, // named routes would otherwise always override trailing slash behavior
+ path: applyTrailingSlashBehavior(path, options.trailingSlash),
}
return resolvedPath
}
+ function useNuxtLink (props: NuxtLinkProps) {
+ const router = useRouter()
+ const config = useRuntimeConfig()
+
+ const hasTarget = computed(() => !!props.target && props.target !== '_self')
+
+ // Lazily check whether to.value has a protocol
+ const isAbsoluteUrl = computed(() => {
+ const path = props.to || props.href || ''
+ return typeof path === 'string' && hasProtocol(path, { acceptRelative: true })
+ })
+
+ const builtinRouterLink = resolveComponent('RouterLink') as string | typeof RouterLink
+ const useBuiltinLink = builtinRouterLink && typeof builtinRouterLink !== 'string' ? builtinRouterLink.useLink : undefined
+
+ // Resolving link type
+ const isExternal = computed(() => {
+ // External prop is explicitly set
+ if (props.external) {
+ return true
+ }
+
+ const path = props.to || props.href || ''
+
+ // When `to` is a route object then it's an internal link
+ if (typeof path === 'object') {
+ return false
+ }
+
+ return path === '' || isAbsoluteUrl.value
+ })
+
+ // Resolving `to` value from `to` and `href` props
+ const to: ComputedRef = computed(() => {
+ checkPropConflicts(props, 'to', 'href')
+ const path = props.to || props.href || '' // Defaults to empty string (won't render any `href` attribute)
+ if (isExternal.value) { return path }
+ return resolveTrailingSlashBehavior(path, router.resolve)
+ })
+
+ const link = isExternal.value ? undefined : useBuiltinLink?.({ ...props, to })
+
+ // Resolves `to` value if it's a route location object
+ const href = computed(() => {
+ if (!to.value || isAbsoluteUrl.value) { return to.value as string }
+
+ if (isExternal.value) {
+ const path = typeof to.value === 'object' ? resolveRouteObject(to.value) : to.value
+ return resolveTrailingSlashBehavior(path, router.resolve /* will not be called */) as string
+ }
+
+ if (typeof to.value === 'object') {
+ return router.resolve(to.value)?.href ?? null
+ }
+
+ return resolveTrailingSlashBehavior(joinURL(config.app.baseURL, to.value), router.resolve /* will not be called */)
+ })
+
+ return {
+ to,
+ hasTarget,
+ isAbsoluteUrl,
+ isExternal,
+ //
+ href,
+ isActive: link?.isActive ?? computed(() => to.value === router.currentRoute.value.path),
+ isExactActive: link?.isExactActive ?? computed(() => to.value === router.currentRoute.value.path),
+ route: link?.route ?? computed(() => router.resolve(to.value)),
+ async navigate () {
+ await navigateTo(href.value, { replace: props.replace, external: isExternal.value || hasTarget.value })
+ },
+ } satisfies ReturnType & {
+ to: ComputedRef
+ hasTarget: ComputedRef
+ isAbsoluteUrl: ComputedRef
+ isExternal: ComputedRef
+ }
+ }
+
return defineComponent({
name: componentName,
props: {
@@ -131,123 +206,91 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
to: {
type: [String, Object] as PropType,
default: undefined,
- required: false
+ required: false,
},
href: {
type: [String, Object] as PropType,
default: undefined,
- required: false
+ required: false,
},
// Attributes
target: {
type: String as PropType,
default: undefined,
- required: false
+ required: false,
},
rel: {
type: String as PropType,
default: undefined,
- required: false
+ required: false,
},
noRel: {
type: Boolean as PropType,
default: undefined,
- required: false
+ required: false,
},
// Prefetching
prefetch: {
type: Boolean as PropType,
default: undefined,
- required: false
+ required: false,
},
noPrefetch: {
type: Boolean as PropType,
default: undefined,
- required: false
+ required: false,
},
// Styling
activeClass: {
type: String as PropType,
default: undefined,
- required: false
+ required: false,
},
exactActiveClass: {
type: String as PropType,
default: undefined,
- required: false
+ required: false,
},
prefetchedClass: {
type: String as PropType,
default: undefined,
- required: false
+ required: false,
},
// Vue Router's `` additional props
replace: {
type: Boolean as PropType,
default: undefined,
- required: false
+ required: false,
},
ariaCurrentValue: {
type: String as PropType,
default: undefined,
- required: false
+ required: false,
},
// Edge cases handling
external: {
type: Boolean as PropType,
default: undefined,
- required: false
+ required: false,
},
// Slot API
custom: {
type: Boolean as PropType,
default: undefined,
- required: false
- }
+ required: false,
+ },
},
+ useLink: useNuxtLink,
setup (props, { slots }) {
const router = useRouter()
- const config = useRuntimeConfig()
- // Resolving `to` value from `to` and `href` props
- const to: ComputedRef = computed(() => {
- checkPropConflicts(props, 'to', 'href')
-
- const path = props.to || props.href || '' // Defaults to empty string (won't render any `href` attribute)
-
- return resolveTrailingSlashBehavior(path, router.resolve)
- })
-
- // Lazily check whether to.value has a protocol
- const isAbsoluteUrl = computed(() => typeof to.value === 'string' && hasProtocol(to.value, { acceptRelative: true }))
-
- const hasTarget = computed(() => props.target && props.target !== '_self')
-
- // Resolving link type
- const isExternal = computed(() => {
- // External prop is explicitly set
- if (props.external) {
- return true
- }
-
- // When `target` prop is set, link is external
- if (hasTarget.value) {
- return true
- }
-
- // When `to` is a route object then it's an internal link
- if (typeof to.value === 'object') {
- return false
- }
-
- return to.value === '' || isAbsoluteUrl.value
- })
+ const { to, href, navigate, isExternal, hasTarget, isAbsoluteUrl } = useNuxtLink(props)
// Prefetching
const prefetched = ref(false)
@@ -270,10 +313,12 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
unobserve?.()
unobserve = null
- const path = typeof to.value === 'string' ? to.value : router.resolve(to.value).fullPath
+ const path = typeof to.value === 'string'
+ ? to.value
+ : isExternal.value ? resolveRouteObject(to.value) : router.resolve(to.value).fullPath
await Promise.all([
nuxtApp.hooks.callHook('link:prefetch', path).catch(() => {}),
- !isExternal.value && preloadRouteComponents(to.value as string, router).catch(() => {})
+ !isExternal.value && !hasTarget.value && preloadRouteComponents(to.value as string, router).catch(() => {}),
])
prefetched.value = true
})
@@ -299,7 +344,7 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
}
return () => {
- if (!isExternal.value) {
+ if (!isExternal.value && !hasTarget.value) {
const routerLinkProps: RouterLinkProps & VNodeProps & AllowedComponentProps & AnchorHTMLAttributes = {
ref: elRef,
to: to.value,
@@ -307,7 +352,7 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
exactActiveClass: props.exactActiveClass || options.exactActiveClass,
replace: props.replace,
ariaCurrentValue: props.ariaCurrentValue,
- custom: props.custom
+ custom: props.custom,
}
// `custom` API cannot support fallthrough attributes as the slot
@@ -323,18 +368,10 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
return h(
resolveComponent('RouterLink'),
routerLinkProps,
- slots.default
+ slots.default,
)
}
- // Resolves `to` value if it's a route location object
- // converts `""` to `null` to prevent the attribute from being added as empty (`href=""`)
- const href = typeof to.value === 'object'
- ? router.resolve(to.value)?.href ?? null
- : (to.value && !props.external && !isAbsoluteUrl.value)
- ? resolveTrailingSlashBehavior(joinURL(config.app.baseURL, to.value), router.resolve) as string
- : to.value || null
-
// Resolves `target` value
const target = props.target || null
@@ -348,7 +385,7 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
* A fallback rel of `noopener noreferrer` is applied for external links or links that open in a new tab.
* This solves a reverse tabnapping security flaw in browsers pre-2021 as well as improving privacy.
*/
- (isAbsoluteUrl.value || hasTarget.value) ? 'noopener noreferrer' : ''
+ (isAbsoluteUrl.value || hasTarget.value) ? 'noopener noreferrer' : '',
) || null
// https://router.vuejs.org/api/#custom
@@ -357,15 +394,13 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
return null
}
- const navigate = () => navigateTo(href, { replace: props.replace, external: props.external })
-
return slots.default({
- href,
+ href: href.value,
navigate,
get route () {
- if (!href) { return undefined }
+ if (!href.value) { return undefined }
- const url = parseURL(href)
+ const url = new URL(href.value, import.meta.client ? window.location.href : 'http://localhost')
return {
path: url.pathname,
fullPath: url.pathname,
@@ -376,20 +411,21 @@ export function defineNuxtLink (options: NuxtLinkOptions) {
matched: [],
redirectedFrom: undefined,
meta: {},
- href
+ href: href.value,
} satisfies RouteLocation & { href: string }
},
rel,
target,
- isExternal: isExternal.value,
+ isExternal: isExternal.value || hasTarget.value,
isActive: false,
- isExactActive: false
+ isExactActive: false,
})
}
- return h('a', { ref: el, href, rel, target }, slots.default?.())
+ // converts `""` to `null` to prevent the attribute from being added as empty (`href=""`)
+ return h('a', { ref: el, href: href.value || null, rel, target }, slots.default?.())
}
- }
+ },
}) as unknown as DefineComponent
}
@@ -445,7 +481,7 @@ function useObserver (): { observe: ObserveFn } | undefined {
}
const _observer = nuxtApp._observer = {
- observe
+ observe,
}
return _observer
@@ -459,3 +495,7 @@ function isSlowConnection () {
if (cn && (cn.saveData || /2g/.test(cn.effectiveType))) { return true }
return false
}
+
+function resolveRouteObject (to: Exclude) {
+ return withQuery(to.path || '', to.query || {}) + (to.hash ? '#' + to.hash : '')
+}
diff --git a/packages/nuxt/src/app/components/nuxt-loading-indicator.ts b/packages/nuxt/src/app/components/nuxt-loading-indicator.ts
index 1020be8164..a0273a8428 100644
--- a/packages/nuxt/src/app/components/nuxt-loading-indicator.ts
+++ b/packages/nuxt/src/app/components/nuxt-loading-indicator.ts
@@ -6,34 +6,38 @@ export default defineComponent({
props: {
throttle: {
type: Number,
- default: 200
+ default: 200,
},
duration: {
type: Number,
- default: 2000
+ default: 2000,
},
height: {
type: Number,
- default: 3
+ default: 3,
},
color: {
type: [String, Boolean],
- default: 'repeating-linear-gradient(to right,#00dc82 0%,#34cdfe 50%,#0047e1 100%)'
+ default: 'repeating-linear-gradient(to right,#00dc82 0%,#34cdfe 50%,#0047e1 100%)',
+ },
+ errorColor: {
+ type: String,
+ default: 'repeating-linear-gradient(to right,#f87171 0%,#ef4444 100%)',
},
estimatedProgress: {
type: Function as unknown as () => (duration: number, elapsed: number) => number,
- required: false
+ required: false,
},
},
setup (props, { slots, expose }) {
- const { progress, isLoading, start, finish, clear } = useLoadingIndicator({
+ const { progress, isLoading, error, start, finish, clear } = useLoadingIndicator({
duration: props.duration,
throttle: props.throttle,
estimatedProgress: props.estimatedProgress,
})
expose({
- progress, isLoading, start, finish, clear
+ progress, isLoading, error, start, finish, clear,
})
return () => h('div', {
@@ -47,13 +51,13 @@ export default defineComponent({
width: 'auto',
height: `${props.height}px`,
opacity: isLoading.value ? 1 : 0,
- background: props.color || undefined,
+ background: error.value ? props.errorColor : props.color || undefined,
backgroundSize: `${(100 / progress.value) * 100}% auto`,
transform: `scaleX(${progress.value}%)`,
transformOrigin: 'left',
transition: 'transform 0.1s, height 0.4s, opacity 0.4s',
- zIndex: 999999
- }
+ zIndex: 999999,
+ },
}, slots)
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/nuxt-root.vue b/packages/nuxt/src/app/components/nuxt-root.vue
index cfbb1aaea9..eefe5fee7f 100644
--- a/packages/nuxt/src/app/components/nuxt-root.vue
+++ b/packages/nuxt/src/app/components/nuxt-root.vue
@@ -1,7 +1,8 @@
+
import('./island-renderer').then(r => r.default || r))
: () => null
@@ -51,6 +54,8 @@ if (import.meta.dev && results && results.some(i => i && 'then' in i)) {
// error handling
const error = useError()
+// render an empty
+
+
+
+```
+
+::
+
:read-more{to="/docs/getting-started/transitions"}
## Layout's Ref
To get the ref of a layout component, access it through `ref.value.layoutRef`.
-````vue [app.vue]
+::code-group
+
+```vue [app.vue]
-
+ default layout
+
+
+```
+
+::
:read-more{to="/docs/guide/directory-structure/layouts"}
diff --git a/docs/3.api/1.components/4.nuxt-link.md b/docs/3.api/1.components/4.nuxt-link.md
index 5e54807145..b623d1ce5a 100644
--- a/docs/3.api/1.components/4.nuxt-link.md
+++ b/docs/3.api/1.components/4.nuxt-link.md
@@ -25,6 +25,22 @@ In this example, we use `
+ Hi there
+
+
+```
diff --git a/docs/3.api/2.composables/use-async-data.md b/docs/3.api/2.composables/use-async-data.md
index 43b2bc4e24..0885af2107 100644
--- a/docs/3.api/2.composables/use-async-data.md
+++ b/docs/3.api/2.composables/use-async-data.md
@@ -1,6 +1,6 @@
---
title: 'useAsyncData'
-description: useAsyncData provides access to data that resolves asynchronously in a SSR-friendly composable.
+description: useAsyncData provides access to data that resolves asynchronously in an SSR-friendly composable.
links:
- label: Source
icon: i-simple-icons-github
@@ -119,10 +119,10 @@ type AsyncDataOptions
-
+
```
+::note
+`useId` must be used in a component with a single root element, as it uses this root element's attributes to pass the id from server to client.
+::
+
## Parameters
`useId` does not take any parameters.
diff --git a/docs/3.api/2.composables/use-lazy-async-data.md b/docs/3.api/2.composables/use-lazy-async-data.md
index c0b6da52c2..eacd9ce39d 100644
--- a/docs/3.api/2.composables/use-lazy-async-data.md
+++ b/docs/3.api/2.composables/use-lazy-async-data.md
@@ -44,4 +44,4 @@ watch(count, (newCount) => {
`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
::
-:read-more{to="/docs/getting-started/data-fetching#uselazyasyncdata"}
+:read-more{to="/docs/getting-started/data-fetching"}
diff --git a/docs/3.api/2.composables/use-loading-indicator.md b/docs/3.api/2.composables/use-loading-indicator.md
index a451518d71..357c260bbd 100644
--- a/docs/3.api/2.composables/use-loading-indicator.md
+++ b/docs/3.api/2.composables/use-loading-indicator.md
@@ -26,6 +26,11 @@ It hooks into [`page:loading:start`](/docs/api/advanced/hooks#app-hooks-runtime)
- **type**: `Ref
+ Some base content
+
+
+```
+
+Now you can generate your site and serve it:
+
+```bash [Terminal]
+npx nuxi generate
+npx nuxi preview
+```
+
+Then you can see your preview page by adding the query param `preview` to the end of the page you want to see once:
+
+```js
+?preview=true
+```
+
+::note
+`usePreviewMode` should be tested locally with `nuxi generate` and then `nuxi preview` rather than `nuxi dev`. (The [preview command](/docs/api/commands/preview) is not related to preview mode.)
+::
diff --git a/docs/3.api/2.composables/use-request-url.md b/docs/3.api/2.composables/use-request-url.md
index a2d4a8e3c8..1ed09bb66b 100644
--- a/docs/3.api/2.composables/use-request-url.md
+++ b/docs/3.api/2.composables/use-request-url.md
@@ -10,6 +10,12 @@ links:
`useRequestURL` is a helper function that returns an [URL object](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) working on both server-side and client-side.
+::important
+When utilizing [Hybrid Rendering](/docs/guide/concepts/rendering#hybrid-rendering) with cache strategies, all incoming request headers are dropped when handling the cached responses via the [Nitro caching layer](https://nitro.unjs.io/guide/cache) (meaning `useRequestURL` will return `localhost` for the `host`).
+
+You can define the [`cache.varies` option](https://nitro.unjs.io/guide/cache#options) to specify headers that will be considered when caching and serving the responses, such as `host` and `x-forwarded-host` for multi-tenant environments.
+::
+
::code-group
```vue [pages/about.vue]
diff --git a/docs/3.api/2.composables/use-route-announcer.md b/docs/3.api/2.composables/use-route-announcer.md
new file mode 100644
index 0000000000..1111eec0a4
--- /dev/null
+++ b/docs/3.api/2.composables/use-route-announcer.md
@@ -0,0 +1,60 @@
+---
+title: 'useRouteAnnouncer'
+description: This composable observes the page title changes and updates the announcer message accordingly.
+navigation:
+ badge: New
+links:
+ - label: Source
+ icon: i-simple-icons-github
+ to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/route-announcer.ts
+ size: xs
+---
+
+::important
+This composable is available in Nuxt v3.12+.
+::
+
+## Description
+
+A composable which observes the page title changes and updates the announcer message accordingly. Used by [`
+ Only preview content: {{ state.token }}
+
+
+
${stacktrace}` : undefined
// TODO: Investigate side-effect issue with imports
-const _Error404 = defineAsyncComponent(() => import('@nuxt/ui-templates/templates/error-404.vue').then(r => r.default || r))
+const _Error404 = defineAsyncComponent(() => import('./error-404.vue').then(r => r.default || r))
const _Error = import.meta.dev
- ? defineAsyncComponent(() => import('@nuxt/ui-templates/templates/error-dev.vue').then(r => r.default || r))
- : defineAsyncComponent(() => import('@nuxt/ui-templates/templates/error-500.vue').then(r => r.default || r))
+ ? defineAsyncComponent(() => import('./error-dev.vue').then(r => r.default || r))
+ : defineAsyncComponent(() => import('./error-500.vue').then(r => r.default || r))
const ErrorTemplate = is404 ? _Error404 : _Error
diff --git a/packages/nuxt/src/app/components/nuxt-island.ts b/packages/nuxt/src/app/components/nuxt-island.ts
index 2f973c4d87..bb3a7fb840 100644
--- a/packages/nuxt/src/app/components/nuxt-island.ts
+++ b/packages/nuxt/src/app/components/nuxt-island.ts
@@ -1,4 +1,4 @@
-import type { Component } from 'vue'
+import type { Component, PropType } from 'vue'
import { Fragment, Teleport, computed, createStaticVNode, createVNode, defineComponent, getCurrentInstance, h, nextTick, onMounted, ref, toRaw, watch, withMemo } from 'vue'
import { debounce } from 'perfect-debounce'
import { hash } from 'ohash'
@@ -9,14 +9,13 @@ import { joinURL, withQuery } from 'ufo'
import type { FetchResponse } from 'ofetch'
import { join } from 'pathe'
-// eslint-disable-next-line import/no-restricted-paths
-import type { NuxtIslandResponse } from '../../core/runtime/nitro/renderer'
+import type { NuxtIslandResponse } from '../types'
import { useNuxtApp, useRuntimeConfig } from '../nuxt'
import { prerenderRoutes, useRequestEvent } from '../composables/ssr'
import { getFragmentHTML } from './utils'
// @ts-expect-error virtual file
-import { remoteComponentIslands, selectiveClient } from '#build/nuxt.config.mjs'
+import { appBaseURL, remoteComponentIslands, selectiveClient } from '#build/nuxt.config.mjs'
const pKey = '_islandPromises'
const SSR_UID_RE = /data-island-uid="([^"]*)"/
@@ -29,7 +28,7 @@ const getId = import.meta.client ? () => (id++).toString() : randomUUID
const components = import.meta.client ? new Map${v}
`, 1),
+ ]))))]
+ },
+ })
+ teleports.push(vnode)
+ }
}
}
}
return h(Fragment, teleports)
- }, _cache, 1)
+ }, _cache, 1),
]
}
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/nuxt-layout.ts b/packages/nuxt/src/app/components/nuxt-layout.ts
index 7509f2f9ff..e7af6597fc 100644
--- a/packages/nuxt/src/app/components/nuxt-layout.ts
+++ b/packages/nuxt/src/app/components/nuxt-layout.ts
@@ -2,7 +2,6 @@ import type { DefineComponent, MaybeRef, VNode } from 'vue'
import { Suspense, Transition, computed, defineComponent, h, inject, mergeProps, nextTick, onMounted, provide, ref, unref } from 'vue'
import type { RouteLocationNormalizedLoaded } from 'vue-router'
-// eslint-disable-next-line import/no-restricted-paths
import type { PageMeta } from '../../pages/runtime/composables'
import { useRoute, useRouter } from '../composables/router'
@@ -23,7 +22,7 @@ const LayoutLoader = defineComponent({
inheritAttrs: false,
props: {
name: String,
- layoutProps: Object
+ layoutProps: Object,
},
async setup (props, context) {
// This is a deliberate hack - this component must always be called with an explicit key to ensure
@@ -32,7 +31,7 @@ const LayoutLoader = defineComponent({
const LayoutComponent = await layouts[props.name]().then((r: any) => r.default || r)
return () => h(LayoutComponent, props.layoutProps, context.slots)
- }
+ },
})
export default defineComponent({
@@ -41,12 +40,12 @@ export default defineComponent({
props: {
name: {
type: [String, Boolean, Object] as unknown as () => unknown extends PageMeta['layout'] ? MaybeRef when plugins have thrown an error but we're not yet rendering the error page
+const abortRender = import.meta.server && error.value && !nuxtApp.ssrContext.error
onErrorCaptured((err, target, info) => {
nuxtApp.hooks.callHook('vue:error', err, target, info).catch(hookError => console.error('[nuxt] Error in `vue:error` hook', hookError))
if (import.meta.server || (isNuxtError(err) && (err.fatal || err.unhandled))) {
diff --git a/packages/nuxt/src/app/components/nuxt-route-announcer.ts b/packages/nuxt/src/app/components/nuxt-route-announcer.ts
new file mode 100644
index 0000000000..035e9e9e50
--- /dev/null
+++ b/packages/nuxt/src/app/components/nuxt-route-announcer.ts
@@ -0,0 +1,48 @@
+import { defineComponent, h } from 'vue'
+import type { Politeness } from '#app/composables/route-announcer'
+import { useRouteAnnouncer } from '#app/composables/route-announcer'
+
+export default defineComponent({
+ name: 'NuxtRouteAnnouncer',
+ props: {
+ atomic: {
+ type: Boolean,
+ default: false,
+ },
+ politeness: {
+ type: String as () => Politeness,
+ default: 'polite',
+ },
+ },
+ setup (props, { slots, expose }) {
+ const { set, polite, assertive, message, politeness } = useRouteAnnouncer({ politeness: props.politeness })
+
+ expose({
+ set, polite, assertive, message, politeness,
+ })
+
+ return () => h('span', {
+ class: 'nuxt-route-announcer',
+ style: {
+ position: 'absolute',
+ },
+ }, h('span', {
+ 'role': 'alert',
+ 'aria-live': politeness.value,
+ 'aria-atomic': props.atomic,
+ 'style': {
+ 'border': '0',
+ 'clip': 'rect(0 0 0 0)',
+ 'clip-path': 'inset(50%)',
+ 'height': '1px',
+ 'width': '1px',
+ 'overflow': 'hidden',
+ 'position': 'absolute',
+ 'white-space': 'nowrap',
+ 'word-wrap': 'normal',
+ 'margin': '-1px',
+ 'padding': '0',
+ },
+ }, slots.default ? slots.default({ message: message.value }) : message.value))
+ },
+})
diff --git a/packages/nuxt/src/app/components/nuxt-stubs.ts b/packages/nuxt/src/app/components/nuxt-stubs.ts
index c2adc56412..5a3d20c10d 100644
--- a/packages/nuxt/src/app/components/nuxt-stubs.ts
+++ b/packages/nuxt/src/app/components/nuxt-stubs.ts
@@ -4,14 +4,14 @@ function renderStubMessage (name: string) {
throw createError({
fatal: true,
statusCode: 500,
- statusMessage: `${name} is provided by @nuxt/image. Check your console to install it or run 'npx nuxi@latest module add @nuxt/image'`
+ statusMessage: `${name} is provided by @nuxt/image. Check your console to install it or run 'npx nuxi@latest module add @nuxt/image'`,
})
}
export const NuxtImg = {
- setup: () => renderStubMessage('')
+ setup: () => renderStubMessage(''),
}
export const NuxtPicture = {
- setup: () => renderStubMessage('')
+ setup: () => renderStubMessage(''),
}
diff --git a/packages/nuxt/src/app/components/nuxt-teleport-island-component.ts b/packages/nuxt/src/app/components/nuxt-teleport-island-component.ts
index 34a5dcca91..e459781dd2 100644
--- a/packages/nuxt/src/app/components/nuxt-teleport-island-component.ts
+++ b/packages/nuxt/src/app/components/nuxt-teleport-island-component.ts
@@ -1,14 +1,16 @@
-import type { Component } from 'vue'
-import { Teleport, defineComponent, h } from 'vue'
+import type { Component, InjectionKey } from 'vue'
+import { Teleport, defineComponent, h, inject, provide } from 'vue'
import { useNuxtApp } from '../nuxt'
// @ts-expect-error virtual file
import { paths } from '#build/components-chunk'
type ExtendedComponent = Component & {
- __file: string,
+ __file: string
__name: string
}
+export const NuxtTeleportIslandSymbol = Symbol('NuxtTeleportIslandComponent') as InjectionKey
+
/**
* component only used with componentsIsland
* this teleport the component in SSR only if it needs to be hydrated on client
@@ -19,43 +21,37 @@ export default defineComponent({
props: {
to: {
type: String,
- required: true
+ required: true,
},
nuxtClient: {
type: Boolean,
- default: false
+ default: false,
},
- /**
- * ONLY used in dev mode since we use build:manifest result in production
- * do not pass any value in production
- */
- rootDir: {
- type: String,
- default: null
- }
},
setup (props, { slots }) {
const nuxtApp = useNuxtApp()
- if (!nuxtApp.ssrContext?.islandContext || !props.nuxtClient) { return () => slots.default!() }
+ // if there's already a teleport parent, we don't need to teleport or to render the wrapped component client side
+ if (!nuxtApp.ssrContext?.islandContext || !props.nuxtClient || inject(NuxtTeleportIslandSymbol, false)) { return () => slots.default?.() }
+ provide(NuxtTeleportIslandSymbol, props.to)
const islandContext = nuxtApp.ssrContext!.islandContext!
return () => {
const slot = slots.default!()[0]
- const slotType = (slot.type as ExtendedComponent)
+ const slotType = slot.type as ExtendedComponent
const name = (slotType.__name || slotType.name) as string
islandContext.components[props.to] = {
- chunk: import.meta.dev ? '_nuxt/' + paths[name] : paths[name],
- props: slot.props || {}
+ chunk: import.meta.dev ? nuxtApp.$config.app.buildAssetsDir + paths[name] : paths[name],
+ props: slot.props || {},
}
return [h('div', {
- style: 'display: contents;',
+ 'style': 'display: contents;',
'data-island-uid': '',
- 'data-island-component': props.to
+ 'data-island-component': props.to,
}, []), h(Teleport, { to: props.to }, slot)]
}
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/nuxt-teleport-island-slot.ts b/packages/nuxt/src/app/components/nuxt-teleport-island-slot.ts
index 6001f26097..9f9fefc8b1 100644
--- a/packages/nuxt/src/app/components/nuxt-teleport-island-slot.ts
+++ b/packages/nuxt/src/app/components/nuxt-teleport-island-slot.ts
@@ -1,6 +1,8 @@
-import { Teleport, defineComponent, h } from 'vue'
+import type { VNode } from 'vue'
+import { Teleport, createVNode, defineComponent, h, inject } from 'vue'
import { useNuxtApp } from '../nuxt'
-
+import { NuxtTeleportIslandSymbol } from './nuxt-teleport-island-component'
+
/**
* component only used within islands for slot teleport
*/
@@ -9,40 +11,53 @@ export default defineComponent({
name: 'NuxtTeleportIslandSlot',
props: {
name: {
- type: String,
- required: true
+ type: String,
+ required: true,
},
/**
* must be an array to handle v-for
*/
props: {
- type: Object as () => Array
- }
+ type: Object as () => Array,
+ },
},
setup (props, { slots }) {
const nuxtApp = useNuxtApp()
const islandContext = nuxtApp.ssrContext?.islandContext
-
- if(!islandContext) {
- return () => slots.default?.()
+ if (!islandContext) {
+ return () => slots.default?.()[0]
}
+ const componentName = inject(NuxtTeleportIslandSymbol, false)
islandContext.slots[props.name] = {
- props: (props.props || []) as unknown[]
+ props: (props.props || []) as unknown[],
}
return () => {
- const vnodes = [h('div', {
- style: 'display: contents;',
- 'data-island-uid': '',
- 'data-island-slot': props.name,
- })]
+ const vnodes: VNode[] = []
+
+ if (nuxtApp.ssrContext?.islandContext && slots.default) {
+ vnodes.push(h('div', {
+ 'style': 'display: contents;',
+ 'data-island-uid': '',
+ 'data-island-slot': props.name,
+ }, {
+ // Teleport in slot to not be hydrated client-side with the staticVNode
+ default: () => [createVNode(Teleport, { to: `island-slot=${componentName};${props.name}` }, slots.default?.())],
+ }))
+ } else {
+ vnodes.push(h('div', {
+ 'style': 'display: contents;',
+ 'data-island-uid': '',
+ 'data-island-slot': props.name,
+ }))
+ }
if (slots.fallback) {
- vnodes.push(h(Teleport, { to: `island-fallback=${props.name}`}, slots.fallback()))
+ vnodes.push(h(Teleport, { to: `island-fallback=${props.name}` }, slots.fallback()))
}
return vnodes
}
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/route-provider.ts b/packages/nuxt/src/app/components/route-provider.ts
index 6f57fb82f6..de4ae64a47 100644
--- a/packages/nuxt/src/app/components/route-provider.ts
+++ b/packages/nuxt/src/app/components/route-provider.ts
@@ -7,15 +7,15 @@ export const RouteProvider = defineComponent({
props: {
vnode: {
type: Object as () => VNode,
- required: true
+ required: true,
},
route: {
type: Object as () => RouteLocationNormalizedLoaded,
- required: true
+ required: true,
},
vnodeRef: Object as () => Ref,
renderKey: String,
- trackRootNodes: Boolean
+ trackRootNodes: Boolean,
},
setup (props) {
// Prevent reactivity when the page will be rerendered in a different suspense fork
@@ -26,7 +26,7 @@ export const RouteProvider = defineComponent({
const route = {} as RouteLocation
for (const key in props.route) {
Object.defineProperty(route, key, {
- get: () => previousKey === props.renderKey ? props.route[key as keyof RouteLocationNormalizedLoaded] : previousRoute[key as keyof RouteLocationNormalizedLoaded]
+ get: () => previousKey === props.renderKey ? props.route[key as keyof RouteLocationNormalizedLoaded] : previousRoute[key as keyof RouteLocationNormalizedLoaded],
})
}
@@ -52,5 +52,5 @@ export const RouteProvider = defineComponent({
return h(props.vnode, { ref: props.vnodeRef })
}
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/server-placeholder.ts b/packages/nuxt/src/app/components/server-placeholder.ts
index eaa38e3282..accbfb9857 100644
--- a/packages/nuxt/src/app/components/server-placeholder.ts
+++ b/packages/nuxt/src/app/components/server-placeholder.ts
@@ -4,5 +4,5 @@ export default defineComponent({
name: 'ServerPlaceholder',
render () {
return createElementBlock('div')
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/test-component-wrapper.ts b/packages/nuxt/src/app/components/test-component-wrapper.ts
index fd185150cc..8b0da24381 100644
--- a/packages/nuxt/src/app/components/test-component-wrapper.ts
+++ b/packages/nuxt/src/app/components/test-component-wrapper.ts
@@ -1,4 +1,3 @@
-import { parseURL } from 'ufo'
import { defineComponent, h } from 'vue'
import { parseQuery } from 'vue-router'
import { resolve } from 'pathe'
@@ -10,18 +9,18 @@ export default (url: string) => defineComponent({
name: 'NuxtTestComponentWrapper',
async setup (props, { attrs }) {
- const query = parseQuery(parseURL(url).search)
+ const query = parseQuery(new URL(url, 'http://localhost').search)
const urlProps = query.props ? destr>(query.props as string) : {}
const path = resolve(query.path as string)
if (!path.startsWith(devRootDir)) {
throw new Error(`[nuxt] Cannot access path outside of project root directory: \`${path}\`.`)
}
- const comp = await import(/* @vite-ignore */ query.path as string).then(r => r.default)
+ const comp = await import(/* @vite-ignore */ path as string).then(r => r.default)
return () => [
- h('div', 'Component Test Wrapper for ' + query.path),
+ h('div', 'Component Test Wrapper for ' + path),
h('div', { id: 'nuxt-component-root' }, [
- h(comp, { ...attrs, ...props, ...urlProps })
- ])
+ h(comp, { ...attrs, ...props, ...urlProps }),
+ ]),
]
- }
+ },
})
diff --git a/packages/nuxt/src/app/components/utils.ts b/packages/nuxt/src/app/components/utils.ts
index 11108cb583..a5e918a89d 100644
--- a/packages/nuxt/src/app/components/utils.ts
+++ b/packages/nuxt/src/app/components/utils.ts
@@ -36,7 +36,7 @@ export function isChangingPage (to: RouteLocationNormalized, from: RouteLocation
if (generateRouteKey(to) !== generateRouteKey(from)) { return true }
const areComponentsSame = to.matched.every((comp, index) =>
- comp.components && comp.components.default === from.matched[index]?.components?.default
+ comp.components && comp.components.default === from.matched[index]?.components?.default,
)
if (areComponentsSame) {
return false
@@ -44,7 +44,6 @@ export function isChangingPage (to: RouteLocationNormalized, from: RouteLocation
return true
}
-// eslint-disable-next-line no-use-before-define
export type SSRBuffer = SSRBufferItem[] & { hasAsync?: boolean }
export type SSRBufferItem = string | SSRBuffer | Promise
@@ -71,28 +70,10 @@ export function createBuffer () {
if (isPromise(item) || (isArray(item) && item.hasAsync)) {
buffer.hasAsync = true
}
- }
+ },
}
}
-const TRANSLATE_RE = /&(nbsp|amp|quot|lt|gt);/g
-const NUMSTR_RE = /&#(\d+);/gi
-export function decodeHtmlEntities (html: string) {
- const translateDict = {
- nbsp: ' ',
- amp: '&',
- quot: '"',
- lt: '<',
- gt: '>'
- } as const
- return html.replace(TRANSLATE_RE, function (_, entity: keyof typeof translateDict) {
- return translateDict[entity]
- }).replace(NUMSTR_RE, function (_, numStr: string) {
- const num = parseInt(numStr, 10)
- return String.fromCharCode(num)
- })
-}
-
/**
* helper for NuxtIsland to generate a correct array for scoped data
*/
@@ -113,7 +94,7 @@ export function vforToArray (source: any): any[] {
} else if (isObject(source)) {
if (source[Symbol.iterator as any]) {
return Array.from(source as Iterable, item =>
- item
+ item,
)
} else {
const keys = Object.keys(source)
diff --git a/packages/nuxt/src/app/composables/asyncData.ts b/packages/nuxt/src/app/composables/asyncData.ts
index 79a7813ba9..8ca773a338 100644
--- a/packages/nuxt/src/app/composables/asyncData.ts
+++ b/packages/nuxt/src/app/composables/asyncData.ts
@@ -1,4 +1,4 @@
-import { getCurrentInstance, onBeforeMount, onServerPrefetch, onUnmounted, ref, shallowRef, toRef, unref, watch } from 'vue'
+import { computed, getCurrentInstance, getCurrentScope, onBeforeMount, onScopeDispose, onServerPrefetch, onUnmounted, ref, shallowRef, toRef, unref, watch } from 'vue'
import type { Ref, WatchSource } from 'vue'
import type { NuxtApp } from '../nuxt'
import { useNuxtApp } from '../nuxt'
@@ -8,39 +8,44 @@ import { createError } from './error'
import { onNuxtReady } from './ready'
// @ts-expect-error virtual file
-import { asyncDataDefaults } from '#build/nuxt.config.mjs'
+import { asyncDataDefaults, resetAsyncDataToUndefined } from '#build/nuxt.config.mjs'
+
+// TODO: temporary module for backwards compatibility
+import type { DedupeOption, DefaultAsyncDataErrorValue, DefaultAsyncDataValue } from '#app/defaults'
export type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
-export type _Transform = (input: Input) => Output
+export type _Transform = (input: Input) => Output | Promise