mirror of
https://github.com/nuxt/nuxt.git
synced 2024-11-22 05:35:13 +00:00
docs: replace callout to new components (#25897)
This commit is contained in:
Florent Delerue
GitHub
parent
ec5d254f41
commit
7213b2ddac
@ -6,7 +6,7 @@ navigation.icon: i-ph-cloud-duotone
|
||||
|
||||
A Nuxt application can be deployed on a Node.js server, pre-rendered for static hosting, or deployed to serverless or edge (CDN) environments.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
If you are looking for a list of cloud providers that support Nuxt 3, see the [Hosting providers](/deploy) section.
|
||||
::
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ description: How to test your Nuxt application.
|
||||
navigation.icon: i-ph-check-circle-duotone
|
||||
---
|
||||
|
||||
::callout
|
||||
::tip
|
||||
If you are a module author, you can find more specific information in the [Module Author's guide](/docs/guide/going-further/modules#testing).
|
||||
::
|
||||
|
||||
@ -53,7 +53,7 @@ We currently ship an environment for unit testing code that needs a [Nuxt](https
|
||||
|
||||
```ts twoslash
|
||||
import { defineVitestConfig } from '@nuxt/test-utils/config'
|
||||
|
||||
|
||||
export default defineVitestConfig({
|
||||
// any custom Vitest config you require
|
||||
})
|
||||
@ -68,7 +68,7 @@ You can opt in to a Nuxt environment by adding `.nuxt.` to the test file's name
|
||||
```ts twoslash
|
||||
// @vitest-environment nuxt
|
||||
import { test } from 'vitest'
|
||||
|
||||
|
||||
test('my test', () => {
|
||||
// ... test with Nuxt environment!
|
||||
})
|
||||
@ -108,12 +108,10 @@ test('my test', () => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
|
||||
::warning
|
||||
When you run your tests within the Nuxt environment, they will be running in a [`happy-dom`](https://github.com/capricorn86/happy-dom) or [`jsdom`](https://github.com/jsdom/jsdom) environment. Before your tests run, a global Nuxt app will be initialized (including, for example, running any plugins or code you've defined in your `app.vue`).
|
||||
|
||||
This means you should take particular care not to mutate the global state in your tests (or, if you need to, to reset it afterwards).
|
||||
|
||||
::
|
||||
|
||||
### 🎭 Built-In Mocks
|
||||
@ -270,7 +268,7 @@ mockNuxtImport('useStorage', () => {
|
||||
// Then, inside a test
|
||||
useStorageMock.mockImplementation(() => {
|
||||
return { value: 'something else' }
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
#### `mockComponent`
|
||||
|
||||
@ -25,7 +25,7 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/
|
||||
- **Text editor** - We recommend [Visual Studio Code](https://code.visualstudio.com/) with the [Volar Extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
|
||||
- **Terminal** - In order to run Nuxt commands
|
||||
|
||||
::callout
|
||||
::note
|
||||
::details
|
||||
:summary[Additional notes for an optimal setup:]
|
||||
- **Node.js**: Make sure to use an even numbered version (18, 20, etc)
|
||||
@ -96,7 +96,7 @@ bun install
|
||||
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you are using Yarn 2+ (Berry), add `nodeLinker: node-modules` to your `.yarnrc.yml` file.
|
||||
[You can follow this issue status here](https://github.com/nuxt/nuxt/issues/22861)
|
||||
::
|
||||
@ -124,7 +124,7 @@ bun run dev -o
|
||||
```
|
||||
::
|
||||
|
||||
::callout{icon="i-ph-check-circle-duotone"}
|
||||
::tip{icon="i-ph-check-circle-duotone"}
|
||||
Well done! A browser window should automatically open for <http://localhost:3000>.
|
||||
::
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@ This file will often be mentioned in the documentation, for example to add custo
|
||||
Every option is described in the **Configuration Reference**.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
You don't have to use TypeScript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration.
|
||||
::
|
||||
|
||||
@ -46,7 +46,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you're authoring layers, you can also use the `$meta` key to provide metadata that you or the consumers of your layer might use.
|
||||
::
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ By default, Nuxt will treat this file as the **entrypoint** and render its conte
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
If you are familiar with Vue, you might wonder where `main.js` is (the file that normally creates a Vue app). Nuxt does this behind the scene.
|
||||
::
|
||||
|
||||
@ -90,7 +90,7 @@ To use pages, create `pages/index.vue` file and add `<NuxtPage />` component to
|
||||
|
||||
Layouts are wrappers around pages that contain a common User Interface for several pages, such as a header and footer display. Layouts are Vue files using `<slot />` components to display the **page** content. The `layouts/default.vue` file will be used by default. Custom layouts can be set as part of your page metadata.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you only have a single layout in your application, we recommend using [`app.vue`](/docs/guide/directory-structure/app) with [`<NuxtPage />`](/docs/api/components/nuxt-page) instead.
|
||||
::
|
||||
|
||||
@ -131,7 +131,7 @@ If you want to create more layouts and learn how to use them in your pages, find
|
||||
|
||||
## Advanced: Extending the HTML template
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you only need to modify the `<head>`, you can refer to the [SEO and meta section](/docs/getting-started/seo-meta).
|
||||
::
|
||||
|
||||
@ -140,7 +140,7 @@ The callback function of the `render:html` hook allows you to mutate the HTML be
|
||||
|
||||
```ts twoslash [server/plugins/extend-html.ts]
|
||||
export default defineNitroPlugin((nitroApp) => {
|
||||
nitroApp.hooks.hook('render:html', (html, { event }) => {
|
||||
nitroApp.hooks.hook('render:html', (html, { event }) => {
|
||||
// This will be an object representation of the html template.
|
||||
console.log(html)
|
||||
html.head.push(`<meta name="description" content="My custom description" />`)
|
||||
|
||||
@ -43,7 +43,7 @@ For example, referencing an image file that will be processed if a build tool is
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Nuxt won't serve files in the [`assets/`](/docs/guide/directory-structure/assets) directory at a static URL like `/assets/my-file.png`. If you need a static URL, use the [`public/`](#public-directory) directory.
|
||||
::
|
||||
|
||||
|
||||
@ -30,7 +30,7 @@ import('~/assets/css/first.css')
|
||||
</style>
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
The stylesheets will be inlined in the HTML rendered by Nuxt.
|
||||
::
|
||||
|
||||
@ -45,7 +45,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
The stylesheets will be inlined in the HTML rendered by Nuxt, injected globally and present in all pages.
|
||||
::
|
||||
|
||||
@ -183,7 +183,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
In both cases, the compiled stylesheets will be inlined in the HTML rendered by Nuxt.
|
||||
::
|
||||
|
||||
@ -286,7 +286,7 @@ const classObject = computed(() => ({
|
||||
```
|
||||
|
||||
```vue [Array]
|
||||
<script setup lang="ts">
|
||||
<script setup lang="ts">
|
||||
const isActive = ref(true)
|
||||
const errorClass = ref('text-danger')
|
||||
</script>
|
||||
@ -489,7 +489,7 @@ Nuxt comes with the same `<Transition>` element that Vue has, and also has suppo
|
||||
|
||||
We would recommend using [Fontaine](https://github.com/nuxt-modules/fontaine) to reduce your [CLS](https://web.dev/cls). If you need something more advanced, consider creating a Nuxt module to extend the build process or the Nuxt runtime.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Always remember to take advantage of the various tools and techniques available in the Web ecosystem at large to make styling your application easier and more efficient. Whether you're using native CSS, a preprocessor, postcss, a UI library or a module, Nuxt has got you covered. Happy styling!
|
||||
::
|
||||
|
||||
|
||||
@ -86,7 +86,7 @@ console.log(route.params.id)
|
||||
|
||||
Nuxt provides a customizable route middleware framework you can use throughout your application, ideal for extracting code that you want to run before navigating to a particular route.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Route middleware runs within the Vue part of your Nuxt app. Despite the similar name, they are completely different from server middleware, which are run in the Nitro server part of your app.
|
||||
::
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ export default defineNuxtConfig({
|
||||
|
||||
Providing an [`app.head`](/docs/api/nuxt-config#head) property in your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config) allows you to customize the head for your entire app.
|
||||
|
||||
::callout
|
||||
::important
|
||||
This method does not allow you to provide reactive data. We recommend to use `useHead()` in `app.vue`.
|
||||
::
|
||||
|
||||
@ -143,7 +143,7 @@ It's recommended to use getters (`() => value`) over computed (`computed(() => v
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
|
||||
```vue twoslash [useSeoMeta]
|
||||
<script setup lang="ts">
|
||||
const description = ref('My amazing site.')
|
||||
@ -158,7 +158,7 @@ It's recommended to use getters (`() => value`) over computed (`computed(() => v
|
||||
<script setup lang="ts">
|
||||
const description = ref('My amazing site.')
|
||||
</script>
|
||||
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<Meta name="description" :content="description" />
|
||||
|
||||
@ -4,7 +4,7 @@ description: Apply transitions between pages and layouts with Vue or native brow
|
||||
navigation.icon: i-ph-exclude-square-duotone
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
Nuxt leverages Vue's [`<Transition>`](https://vuejs.org/guide/built-ins/transition.html#the-transition-component) component to apply transitions between pages and layouts.
|
||||
::
|
||||
|
||||
@ -20,7 +20,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you are changing layouts as well as page, the page transition you set here will not run. Instead, you should set a [layout transition](/docs/getting-started/transitions#layout-transitions).
|
||||
::
|
||||
|
||||
@ -246,7 +246,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::warning
|
||||
If you change the `name` property, you also have to rename the CSS classes accordingly.
|
||||
::
|
||||
|
||||
@ -309,7 +309,7 @@ definePageMeta({
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Learn more about additional [JavaScript hooks](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks) available in the `Transition` component.
|
||||
::
|
||||
|
||||
@ -407,7 +407,7 @@ When `<NuxtPage />` is used in `app.vue`, transition-props can be passed directl
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Remember, this page transition cannot be overridden with `definePageMeta` on individual pages.
|
||||
::
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ The [`useFetch`](/docs/api/composables/use-fetch) and [`useAsyncData`](/docs/api
|
||||
|
||||
The payload is a JavaScript object accessible through [`useNuxtApp().payload`](/docs/api/composables/use-nuxt-app#payload). It is used on the client to avoid refetching the same data when the code is executed in the browser [during hydration](/docs/guide/concepts/rendering#universal-rendering).
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::tip
|
||||
Use the [Nuxt DevTools](https://devtools.nuxt.com) to inspect this data in the **Payload tab**.
|
||||
::
|
||||
|
||||
@ -34,7 +34,7 @@ Use the [Nuxt DevTools](https://devtools.nuxt.com) to inspect this data in the *
|
||||
|
||||
Nuxt uses Vue’s [`<Suspense>`](https://vuejs.org/guide/built-ins/suspense) component under the hood to prevent navigation before every async data is available to the view. The data fetching composables can help you leverage this feature and use what suits best on a per-calls basis.
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
You can add the [`<NuxtLoadingIndicator>`](/docs/api/components/nuxt-loading-indicator) to add a progress bar between page navigations.
|
||||
::
|
||||
|
||||
@ -75,7 +75,7 @@ async function addTodo() {
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Beware that using only `$fetch` will not provide [network calls de-duplication and navigation prevention](#why-using-specific-composables). :br
|
||||
It is recommended to use `$fetch` for client-side interactions (event based) or combined with [`useAsyncData`](#useasyncdata) when fetching the initial component data.
|
||||
::
|
||||
@ -88,7 +88,7 @@ Read more about `$fetch`.
|
||||
|
||||
The `useAsyncData` composable is responsible for wrapping async logic and returning the result once it is resolved.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
`useFetch(url)` is nearly equivalent to `useAsyncData(url, () => $fetch(url))`. :br
|
||||
It's developer experience sugar for the most common use case.
|
||||
::
|
||||
@ -104,7 +104,7 @@ const { data, error } = await useAsyncData(() => myGetFunction('users'))
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
The first argument of [`useAsyncData`](/docs/api/composables/use-async-data) is a unique key used to cache the response of the second argument, the querying function. This key can be ignored by directly passing the querying function, the key will be auto-generated.
|
||||
:br :br
|
||||
Since the autogenerated key only takes into account the file and line where `useAsyncData` is invoked, it is recommended to always create your own key to avoid unwanted behavior, like when you are creating your own custom composable wrapping `useAsyncData`.
|
||||
@ -153,13 +153,13 @@ Read more about `useAsyncData`.
|
||||
- `error`: an error object if the data fetching failed.
|
||||
- `status`: a string indicating the status of the data request (`"idle"`, `"pending"`, `"success"`, `"error"`).
|
||||
|
||||
::callout
|
||||
::note
|
||||
`data`, `pending`, `error` and `status` are Vue refs accessible with `.value` in `<script setup>`
|
||||
::
|
||||
|
||||
By default, Nuxt waits until a `refresh` is finished before it can be executed again.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.
|
||||
::
|
||||
|
||||
@ -247,14 +247,14 @@ const { data: mountain } = await useFetch('/api/mountains/everest', {
|
||||
If you need more control or map over several objects, you can use the `transform` function to alter the result of the query.
|
||||
|
||||
```ts
|
||||
const { data: mountains } = await useFetch('/api/mountains', {
|
||||
const { data: mountains } = await useFetch('/api/mountains', {
|
||||
transform: (mountains) => {
|
||||
return mountains.map(mountain => ({ title: mountain.title, description: mountain.description }))
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Both `pick` and `transform` don't prevent the unwanted data from being fetched initially. But they will prevent unwanted data from being added to the payload transferred from server to client.
|
||||
::
|
||||
|
||||
@ -267,7 +267,7 @@ Both `pick` and `transform` don't prevent the unwanted data from being fetched i
|
||||
- [`useFetch`](/docs/api/composables/use-fetch) uses the provided URL as a key. Alternatively, a `key` value can be provided in the `options` object passed as a last argument.
|
||||
- [`useAsyncData`](/docs/api/composables/use-async-data) uses its first argument as a key if it is a string. If the first argument is the handler function that performs the query, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
To get the cached data by key, you can use [`useNuxtData`](/docs/api/composables/use-nuxt-data)
|
||||
::
|
||||
|
||||
@ -290,7 +290,7 @@ const { data, error, execute, refresh } = await useFetch('/api/users')
|
||||
|
||||
The `execute` function is an alias for `refresh` that works in exactly the same way but is more semantic for cases when the fetch is [not immediate](#not-immediate).
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::tip
|
||||
To globally refetch or invalidate cached data, see [`clearNuxtData`](/docs/api/utils/clear-nuxt-data) and [`refreshNuxtData`](/docs/api/utils/refresh-nuxt-data).
|
||||
::
|
||||
|
||||
@ -360,7 +360,7 @@ const { data, pending, status } = useLazyFetch(() => `/api/users/${id.value}`, {
|
||||
<div v-if="status === 'idle'">
|
||||
Type an user ID
|
||||
</div>
|
||||
|
||||
|
||||
<div v-else-if="pending">
|
||||
Loading ...
|
||||
</div>
|
||||
@ -427,7 +427,7 @@ const { data } = await useFetch('/api/me', { headers })
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::caution
|
||||
Be very careful before proxying headers to an external API and just include headers that you need. Not all headers are safe to be bypassed and might introduce unwanted behavior. Here is a list of common headers that are NOT to be proxied:
|
||||
|
||||
- `host`, `accept`
|
||||
@ -486,7 +486,7 @@ export default defineNuxtComponent({
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
Using `<script setup>` or `<script setup lang="ts">` are the recommended way of declaring Vue components in Nuxt 3.
|
||||
::
|
||||
|
||||
@ -498,7 +498,7 @@ When using `useAsyncData` and `useLazyAsyncData` to transfer data fetched on ser
|
||||
|
||||
It is also possible to define your own serializer/deserializer for types that are not supported by Nuxt. You can read more in the [`useNuxtApp`](/docs/api/composables/use-nuxt-app#payload) docs.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Note that this _does not apply_ to data passed from your server routes when fetched with `$fetch` or `useFetch` - see the next section for more information.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ 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.
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
|
||||
@ -18,12 +18,12 @@ Read more about `useState` composable.
|
||||
|
||||
## Best Practices
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Never define `const state = ref()` outside of `<script setup>` or `setup()` function.<br>
|
||||
Such state will be shared across all users visiting your website and can lead to memory leaks!
|
||||
::
|
||||
|
||||
::callout{color="green" icon="i-ph-check-circle-duotone"}
|
||||
::tip{icon="i-ph-check-circle-duotone"}
|
||||
Instead use `const useX = () => useState('x')`
|
||||
::
|
||||
|
||||
@ -53,7 +53,7 @@ const counter = useState('counter', () => Math.round(Math.random() * 1000))
|
||||
|
||||
:link-example{to="/docs/examples/features/state-management"}
|
||||
|
||||
::callout
|
||||
::note
|
||||
To globally invalidate cached state, see [`clearNuxtState`](/docs/api/utils/clear-nuxt-state) util.
|
||||
::
|
||||
|
||||
@ -71,7 +71,7 @@ await callOnce(async () => {
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
This is similar to the [`nuxtServerInit` action](https://v2.nuxt.com/docs/directory-structure/store/#the-nuxtserverinit-action) in Nuxt 2, which allows filling the initial state of your store server-side before rendering the page.
|
||||
::
|
||||
|
||||
@ -81,7 +81,7 @@ This is similar to the [`nuxtServerInit` action](https://v2.nuxt.com/docs/direct
|
||||
|
||||
In this example, we leverage the [Pinia module](/modules/pinia) to create a global store and use it across the app.
|
||||
|
||||
::callout
|
||||
::important
|
||||
Make sure to install the Pinia module with `npx nuxi@latest module add pinia` or follow the [module's installation steps](https://pinia.vuejs.org/ssr/nuxt.html#Installation).
|
||||
::
|
||||
|
||||
@ -130,7 +130,7 @@ export const useLocale = () => {
|
||||
|
||||
export const useDefaultLocale = (fallback = 'en-US') => {
|
||||
const locale = ref(fallback)
|
||||
if (process.server) {
|
||||
if (process.server) {
|
||||
const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
|
||||
if (reqLocale) {
|
||||
locale.value = reqLocale
|
||||
@ -173,7 +173,7 @@ const date = useLocaleDate(new Date('2016-10-26'))
|
||||
<template>
|
||||
<div>
|
||||
<h1>Nuxt birthday</h1>
|
||||
<p>{{ date }}</p>
|
||||
<p>{{ date }}</p>
|
||||
<label for="locale-chooser">Preview a different locale</label>
|
||||
<select id="locale-chooser" v-model="locale">
|
||||
<option v-for="locale of locales" :key="locale" :value="locale">
|
||||
|
||||
@ -11,7 +11,7 @@ Nuxt 3 is a full-stack framework, which means there are several sources of unpre
|
||||
- Server and client startup errors (SSR + CSR)
|
||||
- Errors downloading JS chunks
|
||||
|
||||
::callout
|
||||
::tip
|
||||
**SSR** stands for **Server-Side Rendering** and **CSR** for **Client-Side Rendering**.
|
||||
::
|
||||
|
||||
@ -36,7 +36,7 @@ export default defineNuxtPlugin((nuxtApp) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Note that the `vue:error` hook is based on [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured) lifecycle hook.
|
||||
::
|
||||
|
||||
@ -63,7 +63,7 @@ You can change this behavior by setting `experimental.emitRouteChunkError` to `f
|
||||
|
||||
## Error Page
|
||||
|
||||
::callout
|
||||
::note
|
||||
When Nuxt encounters a fatal error (any unhandled error on the server, or an error created with `fatal: true` on the client) it will either render a JSON response (if requested with `Accept: application/json` header) or trigger a full-screen error page.
|
||||
::
|
||||
|
||||
@ -121,11 +121,11 @@ export default defineNuxtPlugin(nuxtApp => {
|
||||
|
||||
When you are ready to remove the error page, you can call the [`clearError`](/docs/api/utils/clear-error) helper function, which takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).
|
||||
|
||||
::callout
|
||||
::important
|
||||
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.
|
||||
::
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
|
||||
@ -207,7 +207,7 @@ This component is responsible for handling errors that occur within its default
|
||||
|
||||
The `#error` slot will receive `error` as a prop. (If you set `error = null` it will trigger re-rendering the default slot; you'll need to ensure that the error is fully resolved first or the error slot will just be rendered a second time.)
|
||||
|
||||
::callout
|
||||
::tip
|
||||
If you navigate to another route, the error will be cleared automatically.
|
||||
::
|
||||
|
||||
|
||||
@ -33,7 +33,7 @@ export default defineNuxtConfig({
|
||||
Read more about layers in the **Layer Author Guide**.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=lnFCM7c9f7I" target="_blank"}
|
||||
::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=lnFCM7c9f7I" target="_blank"}
|
||||
Watch Learn Vue video about Nuxt Layers.
|
||||
::
|
||||
|
||||
|
||||
@ -15,15 +15,15 @@ Thanks to its opinionated directory structure, Nuxt can auto-import your [`compo
|
||||
|
||||
Contrary to a classic global declaration, Nuxt preserves typings, IDEs completions and hints, and **only includes what is used in your production code**.
|
||||
|
||||
::callout{color="blue" icon="i-ph-lightbulb-duotone"}
|
||||
::note
|
||||
In the docs, every function that is not explicitly imported is auto-imported by Nuxt and can be used as-is in your code. You can find a reference for auto-imported components, composables and utilities in the [API section](/docs/api).
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
In the [`server`](/docs/guide/directory-structure/server) directory, Nuxt auto-imports exported functions and variables from `server/utils/`.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
You can also auto-import functions exported from custom folders or third-party packages by configuring the [`imports`](/docs/api/nuxt-config#imports) section of your `nuxt.config` file.
|
||||
::
|
||||
|
||||
@ -150,7 +150,7 @@ export default defineNuxtConfig({
|
||||
|
||||
Nuxt also allows auto-importing from third-party packages.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
If you are using the Nuxt module for that package, it is likely that the module has already configured auto-imports for that package.
|
||||
::
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ description: "Nuxt uses Vue.js and adds features such as component auto-imports,
|
||||
|
||||
Nuxt integrates Vue 3, the new major release of Vue that enables new patterns for Nuxt users.
|
||||
|
||||
::callout
|
||||
::note
|
||||
While an in-depth knowledge of Vue is not required to use Nuxt, we recommend that you read the documentation and go through some of the examples on [vuejs.org](https://vuejs.org).
|
||||
::
|
||||
|
||||
|
||||
@ -31,11 +31,11 @@ Universal rendering allows a Nuxt application to provide quick page load times w
|
||||
|
||||
Universal rendering is very versatile and can fit almost any use case, and is especially appropriate for any content-oriented websites: **blogs, marketing websites, portfolios, e-commerce sites, and marketplaces.**
|
||||
|
||||
::callout
|
||||
::tip
|
||||
For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch).
|
||||
::
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::important
|
||||
When importing a library that relies on browser APIs and has side effects, make sure the component importing it is only called client-side. Bundlers do not treeshake imports of modules containing side effects.
|
||||
::
|
||||
|
||||
@ -64,7 +64,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you do use `ssr: false`, you should also place an HTML file in `~/app/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.
|
||||
:read-more{title="SPA Loading Template" to="/docs/api/configuration/nuxt-config#spaloadingtemplate"}
|
||||
::
|
||||
@ -116,7 +116,7 @@ The different properties you can use are the following:
|
||||
|
||||
Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::important
|
||||
Note that Hybrid Rendering is not available when using [`nuxt generate`](/docs/api/commands/generate).
|
||||
::
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Nuxt modules are now build-time-only, and the `buildModules` property used in Nuxt 2 is deprecated in favor of `modules`.
|
||||
::
|
||||
|
||||
|
||||
@ -61,11 +61,11 @@ This file contains the recommended basic TypeScript configuration for your proje
|
||||
|
||||
[Read more about how to extend this configuration](/docs/guide/directory-structure/tsconfig).
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
Keep in mind that all options extended from `./.nuxt/tsconfig.json` will be overwritten by the options defined in your `tsconfig.json`.
|
||||
Overwriting options such as `"compilerOptions.paths"` with your own configuration will lead TypeScript to not factor in the module resolutions from `./.nuxt/tsconfig.json`. This can lead to module resolutions such as `#imports` not being recognized.
|
||||
:br :br
|
||||
|
||||
@ -5,7 +5,7 @@ head.title: ".nuxt/"
|
||||
navigation.icon: i-ph-folder-duotone
|
||||
---
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::important
|
||||
This directory should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing the dev build output to your repository.
|
||||
::
|
||||
|
||||
@ -15,6 +15,6 @@ Nuxt also provides a Virtual File System (VFS) for modules to add templates to t
|
||||
|
||||
You can explore the generated files by opening the [Nuxt DevTools](https://devtools.nuxt.com) in development mode and navigating to the **Virtual Files** tab.
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::warning
|
||||
You should not touch any files inside since the whole directory will be re-created when running [`nuxt dev`](/docs/api/commands/dev).
|
||||
::
|
||||
|
||||
@ -5,7 +5,7 @@ head.title: ".output/"
|
||||
navigation.icon: i-ph-folder-duotone
|
||||
---
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::important
|
||||
This directory should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing the build output to your repository.
|
||||
::
|
||||
|
||||
@ -13,6 +13,6 @@ Use this directory to deploy your Nuxt application to production.
|
||||
|
||||
:read-more{to="/docs/getting-started/deployment"}
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::warning
|
||||
You should not touch any files inside since the whole directory will be re-created when running [`nuxt build`](/docs/api/commands/build).
|
||||
::
|
||||
|
||||
@ -40,7 +40,7 @@ If you have a component in nested directories such as:
|
||||
<BaseFooButton />
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
For clarity, we recommend that the component's filename matches its name. So, in the example above, you could rename `Button.vue` to be `BaseFooButton.vue`.
|
||||
::
|
||||
|
||||
@ -78,7 +78,7 @@ const MyButton = resolveComponent('MyButton')
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::important
|
||||
If you are using `resolveComponent` to handle dynamic components, make sure not to insert anything but the name of the component, which must be a string and not a variable.
|
||||
::
|
||||
|
||||
@ -95,7 +95,7 @@ Alternatively, though not recommended, you can register all your components glob
|
||||
|
||||
You can also selectively register some components globally by placing them in a `~/components/global` directory, or by using a `.global.vue` suffix in the filename. As noted above, each global component is rendered in a separate chunk, so be careful not to overuse this feature.
|
||||
|
||||
::callout
|
||||
::note
|
||||
The `global` option can also be set per component directory.
|
||||
::
|
||||
|
||||
@ -198,7 +198,7 @@ export default defineNuxtModule({
|
||||
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
Any nested directories need to be added first as they are scanned in order.
|
||||
::
|
||||
|
||||
@ -236,11 +236,11 @@ If a component is meant to be rendered only client-side, you can add the `.clien
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
This feature only works with Nuxt auto-imports and `#components` imports. Explicitly importing these components from their real paths does not convert them into client-only components.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
`.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.
|
||||
::
|
||||
|
||||
@ -250,11 +250,11 @@ Server components allow server-rendering individual components within your clien
|
||||
|
||||
Server components can either be used on their own or paired with a [client component](#paired-with-a-client-component).
|
||||
|
||||
::callout{color="blue" icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=u1yyXe86xJM" target="_blank"}
|
||||
::tip{icon="i-ph-video-duotone" to="https://www.youtube.com/watch?v=u1yyXe86xJM" target="_blank"}
|
||||
Watch Learn Vue video about Nuxt Server Components.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-article-duotone" to="https://roe.dev/blog/nuxt-server-components" target="_blank"}
|
||||
::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
|
||||
::
|
||||
|
||||
@ -330,7 +330,7 @@ This means:
|
||||
|
||||
Within an island component, you can access its island context through `nuxtApp.ssrContext.islandContext`. Note that while island components are still marked as experimental, the format of this context may change.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Slots can be interactive and are wrapped within a `<div>` with `display: contents;`
|
||||
::
|
||||
|
||||
@ -390,7 +390,7 @@ Use a slot as fallback until `<ClientOnly>` is mounted on client side.
|
||||
|
||||
<!-- TODO: Add back after passing treeshakeClientOnly experiment -->
|
||||
<!--
|
||||
::callout
|
||||
::note
|
||||
Make sure not to _nest_ `<ClientOnly>` components or other client-only components. Nuxt performs an optimization to remove the contents of these components from the server-side render, which can break in this case.
|
||||
::
|
||||
-->
|
||||
|
||||
@ -52,7 +52,7 @@ Under the hood, Nuxt auto generates the file `.nuxt/imports.d.ts` to declare the
|
||||
|
||||
Be aware that you have to run [`nuxi prepare`](/docs/api/commands/prepare), [`nuxi dev`](/docs/api/commands/dev) or [`nuxi build`](/docs/api/commands/build) in order to let Nuxt generate the types.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you create a composable without having the dev server running, TypeScript will throw an error, such as `Cannot find name 'useBar'.`
|
||||
::
|
||||
|
||||
|
||||
@ -49,6 +49,6 @@ To render content pages, add a [catch-all route](/docs/guide/directory-structure
|
||||
|
||||
## Documentation
|
||||
|
||||
::callout
|
||||
::tip{ icon="i-ph-book" }
|
||||
Head over to <https://content.nuxt.com> to learn more about the Content module features, such as how to build queries and use Vue components in your Markdown files with the MDC syntax.
|
||||
::
|
||||
|
||||
@ -5,7 +5,7 @@ description: "Nuxt provides a layouts framework to extract common UI patterns in
|
||||
navigation.icon: i-ph-folder-duotone
|
||||
---
|
||||
|
||||
::callout{icon="i-ph-rocket-launch-duotone"}
|
||||
::tip{icon="i-ph-rocket-launch-duotone" color="gray" }
|
||||
For best performance, components placed in this directory will be automatically loaded via asynchronous import when used.
|
||||
::
|
||||
|
||||
@ -25,19 +25,19 @@ To use a layout:
|
||||
- Set a `layout` property in your page with [definePageMeta](/docs/api/utils/define-page-meta).
|
||||
- Set the `name` prop of `<NuxtLayout>`.
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
The layout name is normalized to kebab-case, so `someLayout` becomes `some-layout`.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
If no layout is specified, `layouts/default.vue` will be used.
|
||||
::
|
||||
|
||||
::callout{icon="i-ph-lightbulb-duotone"}
|
||||
::important
|
||||
If you only have a single layout in your application, we recommend using [`app.vue`](/docs/guide/directory-structure/app) instead.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
Unlike other components, your layouts must have a single root element to allow Nuxt to apply transitions between layout changes - and this root element cannot be a `<slot />`.
|
||||
::
|
||||
|
||||
@ -175,6 +175,6 @@ definePageMeta({
|
||||
|
||||
::
|
||||
|
||||
::callout
|
||||
::important
|
||||
If you use `<NuxtLayout>` within your pages, make sure it is not the root element (or [disable layout/page transitions](/docs/getting-started/transitions#disable-transitions)).
|
||||
::
|
||||
|
||||
@ -15,11 +15,11 @@ There are three kinds of route middleware:
|
||||
|
||||
The first two kinds of route middleware can be defined in [`definePageMeta`](/docs/api/utils/define-page-meta).
|
||||
|
||||
::callout
|
||||
::note
|
||||
Name of middleware are normalized to kebab-case: `myMiddleware` becomes `my-middleware`.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
Route middleware run within the Vue part of your Nuxt app. Despite the similar name, they are completely different from [server middleware](/docs/guide/directory-structure/server#server-middleware), which are run in the Nitro server part of your app.
|
||||
::
|
||||
|
||||
@ -59,7 +59,7 @@ Possible return values are:
|
||||
:read-more{to="/docs/api/utils/navigate-to"}
|
||||
:read-more{to="/docs/api/utils/abort-navigation"}
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) may work but there may be breaking changes in future.
|
||||
::
|
||||
|
||||
@ -112,7 +112,7 @@ middleware/
|
||||
--| auth.ts
|
||||
```
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
In case you're new to 'alphabetical' numbering, remember that filenames are sorted as strings, not as numeric values. For example, `10.new.global.ts` would come before `2.new.global.ts`. This is why the example prefixes single digit numbers with `0`.
|
||||
::
|
||||
|
||||
|
||||
@ -7,6 +7,6 @@ navigation.icon: i-ph-folder-duotone
|
||||
|
||||
The package manager ([`npm`](https://docs.npmjs.com/cli/commands/npm) or [`yarn`](https://yarnpkg.com) or [`pnpm`](https://pnpm.io/cli/install) or [`bun`](https://bun.sh/package-manager)) creates this directory to store the dependencies of your project.
|
||||
|
||||
::callout
|
||||
::important
|
||||
This directory should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.
|
||||
::
|
||||
|
||||
@ -5,7 +5,7 @@ head.title: "pages/"
|
||||
navigation.icon: i-ph-folder-duotone
|
||||
---
|
||||
|
||||
::callout
|
||||
::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).
|
||||
::
|
||||
|
||||
@ -130,7 +130,7 @@ if (route.params.group === 'admins' && !route.params.id) {
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Named parent routes will take priority over nested dynamic routes. For the `/foo/hello` route, `~/pages/foo.vue` will take priority over `~/pages/foo/[slug].vue`. :br Use `~/pages/foo/index.vue` and `~/pages/foo/[slug].vue` to match `/foo` and `/foo/hello` with different pages,.
|
||||
::
|
||||
|
||||
@ -336,7 +336,7 @@ Learn more about `<NuxtLink>` usage.
|
||||
|
||||
Nuxt 3 allows programmatic navigation through the `navigateTo()` utility method. Using this utility method, you will be able to programmatically navigate the user in your app. This is great for taking input from the user and navigating them dynamically throughout your application. In this example, we have a simple method called `navigate()` that gets called when the user submits a search form.
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
Ensure to always `await` on `navigateTo` or chain its result by returning from functions.
|
||||
::
|
||||
|
||||
|
||||
@ -7,11 +7,11 @@ navigation.icon: i-ph-folder-duotone
|
||||
|
||||
Nuxt automatically reads the files in the `plugins/` directory and loads them at the creation of the Vue application.
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
All plugins inside are auto-registered, you don't need not add them to your `nuxt.config` separately.
|
||||
::
|
||||
|
||||
::callout{color="yellow" icon="i-ph-lightbulb-duotone"}
|
||||
::note
|
||||
You can use `.server` or `.client` suffix in the file name to load a plugin only on the server or client side.
|
||||
::
|
||||
|
||||
@ -76,7 +76,7 @@ export default defineNuxtPlugin({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
@ -95,7 +95,7 @@ In this example, `02.myOtherPlugin.ts` will be able to access anything that was
|
||||
|
||||
This is useful in situations where you have a plugin that depends on another plugin.
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
In case you're new to 'alphabetical' numbering, remember that filenames are sorted as strings, not as numeric values. For example, `10.myPlugin.ts` would come before `2.myOtherPlugin.ts`. This is why the example prefixes single digit numbers with `0`.
|
||||
::
|
||||
|
||||
@ -141,13 +141,13 @@ export default defineNuxtPlugin((nuxtApp) => {
|
||||
|
||||
However, keep in mind there are some limitations and differences:
|
||||
|
||||
::callout
|
||||
::important
|
||||
**If a composable depends on another plugin registered later, it might not work.** :br
|
||||
|
||||
Plugins are called in order sequentially and before everything else. You might use a composable that depends on another plugin which has not been called yet.
|
||||
::
|
||||
|
||||
::callout
|
||||
::important
|
||||
**If a composable depends on the Vue.js lifecycle, it won't work.** :br
|
||||
|
||||
Normally, Vue.js composables are bound to the current component instance while plugins are only bound to [`nuxtApp`](/docs/api/composables/use-nuxt-app) instance.
|
||||
@ -196,11 +196,11 @@ const { $hello } = useNuxtApp()
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
Note that we highly recommend using [`composables`](/docs/guide/directory-structure/composables) instead of providing helpers to avoid polluting the global namespace and keep your main bundle entry small.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
**If your plugin provides a `ref` or `computed`, it will not be unwrapped in a component `<template>`.** :br
|
||||
This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#caveat-when-unwrapping-in-templates).
|
||||
::
|
||||
@ -209,7 +209,7 @@ This is due to how Vue works with refs that aren't top-level to the template. Yo
|
||||
|
||||
If you return your helpers from the plugin, they will be typed automatically; you'll find them typed for the return of `useNuxtApp()` and within your templates.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you need to use a provided helper _within_ another plugin, you can call [`useNuxtApp()`](/docs/api/composables/use-nuxt-app) to get the typed version. But in general, this should be avoided unless you are certain of the plugins' order.
|
||||
::
|
||||
|
||||
@ -231,7 +231,7 @@ declare module 'vue' {
|
||||
export {}
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you are using WebStorm, you may need to augment `@vue/runtime-core` until [this issue](https://youtrack.jetbrains.com/issue/WEB-59818/VUE-TypeScript-WS-PS-does-not-correctly-display-type-of-globally-injected-properties) is resolved.
|
||||
::
|
||||
|
||||
@ -289,7 +289,7 @@ export default defineNuxtPlugin((nuxtApp) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
If you register a Vue directive, you _must_ register it on both client and server side unless you are only using it when rendering one side. If the directive only makes sense from a client side, you can always move it to `~/plugins/my-directive.client.ts` and provide a 'stub' directive for the server in `~/plugins/my-directive.server.ts`.
|
||||
::
|
||||
|
||||
|
||||
@ -22,6 +22,6 @@ useSeoMeta({
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{to="https://v2.nuxt.com/docs/directory-structure/static" target="_blank"}
|
||||
::tip{to="https://v2.nuxt.com/docs/directory-structure/static" target="_blank"}
|
||||
This is known as the [`static/`] directory in Nuxt 2.
|
||||
::
|
||||
|
||||
@ -55,7 +55,7 @@ export default defineEventHandler(() => 'Hello World!')
|
||||
|
||||
Given the example above, the `/hello` route will be accessible at <http://localhost:3000/hello>.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/guide/directory-structure/pages#dynamic-routes) do.
|
||||
::
|
||||
|
||||
@ -65,7 +65,7 @@ Nuxt will automatically read in any file in the `~/server/middleware` to create
|
||||
|
||||
Middleware handlers will run on every request before any other server route to add or check headers, log requests, or extend the event's request object.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Middleware handlers should not return anything (nor close or respond to the request) and only inspect or extend the request context or throw an error.
|
||||
::
|
||||
|
||||
@ -130,7 +130,7 @@ export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
|
||||
|
||||
## Server Types
|
||||
|
||||
::callout
|
||||
::tip
|
||||
This feature is available from Nuxt >= 3.5
|
||||
::
|
||||
|
||||
@ -158,7 +158,7 @@ export default defineEventHandler((event) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-ph-lightbulb" color="green"}
|
||||
::tip
|
||||
Alternatively, use `getValidatedRouterParams` with a schema validator such as Zod for runtime and type safety.
|
||||
::
|
||||
|
||||
@ -234,7 +234,7 @@ export default defineEventHandler(async (event) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-ph-lightbulb" color="green" to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
|
||||
::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
|
||||
Alternatively, use `readValidatedBody` with a schema validator such as Zod for runtime and type safety.
|
||||
::
|
||||
|
||||
@ -251,7 +251,7 @@ async function submit() {
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
We are using `submit.post.ts` in the filename only to match requests with `POST` method that can accept the request body. When using `readBody` within a GET request, `readBody` will throw a `405 Method Not Allowed` HTTP error.
|
||||
::
|
||||
|
||||
@ -267,7 +267,7 @@ export default defineEventHandler((event) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-ph-lightbulb" color="green" to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
|
||||
::tip{to="https://unjs.io/blog/2023-08-15-h3-towards-the-edge-of-the-web#runtime-type-safe-request-utils"}
|
||||
Alternatively, use `getValidatedQuery` with a schema validator such as Zod for runtime and type safety.
|
||||
::
|
||||
|
||||
@ -333,7 +333,7 @@ NUXT_GITHUB_TOKEN='<my-super-token>'
|
||||
```
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
|
||||
::
|
||||
|
||||
@ -353,7 +353,7 @@ export default defineEventHandler((event) => {
|
||||
|
||||
You can use `nitro` key in `nuxt.config` to directly set [Nitro configuration](https://nitro.unjs.io/config).
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
This is an advanced option. Custom config can affect production deployments, as the configuration interface might change over time when Nitro is upgraded in semver-minor versions of Nuxt.
|
||||
::
|
||||
|
||||
@ -380,7 +380,7 @@ export default useBase('/api/hello', router.handler)
|
||||
|
||||
### Sending Streams
|
||||
|
||||
::callout
|
||||
::tip
|
||||
This is an experimental feature and is available in all environments.
|
||||
::
|
||||
|
||||
@ -409,7 +409,7 @@ export default fromNodeMiddleware((req, res) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
Legacy support is possible using [unjs/h3](https://github.com/unjs/h3), but it is advised to avoid legacy handlers as much as you can.
|
||||
::
|
||||
|
||||
@ -420,7 +420,7 @@ export default fromNodeMiddleware((req, res, next) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Never combine `next()` callback with a legacy middleware that is `async` or returns a `Promise`.
|
||||
::
|
||||
|
||||
|
||||
@ -39,11 +39,11 @@ You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files
|
||||
|
||||
:link-example{to="/docs/examples/features/auto-imports"}
|
||||
|
||||
::callout
|
||||
::tip
|
||||
The way `utils/` auto-imports work and are scanned is identical to the [`composables/`](/docs/guide/directory-structure/composables) directory.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
These utils are only available within the Vue part of your app. :br
|
||||
Only `server/utils` are auto-imported in the [`server/`](/docs/guide/directory-structure/server#server-utilities) directory.
|
||||
::
|
||||
|
||||
@ -5,7 +5,7 @@ head.title: ".env"
|
||||
navigation.icon: i-ph-file-duotone
|
||||
---
|
||||
|
||||
::callout{icon="i-ph-warning-duotone" color="amber"}
|
||||
::important
|
||||
This file should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing secrets to your repository.
|
||||
::
|
||||
|
||||
@ -19,7 +19,7 @@ In addition to any process environment variables, if you have a `.env` file in y
|
||||
MY_ENV_VARIABLE=hello
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Note that removing a variable from `.env` or removing the `.env` file entirely will not unset values that have already been set.
|
||||
::
|
||||
|
||||
@ -51,7 +51,7 @@ Note that for a purely static site, it is not possible to set runtime configurat
|
||||
|
||||
:read-more{to="/docs/guide/going-further/runtime-config"}
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you want to use environment variables set at build time but do not care about updating these down the line (or only need to update them reactively _within_ your app) then `appConfig` may be a better choice. You can define `appConfig` both within your `nuxt.config` (using environment variables) and also within an `~/app.config.ts` file in your project.
|
||||
:read-more{to="/docs/guide/directory-structure/app-config"}
|
||||
::
|
||||
|
||||
@ -9,7 +9,7 @@ The `.nuxtignore` file tells Nuxt to ignore files in your project’s root direc
|
||||
|
||||
It is subject to the same specification as [`.gitignore`](/docs/guide/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
You can also configure [`ignoreOptions`](/docs/api/nuxt-config#ignoreoptions), [`ignorePrefix`](/docs/api/nuxt-config#ignoreprefix) and [`ignore`](/docs/api/nuxt-config#ignore) in your `nuxt.config` file.
|
||||
::
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ export default defineAppConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::caution
|
||||
Do not put any secret values inside `app.config` file. It is exposed to the user client bundle.
|
||||
::
|
||||
|
||||
@ -72,7 +72,7 @@ export {}
|
||||
|
||||
If you want to type the result of calling [`useAppConfig()`](/docs/api/composables/use-app-config), then you will want to extend `AppConfig`.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Be careful when typing `AppConfig` as you will overwrite the types Nuxt infers from your actually defined app config.
|
||||
::
|
||||
|
||||
@ -98,7 +98,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.
|
||||
|
||||
::callout
|
||||
::note
|
||||
The Function Merger should only be used in the base `app.config` of your application.
|
||||
::
|
||||
|
||||
|
||||
@ -31,11 +31,11 @@ If you have a [`pages/`](/docs/guide/directory-structure/pages) directory, to di
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Since [`<NuxtPage>`](/docs/api/components/nuxt-page) internally uses Vue's [`<Suspense>`](https://vuejs.org/guide/built-ins/suspense.html#suspense) component, it cannot be set as a root element.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
Remember that `app.vue` acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.
|
||||
::
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ const props = defineProps({
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Although it is called an 'error page' it's not a route and shouldn't be placed in your `~/pages` directory. For the same reason, you shouldn't use `definePageMeta` within this page. That being said, you can still use layouts in the error file, by utilizing the [`NuxtLayout`](/docs/api/components/nuxt-layout) component and specifying the name of the layout.
|
||||
::
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
`defineNuxtConfig` helper is globally available without import.
|
||||
::
|
||||
|
||||
|
||||
@ -15,10 +15,10 @@ You can benefit from this by creating a `tsconfig.json` in the root of your proj
|
||||
}
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
As you need to, you can customize the contents of this file. However, it is recommended that you don't overwrite `target`, `module` and `moduleResolution`.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the [`alias`](/docs/api/nuxt-config#alias) property within your `nuxt.config`, where they will get picked up and added to the auto-generated `tsconfig`.
|
||||
::
|
||||
|
||||
@ -7,7 +7,7 @@ The Nuxt experimental features can be enabled in the Nuxt configuration file.
|
||||
|
||||
Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Note that these features are experimental and could be removed or modified in the future.
|
||||
::
|
||||
|
||||
@ -53,7 +53,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
This feature will likely be removed in a near future.
|
||||
::
|
||||
|
||||
@ -91,7 +91,7 @@ Allows Nuxt app state to be restored from `sessionStorage` when reloading the pa
|
||||
|
||||
To avoid hydration errors, it will be applied only after the Vue app has been mounted, meaning there may be a flicker on initial load.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
Consider carefully before enabling this as it can cause unexpected behavior,
|
||||
and consider providing explicit keys to [`useState`](/docs/api/composables/use-state) as auto-generated keys may not match across builds.
|
||||
::
|
||||
@ -319,11 +319,11 @@ performance in large projects or on Windows platforms.
|
||||
You can also set this to `chokidar` to watch all files in your source directory.
|
||||
|
||||
```ts twoslash [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
experimental: {
|
||||
export default defineNuxtConfig({
|
||||
experimental: {
|
||||
watcher: 'chokidar-granular' // 'chokidar' or 'parcel' are also options
|
||||
}
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## sharedPrerenderData
|
||||
@ -333,11 +333,11 @@ in a significant performance improvement when prerendering sites that use `useAs
|
||||
fetch the same data in different pages.
|
||||
|
||||
```ts twoslash [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
experimental: {
|
||||
export default defineNuxtConfig({
|
||||
experimental: {
|
||||
sharedPrerenderData: true
|
||||
}
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
It is particularly important when enabling this feature to make sure that any unique key of your data
|
||||
@ -383,11 +383,11 @@ This only works with static or strings/arrays rather than variables or condition
|
||||
Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.
|
||||
|
||||
```ts twoslash [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
experimental: {
|
||||
export default defineNuxtConfig({
|
||||
experimental: {
|
||||
cookieStore: true
|
||||
}
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::read-more{icon="i-simple-icons-mdnwebdocs" color="gray" to="https://developer.mozilla.org/en-US/docs/Web/API/CookieStore" target="_blank"}
|
||||
|
||||
@ -29,7 +29,7 @@ console.log(runtimeConfig.apiSecret)
|
||||
console.log(runtimeConfig.public.apiBase)
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Public runtime config is accessible in Vue templates with `$config.public`.
|
||||
::
|
||||
|
||||
@ -43,7 +43,7 @@ Instead of passing non-serializable objects or functions into your application f
|
||||
|
||||
The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
|
||||
|
||||
::callout
|
||||
::note
|
||||
Nuxi CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.
|
||||
:read-more{to="/docs/guide/directory-structure/env"}
|
||||
::
|
||||
@ -56,7 +56,7 @@ There are two key requirements:
|
||||
|
||||
1. Only a specially-named environment variable can override a runtime config property. That is, an uppercase environment variable starting with `NUXT_` which uses `_` to separate keys and case changes.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Setting the default of `runtimeConfig` values to *differently named environment variables* (for example setting `myVar` to `process.env.OTHER_VARIABLE`) will only work during build-time and will break on runtime.
|
||||
It is advised to use environment variables that match the structure of your `runtimeConfig` object.
|
||||
::
|
||||
@ -85,7 +85,7 @@ export default defineNuxtConfig({
|
||||
|
||||
Within the Vue part of your Nuxt app, you will need to call [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) to access the runtime config.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
The behavior is different between the client-side and server-side:
|
||||
|
||||
- On client-side, only keys in `runtimeConfig.public` are available, and the object is both writable and reactive.
|
||||
@ -110,7 +110,7 @@ if (process.server) {
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout{icon="i-ph-flag-duotone" color="red"}
|
||||
::caution
|
||||
**Security note:** Be careful not to expose runtime config keys to the client-side by either rendering them or passing them to `useState`.
|
||||
::
|
||||
|
||||
@ -142,7 +142,7 @@ export default defineEventHandler(async (event) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
|
||||
::
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ You can use these 'nightly' releases to beta test new features and changes.
|
||||
|
||||
The build and publishing method and quality of these 'nightly' releases are the same as stable ones. The only difference is that you should often check the GitHub repository for updates. There is a slight chance of regressions not being caught during the review process and by the automated tests. Therefore, we internally use this channel to double-check everything before each release.
|
||||
|
||||
::callout
|
||||
::note
|
||||
Features that are only available on the nightly release channel are marked with an alert in the documentation.
|
||||
::
|
||||
|
||||
@ -47,7 +47,7 @@ Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.loc
|
||||
|
||||
## Using Nightly `nuxi`
|
||||
|
||||
::callout
|
||||
::note
|
||||
All cli dependencies are bundled because of the building method for reducing `nuxi` package size. :br You can get dependency updates and CLI improvements using the nightly release channel.
|
||||
::
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ title: "Lifecycle Hooks"
|
||||
description: "Nuxt provides a powerful hooking system to expand almost every aspect using hooks."
|
||||
---
|
||||
|
||||
::callout
|
||||
::tip
|
||||
The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookable).
|
||||
::
|
||||
|
||||
|
||||
@ -39,7 +39,7 @@ You can interact with the playground like with any Nuxt application.
|
||||
- Launch its development server with `npm run dev`, it should reload itself as you make changes to your module in the `src` directory
|
||||
- Build it with `npm run dev:build`
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
All other `nuxi` commands can be used against the `playground` directory (e.g. `nuxi <COMMAND> playground`). Feel free to declare additional `dev:*` scripts within your `package.json` referencing them for convenience.
|
||||
::
|
||||
|
||||
@ -50,7 +50,7 @@ The module starter comes with a basic test suite:
|
||||
- A linter powered by [ESLint](https://eslint.org), run it with `npm run lint`
|
||||
- A test runner powered by [Vitest](https://vitest.dev), run it with `npm run test` or `npm run test:watch`
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Feel free to augment this default test strategy to better suit your needs.
|
||||
::
|
||||
|
||||
@ -60,13 +60,13 @@ Nuxt Modules come with their own builder provided by [`@nuxt/module-builder`](ht
|
||||
|
||||
You can build your module by running `npm run prepack`.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
While building your module can be useful in some cases, most of the time you won't need to build it on your own: the `playground` takes care of it while developing, and the release script also has you covered when publishing.
|
||||
::
|
||||
|
||||
#### How to Publish
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
Before publishing your module to npm, makes sure you have an [npmjs.com](https://www.npmjs.com) account and that you're authenticated to it locally with `npm login`.
|
||||
::
|
||||
|
||||
@ -85,7 +85,7 @@ When running the release script, the following will happen:
|
||||
- Publishing the module to npm (for that purpose, the module will be built again to ensure its updated version number is taken into account in the published artifact)
|
||||
- Pushing a git tag representing the newly published version to your git remote origin
|
||||
|
||||
::callout
|
||||
::tip
|
||||
As with other scripts, feel free to fine-tune the default `release` script in your `package.json` to better suit your needs.
|
||||
::
|
||||
|
||||
@ -104,7 +104,7 @@ In either case, their anatomy is similar.
|
||||
|
||||
#### Module Definition
|
||||
|
||||
::callout
|
||||
::note
|
||||
When using the starter, your module definition is available at `src/module.ts`.
|
||||
::
|
||||
|
||||
@ -179,7 +179,7 @@ Ultimately `defineNuxtModule` returns a wrapper function with the lower level `(
|
||||
|
||||
#### Runtime Directory
|
||||
|
||||
::callout
|
||||
::note
|
||||
When using the starter, the runtime directory is available at `src/runtime`.
|
||||
::
|
||||
|
||||
@ -203,11 +203,11 @@ Or any other kind of asset you want to inject in users' Nuxt applications:
|
||||
|
||||
You'll then be able to inject all those assets inside the application from your [module definition](#module-definition).
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Learn more about asset injection in [the recipes section](#recipes).
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Published modules cannot leverage auto-imports for assets within their runtime directory. Instead, they have to import them explicitly from `#imports` or alike.
|
||||
|
||||
Indeed, auto-imports are not enabled for files within `node_modules` (the location where a published module will eventually live) for performance reasons.
|
||||
@ -282,7 +282,7 @@ You can then access your module options in a plugin, component, the application
|
||||
const options = useRuntimeConfig().public.myModule
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Be careful not to expose any sensitive module configuration on the public runtime config, such as private API keys, as they will end up in the public bundle.
|
||||
::
|
||||
|
||||
@ -344,8 +344,8 @@ export default defineNuxtModule({
|
||||
setup(options, nuxt) {
|
||||
const resolver = createResolver(import.meta.url)
|
||||
|
||||
addComponentsDir({
|
||||
path: resolver.resolve('runtime/components')
|
||||
addComponentsDir({
|
||||
path: resolver.resolve('runtime/components')
|
||||
})
|
||||
}
|
||||
})
|
||||
@ -364,8 +364,8 @@ export default defineNuxtModule({
|
||||
|
||||
addImports({
|
||||
name: 'useComposable', // name of the composable to be used
|
||||
as: 'useComposable',
|
||||
from: resolver.resolve('runtime/composables/useComposable') // path of composable
|
||||
as: 'useComposable',
|
||||
from: resolver.resolve('runtime/composables/useComposable') // path of composable
|
||||
})
|
||||
}
|
||||
})
|
||||
@ -462,7 +462,7 @@ If your module depends on other modules, you can add them by using Nuxt Kit's `i
|
||||
```ts
|
||||
import { defineNuxtModule, createResolver, installModule } from '@nuxt/kit'
|
||||
|
||||
export default defineNuxtModule<ModuleOptions>({
|
||||
export default defineNuxtModule<ModuleOptions>({
|
||||
async setup (options, nuxt) {
|
||||
const { resolve } = createResolver(import.meta.url)
|
||||
|
||||
@ -511,9 +511,10 @@ export default defineNuxtModule({
|
||||
|
||||
:read-more{to="/docs/api/advanced/hooks"}
|
||||
|
||||
::callout
|
||||
::note
|
||||
**Module cleanup**
|
||||
|
||||
:br
|
||||
:br
|
||||
If your module opens, handles, or starts a watcher, you should close it when the Nuxt lifecycle is done. The `close` hook is available for this.
|
||||
|
||||
```ts
|
||||
@ -527,7 +528,6 @@ export default defineNuxtModule({
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
#### Adding Templates/Virtual Files
|
||||
@ -592,7 +592,7 @@ If you need to update your templates/virtual files, you can leverage the `update
|
||||
|
||||
```ts
|
||||
nuxt.hook('builder:watch', async (event, path) => {
|
||||
if (path.includes('my-module-feature.config')) {
|
||||
if (path.includes('my-module-feature.config')) {
|
||||
// This will reload the template that you registered
|
||||
updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
|
||||
}
|
||||
@ -605,7 +605,7 @@ Testing helps ensuring your module works as expected given various setup. Find i
|
||||
|
||||
#### Unit and Integration
|
||||
|
||||
::callout
|
||||
::tip
|
||||
We're still discussing and exploring how to ease unit and integration testing on Nuxt Modules.
|
||||
|
||||
[Check out this RFC to join the conversation](https://github.com/nuxt/nuxt/discussions/18399).
|
||||
@ -661,7 +661,7 @@ describe('ssr', async () => {
|
||||
describe('csr', async () => { /* ... */ })
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
An example of such a workflow is available on [the module starter](https://github.com/nuxt/starter/blob/module/test/basic.test.ts).
|
||||
::
|
||||
|
||||
@ -683,7 +683,7 @@ As we've seen, Nuxt Modules can be asynchronous. For example, you may want to de
|
||||
|
||||
However, be careful with asynchronous behaviors as Nuxt will wait for your module to setup before going to the next module and starting the development server, build process, etc. Prefer deferring time-consuming logic to Nuxt hooks.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
If your module takes more than **1 second** to setup, Nuxt will emit a warning about it.
|
||||
::
|
||||
|
||||
|
||||
@ -31,7 +31,7 @@ import { useNuxt } from '@nuxt/kit'
|
||||
|
||||
:read-more{to="/docs/api/kit"}
|
||||
|
||||
::callout
|
||||
::note
|
||||
Nuxt Kit utilities are only available for modules and not meant to be imported in runtime (components, Vue composables, pages, plugins, or server routes).
|
||||
::
|
||||
|
||||
|
||||
@ -96,11 +96,11 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
If you want to extend a private remote source, you need to add the environment variable `GIGET_AUTH=<token>` to provide a token.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::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.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
@ -144,13 +144,13 @@ To publish a layer directory as an npm package, you want to make sure that the `
|
||||
}
|
||||
```
|
||||
|
||||
::callout
|
||||
::important
|
||||
Make sure any dependency imported in the layer is **explicitly added** to the `dependencies`. The `nuxt` dependency, and anything only used for testing the layer before publishing, should remain in the `devDependencies` field.
|
||||
::
|
||||
|
||||
Now you can proceed to publish the module to npm, either publicly or privately.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
When publishing the layer as a private npm package, you need to make sure you log in, to authenticate with npm to download the node module.
|
||||
::
|
||||
|
||||
|
||||
@ -28,7 +28,7 @@ export default <RouterConfig> {
|
||||
}
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Nuxt will not augment any new routes you return from the `routes` function with metadata defined in `definePageMeta` of the component you provide. If you want that to happen, you should use the `pages:extend` hook which is [called at build-time](/docs/api/advanced/hooks#nuxt-hooks-build-time).
|
||||
::
|
||||
|
||||
@ -151,7 +151,7 @@ export default defineNuxtConfig({
|
||||
### Scroll Behavior for hash links
|
||||
|
||||
You can optionally customize the scroll behavior for hash links. When you set the [config](/docs/api/nuxt-config#router) to be `smooth` and you load a page with a hash link (e.g. `https://example.com/blog/my-article#comments`), you will see that the browser smoothly scrolls to this anchor.
|
||||
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
router: {
|
||||
|
||||
@ -26,7 +26,7 @@ nuxi dev --inspect
|
||||
```
|
||||
This will start Nuxt in `dev` mode with debugger active. If everything is working correctly a Node.js icon will appear on your Chrome DevTools and you can attach to the debugger.
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
Note that the Node.js and Chrome processes need to be run on the same platform. This doesn't work inside of Docker.
|
||||
::
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout{to="/docs/guide/going-further/experimental-features#clientfallback"}
|
||||
::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`.
|
||||
::
|
||||
|
||||
@ -63,4 +63,3 @@ This component is experimental and in order to use it you must enable the `exper
|
||||
</NuxtClientFallback>
|
||||
</template>
|
||||
```
|
||||
|
||||
@ -3,7 +3,7 @@ title: '<Teleport>'
|
||||
description: The <Teleport> component teleports a component to a different location in the DOM.
|
||||
---
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
The `to` target of [`<Teleport>`](https://vuejs.org/guide/built-ins/teleport.html) expects a CSS selector string or an actual DOM node. Nuxt currently has SSR support for teleports to `body` only, with client-side support for other targets using a `<ClientOnly>` wrapper.
|
||||
::
|
||||
|
||||
|
||||
@ -10,12 +10,12 @@ links:
|
||||
|
||||
`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`pages/`](/docs/guide/directory-structure/pages) directory.
|
||||
|
||||
::callout
|
||||
::note
|
||||
`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-routerviewprops) component from Vue Router. :br
|
||||
It accepts same `name` and `route` props.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
`<NuxtPage>` should be used instead of `<RouterView>` as the former takes additional care on internal states. Otherwise, `useRoute()` may return incorrect paths.
|
||||
::
|
||||
|
||||
@ -32,7 +32,7 @@ It accepts same `name` and `route` props.
|
||||
- `keepalive`: control state preservation of pages rendered with the `NuxtPage` component.
|
||||
- type: `boolean` or `KeepAliveProps`
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Nuxt automatically resolves the `name` and `route` by scanning and rendering all Vue component files found in the `/pages` directory.
|
||||
::
|
||||
|
||||
@ -52,7 +52,7 @@ You can also use a dynamic key based on the current route:
|
||||
<NuxtPage :page-key="route => route.fullPath" />
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Don't use `$route` object here as it can cause problems with how `<NuxtPage>` renders pages with `<Suspense>`.
|
||||
::
|
||||
|
||||
|
||||
@ -39,7 +39,7 @@ const layout = 'custom'
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Please note the layout name is normalized to kebab-case, so if your layout file is named `errorLayout.vue`, it will become `error-layout` when passed as a `name` property to `<NuxtLayout />`.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
`<NuxtLink>` is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is _internal_ or _external_ and renders it accordingly with available optimizations (prefetching, default attributes, etc.)
|
||||
::
|
||||
|
||||
@ -116,7 +116,7 @@ When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink`
|
||||
- `target`: A `target` attribute value to apply on the link
|
||||
- `rel`: A `rel` attribute value to apply on the link. Defaults to `"noopener noreferrer"` for external links.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Defaults can be overwritten, see [overwriting defaults](#overwriting-defaults) if you want to change them.
|
||||
::
|
||||
|
||||
@ -126,7 +126,7 @@ Defaults can be overwritten, see [overwriting defaults](#overwriting-defaults) i
|
||||
|
||||
You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](https://nuxt.com/docs/api/nuxt-config#defaults)
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::important
|
||||
These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
|
||||
::
|
||||
|
||||
|
||||
@ -35,15 +35,15 @@ You can pass custom HTML or components through the loading indicator's default s
|
||||
- `throttle`: Throttle the appearing and hiding, in milliseconds (default `200`).
|
||||
- `estimatedProgress`: By default Nuxt will back off as it approaches 100%. You can provide a custom function to customize the progress estimation, which is a function that receives the duration of the loading bar (above) and the elapsed time. It should return a value between 0 and 100.
|
||||
|
||||
::callout
|
||||
::note
|
||||
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-loading-indicator.ts).
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
You can hook into the underlying indicator instance using [the `useLoadingIndicator` composable](/docs/api/composables/use-loading-indicator), which will allow you to trigger start/finish events yourself.
|
||||
::
|
||||
|
||||
::callout
|
||||
::tip
|
||||
The loading indicator's speed gradually decreases after reaching a specific point controlled by `estimatedProgress`. This adjustment provides a more accurate reflection of longer page loading times and prevents the indicator from prematurely showing 100% completion.
|
||||
::
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::tip
|
||||
The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured) hook under the hood.
|
||||
::
|
||||
|
||||
|
||||
@ -20,6 +20,6 @@ It includes links to the Nuxt documentation, source code, and social media accou
|
||||
Preview the `<NuxtWelcome />` component.
|
||||
::
|
||||
|
||||
::callout
|
||||
::tip
|
||||
This component is part of [nuxt/assets](https://github.com/nuxt/assets).
|
||||
::
|
||||
|
||||
@ -16,11 +16,11 @@ Changing the island component props triggers a refetch of the island component t
|
||||
This component is experimental and in order to use it you must enable the `experimental.componentIslands` option in your `nuxt.config`.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
Global styles of your application are sent with the response.
|
||||
::
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Server only components use `<NuxtIsland>` under the hood
|
||||
::
|
||||
|
||||
@ -40,7 +40,7 @@ Server only components use `<NuxtIsland>` under the hood
|
||||
- **type**: `boolean`
|
||||
- **default**: `false`
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
Remote islands need `experimental.componentIslands` to be `'local+remote'` in your `nuxt.config`.
|
||||
It is strongly discouraged to enable `dangerouslyLoadClientComponents` as you can't trust a remote server's javascript.
|
||||
::
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
|
||||
Within your pages, components, and plugins you can use useAsyncData to get access to data that resolves asynchronously.
|
||||
|
||||
::callout
|
||||
::note
|
||||
[`useAsyncData`](/docs/api/composables/use-async-data) is a composable meant to be called directly in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context). It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client **without re-fetching the data on client side** when the page hydrates.
|
||||
::
|
||||
|
||||
@ -25,7 +25,7 @@ const { data, pending, error, refresh } = await useAsyncData(
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
`data`, `pending`, `status` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` is a plain function for refetching data.
|
||||
::
|
||||
|
||||
@ -49,7 +49,7 @@ const { data: posts } = await useAsyncData(
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
[`useAsyncData`](/docs/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/api/composables/use-async-data) .
|
||||
::
|
||||
|
||||
@ -73,7 +73,7 @@ const { data: posts } = await useAsyncData(
|
||||
- `cancel` - cancels existing requests when a new one is made
|
||||
- `defer` - does not make new requests at all if there is a pending request
|
||||
|
||||
::callout
|
||||
::note
|
||||
Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the route before the data has been fetched. Consider using `lazy: true` and implementing a loading state instead for a snappier user experience.
|
||||
::
|
||||
|
||||
@ -81,7 +81,7 @@ Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the rout
|
||||
You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `useAsyncData`.
|
||||
::
|
||||
|
||||
::callout{icon="i-simple-icons-youtube" color="gray" to="https://www.youtube.com/watch?v=aQPR0xn-MMk" target="_blank"}
|
||||
::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.
|
||||
::
|
||||
|
||||
@ -95,7 +95,7 @@ Learn how to use `transform` and `getCachedData` to avoid superfluous calls to a
|
||||
|
||||
By default, Nuxt waits until a `refresh` is finished before it can be executed again.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/api/composables/use-async-data) on the client side, `data` will remain `null` within `<script setup>`.
|
||||
::
|
||||
|
||||
|
||||
@ -14,11 +14,11 @@ Within your pages, components and plugins you can use `useCookie`, an SSR-friend
|
||||
const cookie = useCookie(name, options)
|
||||
```
|
||||
|
||||
::alert{icon=👉}
|
||||
::note
|
||||
`useCookie` only works in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
|
||||
::
|
||||
|
||||
::callout
|
||||
::tip
|
||||
`useCookie` ref will automatically serialize and deserialize cookie value to JSON.
|
||||
::
|
||||
|
||||
@ -62,13 +62,13 @@ The given number will be converted to an integer by rounding down. By default, n
|
||||
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.
|
||||
|
||||
::callout
|
||||
::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!
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser.
|
||||
::
|
||||
|
||||
@ -77,7 +77,7 @@ If neither of `expires` and `maxAge` is set, the cookie will be session-only and
|
||||
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.
|
||||
|
||||
::callout
|
||||
::warning
|
||||
Be careful when setting this to `true`, as compliant clients will not allow client-side
|
||||
JavaScript to see the cookie in `document.cookie`.
|
||||
::
|
||||
@ -87,7 +87,7 @@ JavaScript to see the cookie in `document.cookie`.
|
||||
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.
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
@ -128,7 +128,7 @@ a previously encoded cookie value into a JavaScript string or other object.
|
||||
|
||||
The default decoder is `decodeURIComponent` + [destr](https://github.com/unjs/destr).
|
||||
|
||||
::callout
|
||||
::note
|
||||
If an error is thrown from this function, the original, non-decoded cookie value will
|
||||
be returned as the cookie's value.
|
||||
::
|
||||
|
||||
@ -11,7 +11,7 @@ links:
|
||||
This composable provides a convenient wrapper around [`useAsyncData`](/docs/api/composables/use-async-data) and [`$fetch`](/docs/api/utils/dollarfetch).
|
||||
It automatically generates a key based on URL and fetch options, provides type hints for request url based on server routes, and infers API response type.
|
||||
|
||||
::callout
|
||||
::note
|
||||
`useFetch` is a composable meant to be called directly in a setup function, plugin, or route middleware. It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client without re-fetching the data on client side when the page hydrates.
|
||||
::
|
||||
|
||||
@ -25,7 +25,7 @@ const { data, pending, error, refresh } = await useFetch('/api/modules', {
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
`data`, `pending`, `status` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` is a plain function for refetching data.
|
||||
::
|
||||
|
||||
@ -62,7 +62,7 @@ const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
|
||||
})
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
`useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
|
||||
::
|
||||
|
||||
@ -84,7 +84,7 @@ const { data, pending, error, refresh } = await useFetch('/api/auth/login', {
|
||||
- `baseURL`: Base URL for the request.
|
||||
- `timeout`: Milliseconds to automatically abort request
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
|
||||
@ -103,11 +103,11 @@ All fetch options can be given a `computed` or `ref` value. These will be watche
|
||||
- `cancel` - cancels existing requests when a new one is made
|
||||
- `defer` - does not make new requests at all if there is a pending request
|
||||
|
||||
::callout
|
||||
::note
|
||||
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`.
|
||||
::
|
||||
|
||||
::callout{icon="i-simple-icons-youtube" color="gray" to="https://www.youtube.com/watch?v=aQPR0xn-MMk" target="_blank"}
|
||||
::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.
|
||||
::
|
||||
|
||||
@ -121,7 +121,7 @@ Learn how to use `transform` and `getCachedData` to avoid superfluous calls to a
|
||||
|
||||
By default, Nuxt waits until a `refresh` is finished before it can be executed again.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.
|
||||
::
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ interface MetaObject {
|
||||
|
||||
See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/schema/src/schema.ts) for more detailed types.
|
||||
|
||||
::callout
|
||||
::note
|
||||
The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. `meta` parameter can also accept a function returning an object to make the entire object reactive.
|
||||
::
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
|
||||
`useHydration` is a built-in composable that provides a way to set data on the server side every time a new HTTP request is made and receive that data on the client side. This way `useHydration` allows you to take full control of the hydration cycle.
|
||||
|
||||
::callout
|
||||
::note
|
||||
This is an advanced composable and is mostly used internally (`useAsyncData`) or by Nuxt modules.
|
||||
::
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@ links:
|
||||
|
||||
By default, [`useAsyncData`](/docs/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
|
||||
|
||||
::callout
|
||||
::note
|
||||
`useLazyAsyncData` has the same signature as [`useAsyncData`](/docs/api/composables/use-async-data).
|
||||
::
|
||||
|
||||
@ -40,7 +40,7 @@ watch(count, (newCount) => {
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
|
||||
::
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@ links:
|
||||
|
||||
By default, [`useFetch`](/docs/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` provides a wrapper around [`useFetch`](/docs/api/composables/use-fetch) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
|
||||
|
||||
::callout
|
||||
::note
|
||||
`useLazyFetch` has the same signature as [`useFetch`](/docs/api/composables/use-fetch).
|
||||
::
|
||||
|
||||
@ -44,7 +44,7 @@ watch(posts, (newPosts) => {
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.
|
||||
::
|
||||
|
||||
|
||||
@ -169,7 +169,7 @@ export default defineComponent({
|
||||
|
||||
### `runWithContext`
|
||||
|
||||
::callout
|
||||
::note
|
||||
You are likely here because you got a "Nuxt instance unavailable" message. Please use this method sparingly, and report examples that are causing issues, so that it can ultimately be solved at the framework level.
|
||||
::
|
||||
|
||||
@ -186,7 +186,7 @@ export default defineNuxtRouteMiddleware(async (to, from) => {
|
||||
user = null
|
||||
}
|
||||
if (!user) {
|
||||
// apply the correct Nuxt context to our `navigateTo` call.
|
||||
// apply the correct Nuxt context to our `navigateTo` call.
|
||||
return nuxtApp.runWithContext(() => navigateTo('/auth'))
|
||||
}
|
||||
})
|
||||
@ -254,7 +254,7 @@ The `unjs/unctx` transformation to automatically restore context seems buggy wit
|
||||
|
||||
Using a new experimental feature, it is possible to enable native async context support using [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) and new unctx support to make async context available **natively** to **any nested async composable** without needing a transform or manual passing/calling with context.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
Native async context support works currently in Bun and Node.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
`useNuxtData` gives you access to the current cached value of [`useAsyncData`](/docs/api/composables/use-async-data) , `useLazyAsyncData`, [`useFetch`](/docs/api/composables/use-fetch) and [`useLazyFetch`](/docs/api/composables/use-lazy-fetch) with explicitly provided key.
|
||||
::
|
||||
|
||||
|
||||
@ -18,6 +18,6 @@ const event = useRequestEvent()
|
||||
const url = event?.path
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
In the browser, `useRequestEvent` will return `undefined`.
|
||||
::
|
||||
|
||||
@ -15,7 +15,7 @@ You can use the built-in [`useRequestHeader`](/docs/api/composables/use-request-
|
||||
const authorization = useRequestHeader('authorization')
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
In the browser, `useRequestHeader` will return `undefined`.
|
||||
::
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ const headers = useRequestHeaders()
|
||||
const headers = useRequestHeaders(['cookie'])
|
||||
```
|
||||
|
||||
::callout
|
||||
::tip
|
||||
In the browser, `useRequestHeaders` will return an empty object.
|
||||
::
|
||||
|
||||
|
||||
@ -30,6 +30,6 @@ const url = useRequestURL()
|
||||
|
||||
::
|
||||
|
||||
::callout{icon="i-simple-icons-mdnwebdocs" color="gray" to="https://developer.mozilla.org/en-US/docs/Web/API/URL#instance_properties" target="_blank"}
|
||||
::tip{icon="i-simple-icons-mdnwebdocs" color="gray" to="https://developer.mozilla.org/en-US/docs/Web/API/URL#instance_properties" target="_blank"}
|
||||
Read about the URL instance properties on the MDN documentation.
|
||||
::
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
Within the template of a Vue component, you can access the route using `$route`.
|
||||
::
|
||||
|
||||
@ -44,7 +44,7 @@ Apart from dynamic parameters and query parameters, `useRoute()` also provides t
|
||||
- `path`: encoded pathname section of the URL
|
||||
- `redirectedFrom`: route location that was attempted to access before ending up on the current route location
|
||||
|
||||
::callout
|
||||
::note
|
||||
Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` in your template can trigger hydration issues because this will include the fragment on client but not the server.
|
||||
::
|
||||
|
||||
|
||||
@ -46,7 +46,7 @@ router.hasRoute('home')
|
||||
router.resolve({ name: 'home' })
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/guide/directory-structure/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.
|
||||
::
|
||||
|
||||
|
||||
@ -44,7 +44,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Variables that need to be accessible on the server are added directly inside `runtimeConfig`. Variables that need to be accessible on both the client and the server are defined in `runtimeConfig.public`.
|
||||
::
|
||||
|
||||
@ -87,11 +87,11 @@ NUXT_PUBLIC_API_BASE = "https://api.localhost:5555"
|
||||
NUXT_API_SECRET = "123"
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Any environment variables set within `.env` file are accessed using `process.env` in the Nuxt app during **development** and **build/generate**.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
In **production runtime**, you should use platform environment variables and `.env` is not used.
|
||||
::
|
||||
|
||||
@ -101,7 +101,7 @@ In **production runtime**, you should use platform environment variables and `.e
|
||||
|
||||
Nuxt uses `app` namespace in runtime-config with keys including `baseURL` and `cdnURL`. You can customize their values at runtime by setting environment variables.
|
||||
|
||||
::callout
|
||||
::note
|
||||
This is a reserved namespace. You should not introduce additional keys inside `app`.
|
||||
::
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
|
||||
This helps you avoid common mistakes, such as using `name` instead of `property`, as well as typos - with over 100+ meta tags fully typed.
|
||||
|
||||
::callout
|
||||
::important
|
||||
This is the recommended way to add meta tags to your site as it is XSS safe and has full TypeScript support.
|
||||
::
|
||||
|
||||
|
||||
@ -17,11 +17,11 @@ const count = useState('counter', () => Math.round(Math.random() * 100))
|
||||
|
||||
:read-more{to="/docs/getting-started/state-management"}
|
||||
|
||||
::callout
|
||||
::important
|
||||
Because the data inside `useState` will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.
|
||||
::
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
`useState` is a reserved function name transformed by the compiler, so you should not name your own function `useState`.
|
||||
::
|
||||
|
||||
|
||||
@ -10,11 +10,11 @@ links:
|
||||
|
||||
Nuxt uses [ofetch](https://github.com/unjs/ofetch) to expose globally the `$fetch` helper for making HTTP requests within your Vue app or API routes.
|
||||
|
||||
::callout{icon="i-ph-rocket-launch-duotone"}
|
||||
::tip{icon="i-ph-rocket-launch-duotone" color="gray"}
|
||||
During server-side rendering, calling `$fetch` to fetch your internal [API routes](/docs/guide/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note{color="blue" icon="i-ph-info-duotone"}
|
||||
Using `$fetch` in components without wrapping it with [`useAsyncData`](/docs/api/composables/use-async-data) causes fetching the data twice: initially on the server, then again on the client-side during hydration, because `$fetch` does not transfer state from the server to the client. Thus, the fetch will be executed on both sides because the client has to get the data again.
|
||||
::
|
||||
|
||||
@ -52,6 +52,6 @@ function contactForm() {
|
||||
</template>
|
||||
```
|
||||
|
||||
::callout
|
||||
::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.
|
||||
::
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
`abortNavigation` is only usable inside a [route middleware handler](/docs/guide/directory-structure/middleware).
|
||||
::
|
||||
|
||||
@ -37,7 +37,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
|
||||
if (!user.value.isAuthorized) {
|
||||
return abortNavigation()
|
||||
}
|
||||
|
||||
|
||||
if (to.path !== '/edit-post') {
|
||||
return navigateTo('/edit-post')
|
||||
}
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
Route middleware are navigation guards stored in the [`middleware/`](/docs/guide/directory-structure/middleware) directory of your Nuxt application (unless [set otherwise](/docs/api/nuxt-config#middleware)).
|
||||
::
|
||||
|
||||
@ -36,7 +36,7 @@ The second argument is a function of type `RouteMiddleware`. Same as above, it p
|
||||
|
||||
### `options`
|
||||
|
||||
- **Type:** `AddRouteMiddlewareOptions`
|
||||
- **Type:** `AddRouteMiddlewareOptions`
|
||||
|
||||
An optional `options` argument lets you set the value of `global` to `true` to indicate whether the router middleware is global or not (set to `false` by default).
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout{icon="i-ph-info-duotone" color="blue"}
|
||||
::important
|
||||
This utility is available since [Nuxt v3.9](/blog/v3-9).
|
||||
::
|
||||
|
||||
@ -35,17 +35,17 @@ await callOnce(async () => {
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{to="/docs/getting-started/state-management#usage-with-pinia"}
|
||||
::tip{to="/docs/getting-started/state-management#usage-with-pinia"}
|
||||
`callOnce` is useful in combination with the [Pinia module](/modules/pinia) to call store actions.
|
||||
::
|
||||
|
||||
:read-more{to="/docs/getting-started/state-management"}
|
||||
|
||||
::callout{color="info" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Note that `callOnce` doesn't return anything. You should use [`useAsyncData`](/docs/api/composables/use-async-data) or [`useFetch`](/docs/api/composables/use-fetch) if you want to do data fetching during SSR.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
`callOnce` is a composable meant to be called directly in a setup function, plugin, or route middleware, because it needs to add data to the Nuxt payload to avoid re-calling the function on the client when the page hydrates.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
This method is useful if you want to invalidate the data fetching for another page.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
This method is useful if you want to invalidate the state of `useState`.
|
||||
::
|
||||
|
||||
|
||||
@ -8,11 +8,11 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
`defineNuxtComponent()` is a helper function for defining type safe Vue components using options API similar to [`defineComponent()`](https://vuejs.org/api/general.html#definecomponent). `defineNuxtComponent()` wrapper also adds support for `asyncData` and `head` component options.
|
||||
::
|
||||
|
||||
::callout{color="blue" icon="i-ph-info-duotone"}
|
||||
::note
|
||||
Using `<script setup lang="ts">` is the recommended way of declaring Vue components in Nuxt 3.
|
||||
::
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ export default defineNuxtConfig({
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
When running [`nuxt build`](/docs/api/commands/build), the home page will be pre-rendered in `.output/public/index.html` and statically served.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
`navigateTo` is available on both server side and client side.
|
||||
::
|
||||
|
||||
@ -70,7 +70,7 @@ await navigateTo('https://nuxt.com', {
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
// will open 'https://nuxt.com' in a new tab
|
||||
await navigateTo('https://nuxt.com', {
|
||||
await navigateTo('https://nuxt.com', {
|
||||
open: {
|
||||
target: '_blank',
|
||||
windowFeatures: {
|
||||
@ -95,7 +95,7 @@ interface NavigateToOptions {
|
||||
}
|
||||
```
|
||||
|
||||
::callout{color="amber" icon="i-ph-warning-duotone"}
|
||||
::warning
|
||||
Make sure to always use `await` or `return` on result of `navigateTo` when calling it.
|
||||
::
|
||||
|
||||
@ -184,13 +184,13 @@ An object accepting the following properties:
|
||||
- `top` or `screenY` (optional)
|
||||
|
||||
**Type**: `number`
|
||||
|
||||
|
||||
- `noopener` (optional)
|
||||
|
||||
**Type**: `boolean`
|
||||
|
||||
- `noreferrer` (optional)
|
||||
|
||||
|
||||
**Type**: `boolean`
|
||||
|
||||
Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) for more detailed information on the **windowFeatures** properties.
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::important
|
||||
`onNuxtReady` only runs on the client-side. :br
|
||||
It is ideal for running code that should not block the initial rendering of your app.
|
||||
::
|
||||
|
||||
@ -19,10 +19,10 @@ await prefetchComponents('MyGlobalComponent')
|
||||
await prefetchComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
Current implementation behaves exactly the same as [`preloadComponents`](/docs/api/utils/preload-components) by preloading components instead of just prefetching we are working to improve this behavior.
|
||||
::
|
||||
|
||||
::callout
|
||||
::note
|
||||
On server, `prefetchComponents` will have no effect.
|
||||
::
|
||||
|
||||
@ -18,6 +18,6 @@ await preloadComponents('MyGlobalComponent')
|
||||
await preloadComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
On server, `preloadComponents` will have no effect.
|
||||
::
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
|
||||
Preloading routes loads the components of a given route that the user might navigate to in future. This ensures that the components are available earlier and less likely to block the navigation, improving performance.
|
||||
|
||||
::callout{color="green" icon="i-ph-rocket-launch-duotone"}
|
||||
::tip{icon="i-ph-rocket-launch-duotone" color="gray"}
|
||||
Nuxt already automatically preloads the necessary routes if you're using the `NuxtLink` component.
|
||||
::
|
||||
|
||||
@ -36,6 +36,6 @@ const submit = async () => {
|
||||
|
||||
:read-more{to="/docs/api/utils/navigate-to"}
|
||||
|
||||
::callout
|
||||
::note
|
||||
On server, `preloadRouteComponents` will have no effect.
|
||||
::
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
|
||||
When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page.
|
||||
|
||||
::callout
|
||||
::important
|
||||
`prerenderRoutes` can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
|
||||
::
|
||||
|
||||
@ -21,6 +21,6 @@ prerenderRoutes('/')
|
||||
prerenderRoutes(['/', '/about'])
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
In the browser, or if called outside prerendering, `prerenderRoutes` will have no effect.
|
||||
::
|
||||
|
||||
@ -10,7 +10,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout{icon="i-ph-info-duotone" color="blue"}
|
||||
::important
|
||||
This utility is available since [Nuxt v3.10](/blog/v3-10).
|
||||
::
|
||||
|
||||
@ -35,7 +35,7 @@ const loggedIn = computed(() => !!tokenCookie.value)
|
||||
</script>
|
||||
```
|
||||
|
||||
::callout{to="/docs/guide/going-further/experimental-features#cookiestore"}
|
||||
::note{to="/docs/guide/going-further/experimental-features#cookiestore"}
|
||||
You can enable experimental `cookieStore` option to automatically refresh `useCookie` value when cookie changes in the browser.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
`refreshNuxtData` re-fetches all data from the server and updates the page as well as invalidates the cache of [`useAsyncData`](/docs/api/composables/use-async-data) , `useLazyAsyncData`, [`useFetch`](/docs/api/composables/use-fetch) and `useLazyFetch`.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
`reloadNuxtApp` will perform a hard reload of your app, re-requesting a page and its dependencies from the server.
|
||||
::
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: 'setPageLayout'
|
||||
description: setPageLayout allows you to dynamically change the layout of a page.
|
||||
description: setPageLayout allows you to dynamically change the layout of a page.
|
||||
links:
|
||||
- label: Source
|
||||
icon: i-simple-icons-github
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::important
|
||||
`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
|
||||
::
|
||||
|
||||
@ -19,6 +19,6 @@ export default defineNuxtRouteMiddleware((to) => {
|
||||
})
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you choose to set the layout dynamically on the server side, you _must_ do so before the layout is rendered by Vue (that is, within a plugin or route middleware) to avoid a hydration mismatch.
|
||||
::
|
||||
|
||||
@ -12,7 +12,7 @@ Nuxt provides composables and utilities for first-class server-side-rendering su
|
||||
|
||||
`setResponseStatus` sets the statusCode (and optionally the statusMessage) of the response.
|
||||
|
||||
::callout
|
||||
::important
|
||||
`setResponseStatus` can only be called in the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).
|
||||
::
|
||||
|
||||
@ -29,7 +29,7 @@ if (event) {
|
||||
}
|
||||
```
|
||||
|
||||
::callout
|
||||
::note
|
||||
In the browser, `setResponseStatus` will have no effect.
|
||||
::
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ showError({
|
||||
|
||||
The error is set in the state using [`useError()`](/docs/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.
|
||||
|
||||
::callout
|
||||
::tip
|
||||
`showError` calls the `app:error` hook.
|
||||
::
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ links:
|
||||
size: xs
|
||||
---
|
||||
|
||||
::callout
|
||||
::note
|
||||
Updates the [`app.config`](/docs/guide/directory-structure/app-config) using deep assignment. Existing (nested) properties will be preserved.
|
||||
::
|
||||
|
||||
|
||||
@ -18,6 +18,6 @@ Option | Default | Description
|
||||
-------------------------|-----------------|------------------
|
||||
`rootDir` | `.` | The directory of the target application.
|
||||
|
||||
::callout
|
||||
::note
|
||||
This command sets `process.env.NODE_ENV` to `production`.
|
||||
::
|
||||
|
||||
@ -21,6 +21,6 @@ Option | Default | Description
|
||||
`--dotenv` | `.` | Point to another `.env` file to load, **relative** to the root directory.
|
||||
`--log-level` | `info` | Specify build-time logging level, allowing `silent` \| `info` \| `verbose`.
|
||||
|
||||
::callout
|
||||
::note
|
||||
This command sets `process.env.NODE_ENV` to `production`.
|
||||
::
|
||||
|
||||
@ -34,6 +34,6 @@ Additionally to the above options, `nuxi` can pass options through to `listhen`,
|
||||
|
||||
This command sets `process.env.NODE_ENV` to `development`.
|
||||
|
||||
::callout
|
||||
::note
|
||||
If you are using a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
|
||||
::
|
||||
|
||||
@ -21,6 +21,6 @@ Option | Default | Description
|
||||
|
||||
This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a `.env` file or as command-line argument.
|
||||
|
||||
::callout
|
||||
::note
|
||||
For convenience, in preview mode, your [`.env`](/docs/guide/directory-structure/env) file will be loaded into `process.env`. (However, in production you will need to ensure your environment variables are set yourself.)
|
||||
::
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user