Skip to content

Commit

Permalink
Docs: next/font updates (#46159)
Browse files Browse the repository at this point in the history 
Update `next/font` docs pages for version 13.2, rename `@next/font` to `next/font` and remove installation instructions. 

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] [e2e](https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs) tests added
- [x] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have a helpful link attached, see [`contributing.md`](https://github.com/vercel/next.js/blob/canary/contributing.md)

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm build && pnpm lint`
- [ ] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)


Co-authored-by: JJ Kasper <[email protected]>
  • Loading branch information
@delbaoliveira @ijjk
delbaoliveira and ijjk authored Feb 24, 2023
1 parent 9df7df1 commit e91de8e
Show file tree
Hide file tree
Showing 5 changed files with 50 additions and 57 deletions.
61 changes: 31 additions & 30 deletions docs/api-reference/next/font.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,20 @@
---
description: Optimizing loading web fonts with the built-in `@next/font` loaders.
description: Optimizing loading web fonts with the built-in `next/font` loaders.
---

# @next/font
# next/font

<details>
<summary><b>Version History</b></summary>

| Version | Changes |
| --------- | ----------------------- |
| `v13.0.0` | `@next/font` was added. |
| Version | Changes |
| --------- | --------------------------------------------------------------------- |
| `v13.2.0` | `@next/font` renamed to `next/font`. Installation no longer required. |
| `v13.0.0` | `next/font` was added. |

</details>

This API reference will help you understand how to use `@next/font/google` and `@next/font/local`. For features and usage, please see the [Optimizing Fonts](/docs/basic-features/font-optimization.md) page.
This API reference will help you understand how to use `next/font/google` and `next/font/local`. For features and usage, please see the [Optimizing Fonts](/docs/basic-features/font-optimization.md) page.

### Font function arguments

Expand All @@ -37,7 +38,7 @@ For usage, review [Google Fonts](/docs/basic-features/font-optimization.md#googl

The path of the font file as a string or an array of objects (with type `Array<{path: string, weight?: string, style?: string}>`) relative to the directory where the font loader function is called.

Used in `@next/font/local`
Used in `next/font/local`

- Required

Expand All @@ -52,9 +53,9 @@ Examples:
The font [`weight`](https://fonts.google.com/knowledge/glossary/weight) with the following possibilities:

- A string with possible values of the weights available for the specific font or a range of values if it's a [variable](https://fonts.google.com/variablefonts) font
- An array of weight values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `@next/font/google` only.
- An array of weight values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `next/font/google` only.

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

- Required if the font being used is **not** [variable](https://fonts.google.com/variablefonts)

Expand All @@ -69,23 +70,23 @@ Examples:
The font [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) with the following possibilities:

- A string [value](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style#values) with default value of `'normal'`
- An array of style values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `@next/font/google` only.
- An array of style values if the font is not a [variable google font](https://fonts.google.com/variablefonts). It applies to `next/font/google` only.

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

- Optional

Examples:

- `style: 'italic'`: A string - it can be `normal` or `italic` for `@next/font/google`
- `style: 'oblique'`: A string - it can take any value for `@next/font/local` but is expected to come from [standard font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)
- `style: ['italic','normal']`: An array of 2 values for `@next/font/google` - the values are from `normal` and `italic`
- `style: 'italic'`: A string - it can be `normal` or `italic` for `next/font/google`
- `style: 'oblique'`: A string - it can take any value for `next/font/local` but is expected to come from [standard font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)
- `style: ['italic','normal']`: An array of 2 values for `next/font/google` - the values are from `normal` and `italic`

### `subsets`

The font [`subsets`](https://fonts.google.com/knowledge/glossary/subsetting) defined by an array of string values with the names of each subset you would like to be [preloaded](/docs/basic-features/font-optimization#specifying-a-subset). Fonts specified via `subsets` will have a link preload tag injected into the head when the [`preload`](/docs/api-reference/next/font.md#preload) option is true, which is the default.

Used in `@next/font/google`
Used in `next/font/google`

- Optional

Expand All @@ -97,7 +98,7 @@ Examples:

Some variable fonts have extra `axes` that can be included. By default, only the font weight is included to keep the file size down. The possible values of `axes` depend on the specific font.

Used in `@next/font/google`
Used in `next/font/google`

- Optional

Expand All @@ -109,19 +110,19 @@ Examples:

The font [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) with possible string [values](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display#values) of `'auto'`, `'block'`, `'swap'`, `'fallback'` or `'optional'` with default value of `'swap'`.

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

- Optional

Examples:

- `display: 'swap'`: A string assigned to the `swap` value
- `display: 'optional'`: A string assigned to the `optional` value

### `preload`

A boolean value that specifies whether the font should be [preloaded](/docs/basic-features/font-optimization#preloading) or not. The default is `true`.

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

- Optional

Expand All @@ -135,31 +136,31 @@ The fallback font to use if the font cannot be loaded. An array of strings of fa

- Optional

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

Examples:

- `fallback: ['system-ui', 'arial']`: An array setting the fallback fonts to `system-ui` or `arial`

### `adjustFontFallback`

- For `@next/font/google`: A boolean value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The default is `true`.
- For `@next/font/local`: A string or boolean `false` value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The possible values are `'Arial'`, `'Times New Roman'` or `false`. The default is `'Arial'`.
- For `next/font/google`: A boolean value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The default is `true`.
- For `next/font/local`: A string or boolean `false` value that sets whether an automatic fallback font should be used to reduce [Cumulative Layout Shift](https://web.dev/cls/). The possible values are `'Arial'`, `'Times New Roman'` or `false`. The default is `'Arial'`.

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

- Optional

Examples:

- `adjustFontFallback: false`: for ``@next/font/google`
- `adjustFontFallback: 'Times New Roman'`: for `@next/font/local`
- `adjustFontFallback: false`: for ``next/font/google`
- `adjustFontFallback: 'Times New Roman'`: for `next/font/local`

### `variable`

A string value to define the CSS variable name to be used if the style is applied with the [CSS variable method](#css-variables).

Used in `@next/font/google` and `@next/font/local`
Used in `next/font/google` and `next/font/local`

- Optional

Expand All @@ -171,7 +172,7 @@ Examples:

An array of font face [descriptor](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face#descriptors) key-value pairs that define the generated `@font-face` further.

Used in `@next/font/local`
Used in `next/font/local`

- Optional

Expand Down Expand Up @@ -211,7 +212,7 @@ In addition to importing the font, also import the CSS file where the CSS variab

```js
// pages/index.js
import { Inter } from '@next/font/google'
import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'

const inter = Inter({
Expand Down Expand Up @@ -251,8 +252,8 @@ Then, specify your font definitions as follows:
```ts
// styles/fonts.ts
import { Inter, Lora, Source_Sans_Pro } from '@next/font/google';
import localFont from '@next/font/local';
import { Inter, Lora, Source_Sans_Pro } from 'next/font/google';
import localFont from 'next/font/local';
// define your variable fonts
const inter = Inter();
Expand Down
38 changes: 15 additions & 23 deletions docs/basic-features/font-optimization.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,30 @@
---
description: Optimizing loading web fonts with the built-in `@next/font` loaders.
description: Optimizing loading web fonts with the built-in `next/font` loaders.
---

# Optimizing Fonts

[**`@next/font`**](/docs/api-reference/next/font.md) will automatically optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance.
[**`next/font`**](/docs/api-reference/next/font.md) will automatically optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance.

> **🎥 Watch:** Learn more about how to use `@next/font` → [YouTube (6 minutes)](https://www.youtube.com/watch?v=L8_98i_bMMA).
> **🎥 Watch:** Learn more about how to use `next/font` → [YouTube (6 minutes)](https://www.youtube.com/watch?v=L8_98i_bMMA).
## Overview

`@next/font` includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with zero layout shift, thanks to the underlying CSS `size-adjust` property used.
`next/font` includes **built-in automatic self-hosting** for _any_ font file. This means you can optimally load web fonts with zero layout shift, thanks to the underlying CSS `size-adjust` property used.

This new font system also allows you to conveniently use all Google Fonts with performance and privacy in mind. CSS and font files are downloaded at build time and self-hosted with the rest of your static assets. **No requests are sent to Google by the browser.**

## Usage

To get started, install `@next/font`:

```bash
npm install @next/font
```

### Google Fonts

Automatically self-host any Google Font. Fonts are included in the deployment and served from the same domain as your deployment. **No requests are sent to Google by the browser.**

Import the font you would like to use from `@next/font/google` as a function. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.
To get started, import the font you would like to use from `next/font/google` as a function. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.

To use the font in all your pages, add it to [`_app.js` file](https://nextjs.org/docs/advanced-features/custom-app) under `/pages` as shown below:

```js
// pages/_app.js
import { Inter } from '@next/font/google'
import { Inter } from 'next/font/google'

// If loading a variable font, you don't need to specify the font weight
const inter = Inter({ subsets: ['latin'] })
Expand All @@ -50,7 +42,7 @@ If you can't use a variable font, you will **need to specify a weight**:

```js
// pages/_app.js
import { Roboto } from '@next/font/google'
import { Roboto } from 'next/font/google'

const roboto = Roboto({
weight: '400',
Expand Down Expand Up @@ -82,7 +74,7 @@ You can also use the font without a wrapper and `className` by injecting it insi

```js
// pages/_app.js
import { Inter } from '@next/font/google'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

Expand All @@ -106,7 +98,7 @@ To use the font on a single page, add it to the specific page as shown below:

```js
// pages/index.js
import { Inter } from '@next/font/google'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

Expand Down Expand Up @@ -139,7 +131,7 @@ This can be done in 2 ways:
module.exports = {
experimental: {
fontLoaders: [
{ loader: '@next/font/google', options: { subsets: ['latin'] } },
{ loader: 'next/font/google', options: { subsets: ['latin'] } },
],
},
}
Expand All @@ -151,11 +143,11 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontgoogle) f

### Local Fonts

Import `@next/font/local` and specify the `src` of your local font file. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.
Import `next/font/local` and specify the `src` of your local font file. We recommend using [**variable fonts**](https://fonts.google.com/variablefonts) for the best performance and flexibility.

```js
// pages/_app.js
import localFont from '@next/font/local'
import localFont from 'next/font/local'

// Font files can be colocated inside of `pages`
const myFont = localFont({ src: './my-font.woff2' })
Expand Down Expand Up @@ -202,13 +194,13 @@ View the [Font API Reference](/docs/api-reference/next/font.md#nextfontlocal) fo

## With Tailwind CSS

`@next/font` can be used with Tailwind CSS through a [CSS variable](/docs/api-reference/next/font#css-variables).
`next/font` can be used with Tailwind CSS through a [CSS variable](/docs/api-reference/next/font#css-variables).

In the example below, we use the font `Inter` from `@next/font/google` (You can use any font from Google or Local Fonts). Load your font with the `variable` option to define your CSS variable name and assign it to `inter`. Then, use `inter.variable` to add the CSS variable to your HTML document.
In the example below, we use the font `Inter` from `next/font/google` (You can use any font from Google or Local Fonts). Load your font with the `variable` option to define your CSS variable name and assign it to `inter`. Then, use `inter.variable` to add the CSS variable to your HTML document.

```js
// pages/_app.js
import { Inter } from '@next/font/google'
import { Inter } from 'next/font/google'

const inter = Inter({
subsets: ['latin'],
Expand Down
2 changes: 1 addition & 1 deletion docs/manifest.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,7 @@
"path": "/docs/api-reference/next/server.md"
},
{
"title": "@next/font",
"title": "next/font",
"path": "/docs/api-reference/next/font.md"
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/testing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -341,7 +341,7 @@ module.exports = createJestConfig(customJestConfig)
Under the hood, `next/jest` is automatically configuring Jest for you, including:

- Setting up `transform` using [SWC](https://nextjs.org/docs/advanced-features/compiler)
- Auto mocking stylesheets (`.css`, `.module.css`, and their scss variants), image imports and [`@next/font`](https://nextjs.org/docs/basic-features/font-optimization)
- Auto mocking stylesheets (`.css`, `.module.css`, and their scss variants), image imports and [`next/font`](https://nextjs.org/docs/basic-features/font-optimization)
- Loading `.env` (and all variants) into `process.env`
- Ignoring `node_modules` from test resolving and transforms
- Ignoring `.next` from test resolving
Expand Down
4 changes: 2 additions & 2 deletions docs/upgrading.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,9 @@ The behavior of [`next/script`](/docs/api-reference/next/script.md) has been upd

### Font Optimization

Previously, Next.js helped you optimize fonts by inlining font CSS. Version 13 introduces the new [`@next/font`](/docs/basic-features/font-optimization.md) module which gives you the ability to customize your font loading experience while still ensuring great performance and privacy.
Previously, Next.js helped you optimize fonts by inlining font CSS. Version 13 introduces the new [`next/font`](/docs/basic-features/font-optimization.md) module which gives you the ability to customize your font loading experience while still ensuring great performance and privacy.

See [Optimizing Fonts](/docs/basic-features/font-optimization.md) to learn how to use `@next/font`.
See [Optimizing Fonts](/docs/basic-features/font-optimization.md) to learn how to use `next/font`.

## Upgrading to 12.2

Expand Down

0 comments on commit e91de8e

Please sign in to comment.