Skip to content
This repository has been archived by the owner on Apr 6, 2023. It is now read-only.

Commit

Permalink
Merge branch 'main' into docs/client-data-fetching-note
Browse files Browse the repository at this point in the history
  • Loading branch information
pi0 authored Sep 3, 2022
2 parents 1f4fdf7 + 664e570 commit dfc5db4
Show file tree
Hide file tree
Showing 40 changed files with 1,014 additions and 835 deletions.
3 changes: 0 additions & 3 deletions docs/content/2.guide/2.features/10.app-config.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# App Config

::StabilityEdge
::

Nuxt 3 provides an `app.config` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).

::alert{type=warning}
Expand Down
3 changes: 0 additions & 3 deletions docs/content/2.guide/3.directory-structure/16.app.config.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,6 @@ head.title: Nuxt App Config

# Nuxt App Config

::StabilityEdge
::

You can easily provide runtime app configuration using `app.config.ts` file. It can have either of `.ts`, `.js`, or `.mjs` extensions.

```ts [app.config.ts]
Expand Down
3 changes: 0 additions & 3 deletions docs/content/3.api/1.composables/prefetch-components.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# `prefetchComponents`

::StabilityEdge
::

Nuxt provides composables and utilities to give you fine-grained control over prefetching and preloading components.

> Prefetching component downloads the code in the background, this is based on the assumption that the component will likely be used for rendering, enabling the component to load instantly if and when the user requests it. The component is downloaded and cached for anticipated future use without the user making an explicit request for it.
Expand Down
3 changes: 0 additions & 3 deletions docs/content/3.api/1.composables/preload-components.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# `preloadComponents`

::StabilityEdge
::

Nuxt provides composables and utilities to give you fine-grained control over prefetching and preloading components.

> Preloading components loads components that your page will need very soon, which you want to start loading early in rendering lifecycle. This ensures they are available earlier and are less likely to block the page's render, improving performance.
Expand Down
3 changes: 0 additions & 3 deletions docs/content/3.api/1.composables/update-app-config.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# `updateAppConfig`

::StabilityEdge
::

Updates [app config](/guide/features/app-config) using deep assignment. Existing (nested) properties will be preserved.

**Usage:**
Expand Down
3 changes: 0 additions & 3 deletions docs/content/3.api/1.composables/use-app-config.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
# `useAppConfig`

::StabilityEdge
::

Access [app config](/guide/features/app-config):

**Usage:**
Expand Down
3 changes: 1 addition & 2 deletions docs/content/3.api/1.composables/use-fetch.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,7 @@ type AsyncData<DataT> = {
* `headers`: Request headers.
* `baseURL`: Base URL for the request.
* **Options (from `useAsyncData`)**:
* `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests, if not provided, it will be generated based on the `url` and fetch options.
* `lazy`: Whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`).
* `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests, if not provided, it will be generated based on the static code location where `useAyncData` is used.
* `server`: Whether to fetch the data on the server (defaults to `true`).
* `default`: A factory function to set the default value of the data, before the async function resolves - particularly useful with the `lazy: true` option.
* `pick`: Only pick specified keys in this array from the `handler` function result.
Expand Down
223 changes: 188 additions & 35 deletions docs/content/3.api/1.composables/use-head.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,201 @@
# `useHead`

