Add documentation on Font Optimization. (#24572)

vercel · Apr 28, 2021 · 9721374 · 9721374
1 parent 2d6b560
commit 9721374
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 0 deletions.
diff --git a/docs/basic-features/font-optimization.md b/docs/basic-features/font-optimization.md
@@ -0,0 +1,88 @@
+---
+description: Next.js supports built-in web font optimization to inline font CSS. Learn more here.
+---
+
+# Font Optimization
+
+Since version **10.2**, Next.js has built-in web font optimization.
+
+By default, Next.js will automatically inline font CSS at build time, eliminating an extra round trip to fetch font declarations. This results in improvements to [First Contentful Paint (FCP)](https://web.dev/fcp/) and [Largest Contentful Paint (LCP)](https://vercel.com/blog/core-web-vitals#largest-contentful-paint). For example:
+
+```js
+// Before
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter"
+  rel="stylesheet"
+/>
+
+// After
+<style data-href="https://fonts.googleapis.com/css2?family=Inter">
+  @font-face{font-family:'Inter';font-style:normal...
+</style>
+```
+
+## Usage
+
+To add a web font to your Next.js application, override `next/head`. For example, you can add a font to a specific page:
+
+```js
+// pages/index.js
+
+import Head from 'next/head'
+
+export default function IndexPage() {
+  return (
+    <div>
+      <Head>
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter"
+          rel="stylesheet"
+        />
+      </Head>
+      <p>Hello world!</p>
+    </div>
+  )
+}
+```
+
+or to your entire application with a [Custom `Document`](/docs/advanced-features/custom-document.md).
+
+```js
+// pages/_document.js
+
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+  render() {
+    return (
+      <Html>
+        <Head>
+          <link
+            href="https://fonts.googleapis.com/css2?family=Inter"
+            rel="stylesheet"
+          />
+        </Head>
+        <body>
+          <Main />
+          <NextScript />
+        </body>
+      </Html>
+    )
+  }
+}
+
+export default MyDocument
+```
+
+Automatic Webfont Optimization currently supports Google Fonts, with support for other font providers coming soon. We're also planning to add control over [loading strategies](https://github.com/vercel/next.js/issues/21555) and `font-display` values.
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+  <a href="/docs/advanced-features/custom-document.md">
+    <b>Custom Document</b>
+    <small>Learn how to augment your application's html and body tags.</small>
+  </a>
+</div>
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -25,6 +25,10 @@
               "title": "Image Optimization",
               "path": "/docs/basic-features/image-optimization.md"
             },
+            {
+              "title": "Font Optimization",
+              "path": "/docs/basic-features/font-optimization.md"
+            },
             {
               "title": "Static File Serving",
               "path": "/docs/basic-features/static-file-serving.md"