@nuxt/docs 0.0.0 → 3.17.0

package/1.getting-started/06.styling.md

@@ -0,0 +1,565 @@
+---
+title: 'Styling'
+description: 'Learn how to style your Nuxt application.'
+navigation.icon: i-lucide-palette
+---
+
+Nuxt is highly flexible when it comes to styling. Write your own styles, or reference local and external stylesheets.
+You can use CSS preprocessors, CSS frameworks, UI libraries and Nuxt modules to style your application.
+
+## Local Stylesheets
+
+If you're writing local stylesheets, the natural place to put them is the [`assets/` directory](/docs/guide/directory-structure/assets).
+
+### Importing Within Components
+
+You can import stylesheets in your pages, layouts and components directly.
+You can use a JavaScript import, or a CSS [`@import` statement](https://developer.mozilla.org/en-US/docs/Web/CSS/@import).
+
+```vue [pages/index.vue]
+<script>
+// Use a static import for server-side compatibility
+import '~/assets/css/first.css'
+
+// Caution: Dynamic imports are not server-side compatible
+import('~/assets/css/first.css')
+</script>
+
+<style>
+@import url("~/assets/css/second.css");
+</style>
+```
+
+::tip
+The stylesheets will be inlined in the HTML rendered by Nuxt.
+::
+
+### The CSS Property
+
+You can also use the `css` property in the Nuxt configuration.
+The natural place for your stylesheets is the [`assets/` directory](/docs/guide/directory-structure/assets). You can then reference its path and Nuxt will include it to all the pages of your application.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  css: ['~/assets/css/main.css']
+})
+```
+
+::tip
+The stylesheets will be inlined in the HTML rendered by Nuxt, injected globally and present in all pages.
+::
+
+### Working With Fonts
+
+Place your local fonts files in your `~/public/` directory, for example in `~/public/fonts`. You can then reference them in your stylesheets using `url()`.
+
+```css [assets/css/main.css]
+@font-face {
+  font-family: 'FarAwayGalaxy';
+  src: url('/fonts/FarAwayGalaxy.woff') format('woff');
+  font-weight: normal;
+  font-style: normal;
+  font-display: swap;
+}
+```
+
+Then reference your fonts by name in your stylesheets, pages or components:
+
+```vue
+<style>
+h1 {
+  font-family: 'FarAwayGalaxy', sans-serif;
+}
+</style>
+```
+
+### Stylesheets Distributed Through NPM
+
+You can also reference stylesheets that are distributed through npm. Let's use the popular `animate.css` library as an example.
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npm install animate.css
+```
+
+```bash [yarn]
+yarn add animate.css
+```
+
+```bash [pnpm]
+pnpm install animate.css
+```
+
+```bash [bun]
+bun install animate.css
+```
+
+::
+
+Then you can reference it directly in your pages, layouts and components:
+
+```vue [app.vue]
+<script>
+import 'animate.css'
+</script>
+
+<style>
+@import url("animate.css");
+</style>
+```
+
+The package can also be referenced as a string in the css property of your Nuxt configuration.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  css: ['animate.css']
+})
+```
+
+## External Stylesheets
+
+You can include external stylesheets in your application by adding a link element in the head section of your nuxt.config file. You can achieve this result using different methods. Note that local stylesheets can also be included like this.
+
+You can manipulate the head with the [`app.head`](/docs/api/nuxt-config#head) property of your Nuxt configuration:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  app: {
+    head: {
+      link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }]
+    }
+  }
+})
+```
+
+### Dynamically Adding Stylesheets
+
+You can use the useHead composable to dynamically set a value in your head in your code.
+
+:read-more{to="/docs/api/composables/use-head"}
+
+```ts twoslash
+useHead({
+  link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }]
+})
+```
+
+Nuxt uses `unhead` under the hood, and you can refer to its full documentation [here](https://unhead.unjs.io).
+
+### Modifying The Rendered Head With A Nitro Plugin
+
+If you need more advanced control, you can intercept the rendered html with a hook and modify the head programmatically.
+
+Create a plugin in `~/server/plugins/my-plugin.ts` like this:
+
+```ts twoslash [server/plugins/my-plugin.ts]
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('render:html', (html) => {
+    html.head.push('<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">')
+  })
+})
+```
+
+External stylesheets are render-blocking resources: they must be loaded and processed before the browser renders the page. Web pages that contain unnecessarily large styles take longer to render. You can read more about it on [web.dev](https://web.dev/defer-non-critical-css).
+
+## Using Preprocessors
+
+To use a preprocessor like SCSS, Sass, Less or Stylus, install it first.
+
+::code-group
+
+```bash [Sass & SCSS]
+npm install -D sass
+```
+
+```bash [Less]
+npm install -D less
+```
+
+```bash [Stylus]
+npm install -D stylus
+```
+
+::
+
+The natural place to write your stylesheets is the `assets` directory.
+You can then import your source files in your `app.vue` (or layouts files) using your preprocessor's syntax.
+
+```vue [pages/app.vue]
+<style lang="scss">
+@use "~/assets/scss/main.scss";
+</style>
+```
+
+Alternatively, you can use the `css` property of your Nuxt configuration.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  css: ['~/assets/scss/main.scss']
+})
+```
+
+::tip
+In both cases, the compiled stylesheets will be inlined in the HTML rendered by Nuxt.
+::
+
+If you need to inject code in pre-processed files, like a [Sass partial](https://sass-lang.com/documentation/at-rules/use#partials) with color variables, you can do so with the Vite [preprocessors options](https://vite.dev/config/shared-options.html#css-preprocessoroptions).
+
+Create some partials in your `assets` directory:
+
+::code-group{sync="preprocessor"}
+
+```scss [assets/_colors.scss]
+$primary: #49240F;
+$secondary: #E4A79D;
+```
+
+```sass [assets/_colors.sass]
+$primary: #49240F
+$secondary: #E4A79D
+```
+
+::
+
+Then in your `nuxt.config` :
+
+::code-group
+
+```ts twoslash [SCSS]
+export default defineNuxtConfig({
+  vite: {
+    css: {
+      preprocessorOptions: {
+        scss: {
+          additionalData: '@use "~/assets/_colors.scss" as *;'
+        }
+      }
+    }
+  }
+})
+```
+
+```ts twoslash [SASS]
+export default defineNuxtConfig({
+  vite: {
+    css: {
+      preprocessorOptions: {
+        sass: {
+          additionalData: '@use "~/assets/_colors.sass" as *\n'
+        }
+      }
+    }
+  }
+})
+```
+
+::
+
+Nuxt uses Vite by default. If you wish to use webpack instead, refer to each preprocessor loader [documentation](https://webpack.js.org/loaders/sass-loader).
+
+### Preprocessor Workers (Experimental)
+
+Vite has made available an [experimental option](https://vite.dev/config/shared-options.html#css-preprocessormaxworkers) which can speed up using preprocessors.
+
+You can enable this in your `nuxt.config`:
+
+```ts
+
+export default defineNuxtConfig({
+  vite: {
+    css: {
+      preprocessorMaxWorkers: true // number of CPUs minus 1
+    }
+  }
+})
+```
+
+::note
+This is an experimental option and you should refer to the Vite documentation and [provide feedback](https://github.com/vitejs/vite/discussions/15835).
+::
+
+## Single File Components (SFC) Styling
+
+One of the best things about Vue and SFC is how great it is at naturally dealing with styling. You can directly write CSS or preprocessor code in the style block of your components file, therefore you will have fantastic developer experience without having to use something like CSS-in-JS. However if you wish to use CSS-in-JS, you can find 3rd party libraries and modules that support it, such as [pinceau](https://github.com/Tahul/pinceau).
+
+You can refer to the [Vue docs](https://vuejs.org/api/sfc-css-features.html) for a comprehensive reference about styling components in SFC.
+
+### Class And Style Bindings
+
+You can leverage Vue SFC features to style your components with class and style attributes.
+
+::code-group
+
+```vue [Ref and Reactive]
+<script setup lang="ts">
+const isActive = ref(true)
+const hasError = ref(false)
+const classObject = reactive({
+  active: true,
+  'text-danger': false
+})
+</script>
+
+<template>
+  <div class="static" :class="{ active: isActive, 'text-danger': hasError }"></div>
+  <div :class="classObject"></div>
+</template>
+```
+
+```vue [Computed]
+<script setup lang="ts">
+const isActive = ref(true)
+const error = ref(null)
+
+const classObject = computed(() => ({
+  active: isActive.value && !error.value,
+  'text-danger': error.value && error.value.type === 'fatal'
+}))
+</script>
+
+<template>
+  <div :class="classObject"></div>
+</template>
+```
+
+```vue [Array]
+<script setup lang="ts">
+const isActive = ref(true)
+const errorClass = ref('text-danger')
+</script>
+
+<template>
+  <div :class="[{ active: isActive }, errorClass]"></div>
+</template>
+```
+
+```vue [Style]
+<script setup lang="ts">
+const activeColor = ref('red')
+const fontSize = ref(30)
+const styleObject = reactive({ color: 'red', fontSize: '13px' })
+</script>
+
+<template>
+  <div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>
+  <div :style="[baseStyles, overridingStyles]"></div>
+  <div :style="styleObject"></div>
+</template>
+```
+
+::
+
+Refer to the [Vue docs](https://vuejs.org/guide/essentials/class-and-style.html) for more information.
+
+### Dynamic Styles With `v-bind`
+
+You can reference JavaScript variable and expression within your style blocks with the v-bind function.
+The binding will be dynamic, meaning that if the variable value changes, the style will be updated.
+
+```vue
+<script setup lang="ts">
+const color = ref("red")
+</script>
+
+<template>
+  <div class="text">hello</div>
+</template>
+
+<style>
+.text {
+  color: v-bind(color);
+}
+</style>
+```
+
+### Scoped Styles
+
+The scoped attribute allows you to style components in isolation. The styles declared with this attribute will only apply to this component.
+
+```vue
+<template>
+  <div class="example">hi</div>
+</template>
+
+<style scoped>
+.example {
+  color: red;
+}
+</style>
+```
+
+### CSS Modules
+
+You can use [CSS Modules](https://github.com/css-modules/css-modules) with the module attribute. Access it with the injected `$style` variable.
+
+```vue
+<template>
+  <p :class="$style.red">This should be red</p>
+</template>
+
+<style module>
+.red {
+  color: red;
+}
+</style>
+```
+
+### Preprocessors Support
+
+SFC style blocks support preprocessors syntax. Vite come with built-in support for .scss, .sass, .less, .styl and .stylus files without configuration. You just need to install them first, and they will be available directly in SFC with the lang attribute.
+
+::code-group
+
+```vue [SCSS]
+<style lang="scss">
+  /* Write scss here */
+</style>
+```
+
+```vue [Sass]
+<style lang="sass">
+  /* Write sass here */
+</style>
+```
+
+```vue [LESS]
+<style lang="less">
+  /* Write less here */
+</style>
+```
+
+```vue [Stylus]
+<style lang="stylus">
+  /* Write stylus here */
+</style>
+```
+
+::
+
+You can refer to the [Vite CSS docs](https://vite.dev/guide/features.html#css) and the [@vitejs/plugin-vue docs](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue).
+For webpack users, refer to the [vue loader docs](https://vue-loader.vuejs.org).
+
+## Using PostCSS
+
+Nuxt comes with postcss built-in. You can configure it in your `nuxt.config` file.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  postcss: {
+    plugins: {
+      'postcss-nested': {},
+      'postcss-custom-media': {}
+    }
+  }
+})
+```
+
+For proper syntax highlighting in SFC, you can use the postcss lang attribute.
+
+```vue
+<style lang="postcss">
+  /* Write postcss here */
+</style>
+```
+
+By default, Nuxt comes with the following plugins already pre-configured:
+
+- [postcss-import](https://github.com/postcss/postcss-import): Improves the `@import` rule
+- [postcss-url](https://github.com/postcss/postcss-url): Transforms `url()` statements
+- [autoprefixer](https://github.com/postcss/autoprefixer): Automatically adds vendor prefixes
+- [cssnano](https://cssnano.github.io/cssnano): Minification and purge
+
+## Leveraging Layouts For Multiple Styles
+
+If you need to style different parts of your application completely differently, you can use layouts.
+Use different styles for different layouts.
+
+```vue
+<template>
+  <div class="default-layout">
+    <h1>Default Layout</h1>
+    <slot />
+  </div>
+</template>
+
+<style>
+.default-layout {
+  color: red;
+}
+</style>
+```
+
+:read-more{to="/docs/guide/directory-structure/layouts"}
+
+## Third Party Libraries And Modules
+
+Nuxt isn't opinionated when it comes to styling and provides you with a wide variety of options. You can use any styling tool that you want, such as popular libraries like [UnoCSS](https://unocss.dev) or [Tailwind CSS](https://tailwindcss.com).
+
+The community and the Nuxt team have developed plenty of Nuxt modules to make the integration easier.
+You can discover them on the [modules section](/modules) of the website.
+Here are a few modules to help you get started:
+
+- [UnoCSS](/modules/unocss): Instant on-demand atomic CSS engine
+- [Tailwind CSS](/modules/tailwindcss): Utility-first CSS framework
+- [Fontaine](https://github.com/nuxt-modules/fontaine): Font metric fallback
+- [Pinceau](https://github.com/Tahul/pinceau): Adaptable styling framework
+- [Nuxt UI](https://ui.nuxt.com): A UI Library for Modern Web Apps
+- [Panda CSS](https://panda-css.com/docs/installation/nuxt): CSS-in-JS engine that generates atomic CSS at build time
+
+Nuxt modules provide you with a good developer experience out of the box, but remember that if your favorite tool doesn't have a module, it doesn't mean that you can't use it with Nuxt! You can configure it yourself for your own project. Depending on the tool, you might need to use a [Nuxt plugin](/docs/guide/directory-structure/plugins) and/or [make your own module](/docs/guide/going-further/modules). Share them with the [community](/modules) if you do!
+
+### Easily Load Webfonts
+
+You can use [the Nuxt Google Fonts module](https://github.com/nuxt-modules/google-fonts) to load Google Fonts.
+
+If you are using [UnoCSS](https://unocss.dev/integrations/nuxt), note that it comes with a [web fonts presets](https://unocss.dev/presets/web-fonts) to conveniently load fonts from common providers, including Google Fonts and more.
+
+## Advanced
+
+### Transitions
+
+Nuxt comes with the same `<Transition>` element that Vue has, and also has support for the experimental [View Transitions API](/docs/getting-started/transitions#view-transitions-api-experimental).
+
+:read-more{to="/docs/getting-started/transitions"}
+
+### Font Advanced Optimization
+
+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.
+
+::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!
+::
+
+### LCP Advanced Optimizations
+
+You can do the following to speed-up the download of your global CSS files:
+
+- Use a CDN so the files are physically closer to your users
+- Compress your assets, ideally using Brotli
+- Use HTTP2/HTTP3 for delivery
+- Host your assets on the same domain (do not use a different subdomain)
+
+Most of these things should be done for you automatically if you're using modern platforms like Cloudflare, Netlify or Vercel.
+You can find an LCP optimization guide on [web.dev](https://web.dev/optimize-lcp).
+
+If all of your CSS is inlined by Nuxt, you can (experimentally) completely stop external CSS files from being referenced in your rendered HTML.
+You can achieve that with a hook, that you can place in a module, or in your Nuxt configuration file.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hooks: {
+    'build:manifest': (manifest) => {
+      // find the app entry, css list
+      const css = Object.values(manifest).find(options => options.isEntry)?.css
+      if (css) {
+        // start from the end of the array and go to the beginning
+        for (let i = css.length - 1; i >= 0; i--) {
+          // if it starts with 'entry', remove it from the list
+          if (css[i].startsWith('entry')) css.splice(i, 1)
+        }
+      }
+    },
+  },
+})
+```

package/1.getting-started/07.routing.md

@@ -0,0 +1,149 @@
+---
+title: 'Routing'
+description: Nuxt file-system routing creates a route for every file in the pages/ directory.
+navigation.icon: i-lucide-milestone
+---
+
+One core feature of Nuxt is the file system router. Every Vue file inside the [`pages/`](/docs/guide/directory-structure/pages) directory creates a corresponding URL (or route) that displays the contents of the file. By using dynamic imports for each page, Nuxt leverages code-splitting to ship the minimum amount of JavaScript for the requested route.
+
+## Pages
+
+Nuxt routing is based on [vue-router](https://router.vuejs.org) and generates the routes from every component created in the [`pages/` directory](/docs/guide/directory-structure/pages), based on their filename.
+
+This file system routing uses naming conventions to create dynamic and nested routes:
+
+::code-group
+
+```bash [Directory Structure]
+-| pages/
+---| about.vue
+---| index.vue
+---| posts/
+-----| [id].vue
+```
+
+```json [Generated Router File]
+{
+  "routes": [
+    {
+      "path": "/about",
+      "component": "pages/about.vue"
+    },
+    {
+      "path": "/",
+      "component": "pages/index.vue"
+    },
+    {
+      "path": "/posts/:id",
+      "component": "pages/posts/[id].vue"
+    }
+  ]
+}
+```
+
+::
+
+:read-more{to="/docs/guide/directory-structure/pages"}
+
+## Navigation
+
+The [`<NuxtLink>`](/docs/api/components/nuxt-link) component links pages between them. It renders an `<a>` tag with the `href` attribute set to the route of the page. Once the application is hydrated, page transitions are performed in JavaScript by updating the browser URL. This prevents full-page refreshes and allows for animated transitions.
+
+When a [`<NuxtLink>`](/docs/api/components/nuxt-link) enters the viewport on the client side, Nuxt will automatically prefetch components and payload (generated pages) of the linked pages ahead of time, resulting in faster navigation.
+
+```vue [pages/app.vue]
+<template>
+  <header>
+    <nav>
+      <ul>
+        <li><NuxtLink to="/about">About</NuxtLink></li>
+        <li><NuxtLink to="/posts/1">Post 1</NuxtLink></li>
+        <li><NuxtLink to="/posts/2">Post 2</NuxtLink></li>
+      </ul>
+    </nav>
+  </header>
+</template>
+```
+
+:read-more{to="/docs/api/components/nuxt-link"}
+
+## Route Parameters
+
+The [`useRoute()`](/docs/api/composables/use-route) composable can be used in a `<script setup>` block or a `setup()` method of a Vue component to access the current route details.
+
+```vue twoslash [pages/posts/[id\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+
+// When accessing /posts/1, route.params.id will be 1
+console.log(route.params.id)
+</script>
+```
+
+:read-more{to="/docs/api/composables/use-route"}
+
+## Route Middleware
+
+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.
+
+::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.
+::
+
+There are three kinds of route middleware:
+
+1. Anonymous (or inline) route middleware, which are defined directly in the pages where they are used.
+2. Named route middleware, which are placed in the [`middleware/`](/docs/guide/directory-structure/middleware) directory and will be automatically loaded via asynchronous import when used on a page. (**Note**: The route middleware name is normalized to kebab-case, so `someMiddleware` becomes `some-middleware`.)
+3. Global route middleware, which are placed in the [`middleware/` directory](/docs/guide/directory-structure/middleware) (with a `.global` suffix) and will be automatically run on every route change.
+
+Example of an `auth` middleware protecting the `/dashboard` page:
+
+::code-group
+
+```ts twoslash [middleware/auth.ts]
+function isAuthenticated(): boolean { return false }
+// ---cut---
+export default defineNuxtRouteMiddleware((to, from) => {
+  // isAuthenticated() is an example method verifying if a user is authenticated
+  if (isAuthenticated() === false) {
+    return navigateTo('/login')
+  }
+})
+```
+
+```vue twoslash [pages/dashboard.vue]
+<script setup lang="ts">
+definePageMeta({
+  middleware: 'auth'
+})
+</script>
+
+<template>
+  <h1>Welcome to your dashboard</h1>
+</template>
+```
+
+::
+
+:read-more{to="/docs/guide/directory-structure/middleware"}
+
+## Route Validation
+
+Nuxt offers route validation via the `validate` property in [`definePageMeta()`](/docs/api/utils/define-page-meta) in each page you wish to validate.
+
+The `validate` property accepts the `route` as an argument. You can return a boolean value to determine whether or not this is a valid route to be rendered with this page. If you return `false`, and another match can't be found, this will cause a 404 error. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+
+If you have a more complex use case, then you can use anonymous route middleware instead.
+
+```vue twoslash [pages/posts/[id\\].vue]
+<script setup lang="ts">
+definePageMeta({
+  validate: async (route) => {
+    // Check if the id is made up of digits
+    return typeof route.params.id === 'string' && /^\d+$/.test(route.params.id)
+  }
+})
+</script>
+```
+
+:read-more{to="/docs/api/utils/define-page-meta"}