::ReadMore{link="/guide/features/head-management"}
Nuxt provides the `useHead` composable to add and customize the head properties of individual pages of your Nuxt app. `useHead` uses [@vueuse/head](https://github.com/vueuse/head) under the hood.

Nuxt provides a composable to update the head properties of your page with an [`MetaObject`](/api/composables/use-head/#metaobject) of meta properties with keys corresponding to meta tags:
::alert{icon=👉}
**`useHead` must be placed within the `setup` function**.
::

`title`, `base`, `script`, `noscript`, `style`, `meta` and `link`, as well as `htmlAttrs` and `bodyAttrs`. Alternatively, you can pass a function returning the object for reactive metadata.
## Type

```js
useHead(options: MetaObject)
```ts
useHead(meta: Computable<MetaObject>): void

interface MetaObject extends Record<string, any> {
charset?: string
viewport?: string
meta?: Array<Record<string, any>>
link?: Array<Record<string, any>>
style?: Array<Record<string, any>>
script?: Array<Record<string, any>>
noscript?: Array<Record<string, any>>
titleTemplate?: string | ((title: string) => string)
title?: string
bodyAttrs?: Record<string, any>
htmlAttrs?: Record<string, any>
}
```

::alert{icon=👉}
**`useHead` only works during `setup`**.
Application-wide configuration of the head metadata is possible through [nuxt.config](/api/configuration/nuxt.config#head), or by placing the `useHead` in the `app.vue` file.

::alert{type=info}
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.
::

## Example

The example below changes the website's title in the `meta` and inserts a Google Font using the `link` property.

```js
export default {
setup () {
useHead({
meta: [
{ name: 'title' content: 'Nuxt 3 - The Hybrid Vue Framework' }
],
link: [
{ rel: 'preconnect', href: 'https://fonts.googleapis.com' },
{ rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' },
{ rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', crossorigin: '' },
]
})
}
}
## Parameters

### `meta`

**Type**: `MetaObject`

An object accepting the following head metadata:

- `charset`

**Type**: `string`

**Default**: `utf-8`

Specifies character encoding for the HTML document.

- `viewport`

**Type**: `string`

**Default**: `width=device-width, initial-scale=1`

Configures the viewport (the user's visible area of a web page).

- `meta`

**Type**: `Array<Record<string, any>>`

**Default**: `width=device-width, initial-scale=1`

Each element in the array is mapped to a newly-created `<meta>` tag, where object properties are mapped to the corresponding attributes.

- `link`

**Type**: `Array<Record<string, any>>`

Each element in the array is mapped to a newly-created `<link>` tag, where object properties are mapped to the corresponding attributes.

- `style`

**Type**: `Array<Record<string, any>>`

Each element in the array is mapped to a newly-created `<style>` tag, where object properties are mapped to the corresponding attributes.

- `script`

**Type**: `Array<Record<string, any>>`

Each element in the array is mapped to a newly-created `<script>` tag, where object properties are mapped to the corresponding attributes.

- `noscript`

**Type**: `Array<Record<string, any>>`

Each element in the array is mapped to a newly-created `<noscript>` tag, where object properties are mapped to the corresponding attributes.

- `titleTemplate`

**Type**: `string` | `((title: string) => string)`

Configures dynamic template to customize the page title on an individual page.

- `title`

**Type**: `string`

Sets static page title on an individual page.

- `bodyAttrs`

**Type**: `Record<string, any>`

Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute.

- `htmlAttrs`

**Type**: `Record<string, any>`

Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute.

## Examples

### Customize Metadata

The example below changes the website's `title` and `description` using `meta` option of the `useHead` composable:

```vue
<script setup>
const title = ref('My App')
const description = ref('My amazing Nuxt app')
useHead({
title,
meta: [
{
name: 'description',
content: description
}
]
})
</script>
```

### Add Dynamic Title

In the example below, `titleTemplate` is set either as a string with the `%s` placeholder or as a `function`, which allows greater flexibility in setting the page title dynamically for each route of your Nuxt app:

```vue [app.vue]
<script setup>
useHead({
// as a string,
// where `%s` is replaced with the title
titleTemplate: '%s - Site Title',
// ... or as a function
titleTemplate: (productCategory) => {
return productCategory
? `${productCategory} - Site Title`
: 'Site Title'
}
})
</script>
```

## `MetaObject`
`nuxt.config` is also used as an alternative way of setting the page title. However, `nuxt.config` does not allow the page title to be dynamic. Therefore, it is recommended to use `titleTemplate` in the `app.vue` file to add a dynamic title, which is then applied to all routes of your Nuxt app.

### Add External CSS

The example below inserts Google Fonts using the `link` property of the `useHead` composable:

```vue
<script setup>
useHead({
link: [
{
rel: 'preconnect',
href: 'https://fonts.googleapis.com'
},
{
rel: 'stylesheet',
href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
crossorigin: ''
}
]
})
</script>
```

### Add Third-party Script

The example below inserts a third-party script using the `script` property of the `useHead` composable:

```vue
<script setup>
useHead({
script: [
{
src: 'https://third-party-script.com',
body: true
}
]
})
</script>
```

* **charset**: the character encoding in which the document is encoded => `<meta charset="<value>" />` (default: `'utf-8'`)
* **viewport**: configuration of the viewport (the area of the window in which web content can be seen) => `<meta name="viewport" content="<value>" />` (default: `'width=device-width, initial-scale=1'`)
* **meta**: array, each item maps to a newly-created `<meta>` element, where object properties map to attributes.
* **link**: array, each item maps to a newly-created `<link>` element, where object properties map to attributes.
* **style**: array, each item maps to a newly-created `<style>` element, where object properties map to attributes.
* **script**: array, each item maps to a newly-created `<script>` element, where object properties map to attributes.
* **noscript**: array, each item maps to a newly-created `<noscript>` element, where object properties map to attributes.
You can use the `body: true` option to add the above script at the end of the `<body>` tag.

All elements in the meta object are optional. You can also pass only single values.
:ReadMore{link="/guide/features/head-management"}
1 change: 0 additions & 1 deletion docs/content/3.api/4.advanced/1.hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ Hook | Arguments | Environment | Description
`app:error` | `err` | Server & Client | Called when a fatal error occurs.
`app:error:cleared` | `{ redirect? }` | Server & Client | Called when a fatal error occurs.
`app:data:refresh` | `keys?` | Server & Client | (internal)
`meta:register` | `metaRenderers` | Server & Client | (internal)
`vue:setup` | - | Server & Client | (internal)
`vue:error` | `err, target, info` | Server & Client | Called when a vue error propages to the root component. [Learn More](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
`app:rendered` | `renderContext` | Server | Called when SSR rendering is done.
Expand Down
2 changes: 1 addition & 1 deletion lerna.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"version": "3.0.0-rc.8",
"version": "3.0.0-rc.9",
"npmClient": "yarn",
"useWorkspaces": true,
"conventionalCommits": true,
Expand Down
12 changes: 6 additions & 6 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,27 +44,27 @@
"nuxt": "link:./packages/nuxt",
"nuxt3": "link:./packages/nuxt",
"vite": "~3.0.9",
"unbuild": "^0.8.9"
"unbuild": "^0.8.10"
},
"devDependencies": {
"@nuxtjs/eslint-config-typescript": "^11.0.0",
"@types/node": "^16.11.56",
"@types/rimraf": "^3",
"@unocss/reset": "^0.45.13",
"case-police": "^0.5.9",
"changelogen": "^0.1.1",
"@unocss/reset": "^0.45.14",
"case-police": "^0.5.10",
"changelogen": "^0.3.0",
"eslint": "^8.23.0",
"eslint-plugin-jsdoc": "^39.3.6",
"execa": "^6.1.0",
"expect-type": "^0.13.0",
"globby": "^13.1.2",
"jiti": "^1.14.0",
"lerna": "^5.4.3",
"lerna": "^5.5.0",
"markdownlint-cli": "^0.32.2",
"pathe": "^0.3.5",
"rimraf": "^3.0.2",
"typescript": "^4.8.2",
"unbuild": "^0.8.9",
"unbuild": "^0.8.10",
"vitest": "~0.19.1",
"vue-tsc": "^0.39.5"
},
Expand Down
6 changes: 3 additions & 3 deletions packages/kit/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@nuxt/kit",
"version": "3.0.0-rc.8",
"version": "3.0.0-rc.9",
"repository": "nuxt/framework",
"license": "MIT",
"type": "module",
Expand All @@ -13,8 +13,8 @@
"prepack": "unbuild"
},
"dependencies": {
"@nuxt/schema": "3.0.0-rc.8",
"c12": "^0.2.9",
"@nuxt/schema": "3.0.0-rc.9",
"c12": "^0.2.10",
"consola": "^2.15.3",
"defu": "^6.1.0",
"globby": "^13.1.2",
Expand Down
21 changes: 0 additions & 21 deletions packages/kit/src/auto-import.ts

This file was deleted.

Loading

0 comments on commit dfc5db4

Please sign in to comment.