@nuxt/docs 0.0.0 → 3.17.0

package/7.migration/6.pages-and-layouts.md

@@ -0,0 +1,233 @@
+---
+title: Pages and Layouts
+description: Learn how to migrate from Nuxt 2 to Nuxt 3 pages and layouts.
+---
+
+## `app.vue`
+
+Nuxt 3 provides a central entry point to your app via `~/app.vue`.
+
+::note
+If you don't have an `app.vue` file in your source directory, Nuxt will use its own default version.
+::
+
+This file is a great place to put any custom code that needs to be run once when your app starts up, as well as any components that are present on every page of your app. For example, if you only have one layout, you can move this to `app.vue` instead.
+
+:read-more{to="/docs/guide/directory-structure/app"}
+
+:link-example{to="/docs/examples/hello-world"}
+
+### Migration
+
+Consider creating an `app.vue` file and including any logic that needs to run once at the top-level of your app. You can check out [an example here](/docs/guide/directory-structure/app).
+
+## Layouts
+
+If you are using layouts in your app for multiple pages, there is only a slight change required.
+
+In Nuxt 2, the `<Nuxt>` component is used within a layout to render the current page. In Nuxt 3, layouts use slots instead, so you will have to replace that component with a `<slot />`. This also allows advanced use cases with named and scoped slots. [Read more about layouts](/docs/guide/directory-structure/layouts).
+
+You will also need to change how you define the layout used by a page using the `definePageMeta` compiler macro. Layouts will be kebab-cased. So `layouts/customLayout.vue` becomes `custom-layout` when referenced in your page.
+
+### Migration
+
+1. Replace `<Nuxt />` with `<slot />`
+    ```diff [layouts/custom.vue]
+      <template>
+        <div id="app-layout">
+          <main>
+    -       <Nuxt />
+    +       <slot />
+          </main>
+        </div>
+      </template>
+    ```
+2. Use [`definePageMeta`](/docs/api/utils/define-page-meta) to select the layout used by your page.
+    ```diff [pages/index.vue]
+    + <script setup>
+    + definePageMeta({
+    +   layout: 'custom'
+    + })
+    - <script>
+    - export default {
+    -   layout: 'custom'
+    - }
+      </script>
+    ```
+3. Move `~/layouts/_error.vue` to `~/error.vue`. See [the error handling docs](/docs/getting-started/error-handling). If you want to ensure that this page uses a layout, you can use [`<NuxtLayout>`](/docs/guide/directory-structure/layouts) directly within `error.vue`:
+    ```vue [error.vue]
+    <template>
+      <div>
+        <NuxtLayout name="default">
+          <!-- -->
+        </NuxtLayout>
+      </div>
+    </template>
+    ```
+
+## Pages
+
+Nuxt 3 ships with an optional `vue-router` integration triggered by the existence of a [`pages/`](/docs/guide/directory-structure/pages) directory in your source directory. If you only have a single page, you may consider instead moving it to `app.vue` for a lighter build.
+
+### Dynamic Routes
+
+The format for defining dynamic routes in Nuxt 3 is slightly different from Nuxt 2, so you may need to rename some of the files within `pages/`.
+
+1. Where you previously used `_id` to define a dynamic route parameter you now use `[id]`.
+2. Where you previously used `_.vue` to define a catch-all route, you now use `[...slug].vue`.
+
+### Nested Routes
+
+In Nuxt 2, you will have defined any nested routes (with parent and child components) using `<Nuxt>` and `<NuxtChild>`. In Nuxt 3, these have been replaced with a single `<NuxtPage>` component.
+
+### Page Keys and Keep-alive Props
+
+If you were passing a custom page key or keep-alive props to `<Nuxt>`, you will now use `definePageMeta` to set these options.
+
+:read-more{to="/docs/guide/directory-structure/pages#special-metadata"}
+
+### Page and Layout Transitions
+
+If you have been defining transitions for your page or layout directly in your component options, you will now need to use `definePageMeta` to set the transition. Since Vue 3, [-enter and -leave CSS classes have been renamed](https://v3-migration.vuejs.org/breaking-changes/transition.html). The `style` prop from `<Nuxt>` no longer applies to transition when used on `<slot>`, so move the styles to your `-active` class.
+
+:read-more{to="/docs/getting-started/transitions"}
+
+### Migration
+
+1. Rename any pages with dynamic parameters to match the new format.
+2. Update `<Nuxt>` and `<NuxtChild>` to be `<NuxtPage>`.
+3. If you're using the Composition API, you can also migrate `this.$route` and `this.$router` to use [`useRoute`](/docs/api/composables/use-route) and [`useRouter`](/docs/api/composables/use-router)  composables.
+
+#### Example: Dynamic Routes
+
+::code-group
+
+``` [Nuxt 2]
+- URL: /users
+- Page: /pages/users/index.vue
+
+- URL: /users/some-user-name
+- Page: /pages/users/_user.vue
+- Usage: params.user
+
+- URL: /users/some-user-name/edit
+- Page: /pages/users/_user/edit.vue
+- Usage: params.user
+
+- URL: /users/anything-else
+- Page: /pages/users/_.vue
+- Usage: params.pathMatch
+```
+
+``` [Nuxt 3]
+- URL: /users
+- Page: /pages/users/index.vue
+
+- URL: /users/some-user-name
+- Page: /pages/users/[user].vue
+- Usage: params.user
+
+- URL: /users/some-user-name/edit
+- Page: /pages/users/[user]/edit.vue
+- Usage: params.user
+
+- URL: /users/anything-else
+- Page: /pages/users/[...slug].vue
+- Usage: params.slug
+```
+
+::
+
+#### Example: Nested Routes and `definePageMeta`
+
+::code-group
+
+```vue [Nuxt 2]
+<template>
+  <div>
+    <NuxtChild keep-alive :keep-alive-props="{ exclude: ['modal'] }" :nuxt-child-key="$route.slug" />
+  </div>
+</template>
+
+<script>
+export default {
+  transition: 'page' // or { name: 'page' }
+}
+</script>
+```
+
+```vue [Nuxt 3]
+<template>
+  <div>
+    <NuxtPage />
+  </div>
+</template>
+
+<script setup lang="ts">
+// This compiler macro works in both <script> and <script setup>
+definePageMeta({
+  // you can also pass a string or a computed property
+  key: route => route.slug,
+  transition: {
+    name: 'page',
+  },
+  keepalive: {
+    exclude: ['modal']
+  },
+})
+</script>
+```
+
+::
+
+## `<NuxtLink>` Component
+
+Most of the syntax and functionality are the same for the global [NuxtLink](/docs/api/components/nuxt-link) component. If you have been using the shortcut `<NLink>` format, you should update this to use `<NuxtLink>`.
+
+`<NuxtLink>` is now a drop-in replacement for _all_ links, even external ones. You can read more about it, and how to extend it to provide your own link component.
+
+:read-more{to="/docs/api/components/nuxt-link"}
+
+## Programmatic Navigation
+
+When migrating from Nuxt 2 to Nuxt 3, you will have to update how you programmatically navigate your users. In Nuxt 2, you had access to the underlying Vue Router with `this.$router`. In Nuxt 3, you can use the `navigateTo()` utility method which allows you to pass a route and parameters to Vue Router.
+
+::warning
+Ensure to always `await` on [`navigateTo`](/docs/api/utils/navigate-to) or chain its result by returning from functions.
+::
+
+::code-group
+
+```vue [Nuxt 2]
+<script>
+export default {
+  methods: {
+    navigate(){
+      this.$router.push({
+        path: '/search',
+        query: {
+          name: 'first name',
+          type: '1'
+        }
+      })
+    }
+  }
+}
+</script>
+```
+
+```vue [Nuxt 3]
+<script setup lang="ts">
+function navigate(){
+  return navigateTo({
+    path: '/search',
+    query: {
+      name: 'first name',
+      type: '1'
+    }
+  })
+}
+</script>
+```
+
+::

package/7.migration/7.component-options.md

@@ -0,0 +1,156 @@
+---
+title: Component Options
+description: 'Learn how to migrate from Nuxt 2 components options to Nuxt 3 composables.'
+---
+
+## `asyncData` and `fetch`
+
+Nuxt 3 provides new options for [fetching data from an API](/docs/getting-started/data-fetching).
+
+<!-- TODO: Intro to <script setup> -->
+<!-- TODO: Mention about options compatibility with asyncData -->
+
+### Isomorphic Fetch
+
+In Nuxt 2 you might use `@nuxtjs/axios` or `@nuxt/http` to fetch your data - or just the polyfilled global `fetch`.
+
+In Nuxt 3 you can use a globally available `fetch` method that has the same API as [the Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) or [`$fetch`](/docs/api/utils/dollarfetch) method which is using [unjs/ofetch](https://github.com/unjs/ofetch). It has a number of benefits, including:
+
+1. It will handle 'smartly' making [direct API calls](/docs/guide/concepts/server-engine#direct-api-calls) if it's running on the server, or making a client-side call to your API if it's running on the client. (It can also handle calling third-party APIs.)
+
+2. Plus, it comes with convenience features including automatically parsing responses and stringifying data.
+
+You can read more [about direct API calls](/docs/guide/concepts/server-engine#direct-api-calls) or [fetching data](/docs/getting-started/data-fetching).
+
+### Composables
+
+Nuxt 3 provides new composables for fetching data: [`useAsyncData`](/docs/api/composables/use-async-data) and `useFetch`. They each have 'lazy' variants (`useLazyAsyncData` and `useLazyFetch`), which do not block client-side navigation.
+
+In Nuxt 2, you'd fetch your data in your component using a syntax similar to:
+
+```ts
+export default {
+  async asyncData({ params, $http }) {
+    const post = await $http.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
+    return { post }
+  },
+  // or alternatively
+  fetch () {
+    this.post = await $http.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
+  }
+}
+```
+
+Within your methods and templates, you could use the `post` variable similar how you'd use any other piece of data provided by your component.
+
+With Nuxt 3, you can perform this data fetching using composables in your `setup()` method or `<script setup>` tag:
+
+```vue
+<script setup lang="ts">
+// Define params wherever, through `defineProps()`, `useRoute()`, etc.
+const { data: post, refresh } = await useAsyncData('post', () => $fetch(`https://api.nuxtjs.dev/posts/${params.id}`) )
+// Or instead - useFetch is a convenience wrapper around useAsyncData when you're just performing a simple fetch
+const { data: post, refresh } = await useFetch(`https://api.nuxtjs.dev/posts/${params.id}`)
+</script>
+```
+
+You can now use `post` inside of your Nuxt 3 template, or call `refresh` to update the data.
+
+::note
+Despite the names, [`useFetch`](/docs/api/composables/use-fetch) is not a direct replacement of the `fetch()` hook. Rather, [`useAsyncData`](/docs/api/composables/use-async-data) replaces both hooks and is more customizable; it can do more than simply fetching data from an endpoint. [`useFetch`](/docs/api/composables/use-fetch) is a convenience wrapper around [`useAsyncData`](/docs/api/composables/use-async-data) for simply fetching data from an endpoint.
+::
+
+### Migration
+
+1. Replace the `asyncData` hook with [`useAsyncData`](/docs/api/composables/use-async-data) or [`useFetch`](/docs/api/composables/use-fetch) in your page/component.
+2. Replace the `fetch` hook with [`useAsyncData`](/docs/api/composables/use-async-data) or [`useFetch`](/docs/api/composables/use-fetch) in your component.
+
+## `head`
+
+:read-more{to="/docs/migration/meta"}
+
+## `key`
+
+You can now define a key within the [`definePageMeta`](/docs/api/utils/define-page-meta) compiler macro.
+
+```diff [pages/index.vue]
+- <script>
+- export default {
+-   key: 'index'
+-   // or a method
+-   // key: route => route.fullPath
+- }
++ <script setup>
++ definePageMeta({
++   key: 'index'
++   // or a method
++   // key: route => route.fullPath
++ })
+</script>
+```
+
+## `layout`
+
+:read-more{to="/docs/migration/pages-and-layouts"}
+
+## `loading`
+
+This feature is not yet supported in Nuxt 3.
+
+## `middleware`
+
+:read-more{to="/docs/migration/plugins-and-middleware"}
+
+## `scrollToTop`
+
+This feature is not yet supported in Nuxt 3. If you want to overwrite the default scroll behavior of `vue-router`, you can do so in `~/app/router.options.ts` (see [docs](/docs/guide/recipes/custom-routing#router-options)) for more info.
+Similar to `key`, specify it within the [`definePageMeta`](/docs/api/utils/define-page-meta) compiler macro.
+
+```diff [pages/index.vue]
+- <script>
+- export default {
+-   scrollToTop: false
+- }
++ <script setup>
++ definePageMeta({
++   scrollToTop: false
++ })
+</script>
+```
+
+## `transition`
+
+:read-more{to="/docs/getting-started/transitions"}
+
+## `validate`
+
+The validate hook in Nuxt 3 only accepts a single argument, the `route`. Just as in Nuxt 2, you can return a boolean value. If you return false and another match can't be found, this will mean a 404. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+
+```diff [pages/users/[id\\].vue]
+- <script>
+- export default {
+-   async validate({ params }) {
+-     return /^\d+$/.test(params.id)
+-   }
+- }
++ <script setup>
++ definePageMeta({
++   validate: async (route) => {
++     const nuxtApp = useNuxtApp()
++     return /^\d+$/.test(route.params.id)
++   }
++ })
+  </script>
+```
+
+## `watchQuery`
+
+This is not supported in Nuxt 3. Instead, you can directly use a watcher to trigger refetching data.
+
+```vue [pages/users/[id\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const { data, refresh } = await useFetch('/api/user')
+watch(() => route.query, () => refresh())
+</script>
+```

package/7.migration/8.runtime-config.md

@@ -0,0 +1,58 @@
+---
+title: Runtime Config
+description: 'Learn how to migrate from Nuxt 2 to Nuxt 3 runtime config.'
+---
+
+If you wish to reference environment variables within your Nuxt 3 app, you will need to use runtime config.
+
+When referencing these variables within your components, you will have to use the [`useRuntimeConfig`](/docs/api/composables/use-runtime-config) composable in your setup method (or Nuxt plugin).
+
+In the `server/` portion of your app, you can use [`useRuntimeConfig`](/docs/api/composables/use-runtime-config) without any import.
+
+:read-more{to="/docs/guide/going-further/runtime-config"}
+
+## Migration
+
+1. Add any environment variables that you use in your app to the `runtimeConfig` property of the `nuxt.config` file.
+2. Migrate `process.env` to [`useRuntimeConfig`](/docs/api/composables/use-runtime-config) throughout the Vue part of your app.
+
+::code-group
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    // Private config that is only available on the server
+    apiSecret: '123',
+    // Config within public will be also exposed to the client
+    public: {
+      apiBase: '/api'
+    }
+  },
+})
+```
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const config = useRuntimeConfig()
+
+// instead of process.env you will now access config.public.apiBase
+console.log(config.public.apiBase)
+</script>
+```
+
+```ts [server/api/hello.ts]
+export default defineEventhandler((event) => {
+  const config = useRuntimeConfig(event)
+  // In server, you can now access config.apiSecret, in addition to config.public
+  console.log(config.apiSecret)
+  console.log(config.public.apiBase)
+})
+```
+
+```ini [.env]
+# Runtime config values are automatically replaced by matching environment variables at runtime
+NUXT_API_SECRET=api_secret_token
+NUXT_PUBLIC_API_BASE=https://nuxtjs.org
+```
+
+::

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-present - Nuxt Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+---
+navigation: false
+---
+
+# Nuxt Docs
+
+This repository contains the documentation of Nuxt hosted on <https://nuxt.com/docs>
+
+## Contributing
+
+Have a look at <https://github.com/nuxt/nuxt.com> to run the website locally.

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@nuxt/docs",
-  "version": "0.0.0",
+  "version": "3.17.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuxt/nuxt.git",
+    "directory": "docs"
+  },
+  "homepage": "https://nuxt.com",
+  "description": "Documentation for Nuxt in raw markdown",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./*": "./*"
+  },
   "files": [
-    "dist"
-  ],
-  "author": "Daniel Roe <daniel@roe.dev>"
+    "**/*.md",
+    "**/*.yml"
+  ]
 }