Docs for experimental font optimization adjustFontFallbacks

docs/basic-features/font-optimization.md

@@ -65,6 +65,58 @@ module.exports = {
 }
 ```
 
+## Optimize CLS for Fonts
+
+Next.js can reduce the Cumulative Layout Shift ([CLS](https://web.dev/cls/)) of your website by adjusting the size of your fallback fonts and inlining the font CSS.
+
+Sites that load fonts with `font-display: swap` usually suffer from ([CLS](https://web.dev/cls/)) when the web font loads and replaces the fallback font. This is due to differences in height, width, and alignment between the main and fallback fonts, which is common even if the CSS font size is the same.
+
+Next.js can reduce CLS automatically by adjusting the size of the fallback font to match that of the main font using font override metric properties such as `size-adjust`, `ascent-override`, `descent-override`, and `line-gap-override`.
+
+To enable this experimental feature, update your `next.config.js` with the following configuration:
+
+```js
+module.exports = {
+  experimental: {
+    adjustFontFallbacks: true,
+  },
+}
+```
+
+When enabled, Next.js will generate a fallback font definition with the correct size overrides in the format `{fontName} Fallback`.
+For example, the font `Inter` will generate the fallback font `Inter Fallback`.
+
+You can then use the fallback font in your stylesheets such as the following:
+
+```css
+body {
+  font-family: 'Inter', 'Inter Fallback', sans-serif;
+}
+```
+
+> **NOTE**: Next.js currently supports one cross-platform serif font ('Times New Roman') and one cross-platform sans-serif font ('Arial')
+
+The final output will include the fallback override definition.
+
+```html
+// Injected into index.html during build/render
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<style data-href="https://fonts.googleapis.com/css2?family=Inter&display=swap">
+  @font-face{
+    font-family: 'Inter';
+    font-style:normal
+    ...
+  }
+
+  @font-face {
+    font-family: 'Inter Fallback',
+    src: local('Arial');
+    ascent-override: 96.975%;
+    ...
+  }
+</style>
+```
+
 ## Related
 
 For more information on what to do next, we recommend the following sections:

packages/next/build/webpack-config.ts

@@ -216,7 +216,7 @@ export function getDefineEnv({
     'process.env.__NEXT_STRICT_MODE': JSON.stringify(config.reactStrictMode),
     'process.env.__NEXT_REACT_ROOT': JSON.stringify(hasReactRoot),
     'process.env.__NEXT_OPTIMIZE_FONTS': JSON.stringify(
-      !dev && config.optimizeFonts
+      config.optimizeFonts && !dev
     ),
     'process.env.__NEXT_OPTIMIZE_CSS': JSON.stringify(
       config.experimental.optimizeCss && !dev

packages/next/server/font-utils.ts

@@ -117,7 +117,7 @@ export function calculateOverrideValues(font: string, fontMetrics: any) {
 }
 
 function calculateOverrideCSS(font: string, fontMetrics: any) {
-  const fontName = font.toLowerCase().trim().replace(/ /g, '-')
+  const fontName = font.trim()
 
   const { ascent, descent, lineGap, fallbackFont } = calculateOverrideValues(
     font,
@@ -126,7 +126,7 @@ function calculateOverrideCSS(font: string, fontMetrics: any) {
 
   return `
     @font-face {
-      font-family: "${fontName}-fallback";
+      font-family: "${fontName} Fallback";
       ascent-override: ${ascent}%;
       descent-override: ${descent}%;
       line-gap-override: ${lineGap}%;

test/integration/font-optimization/test/index.test.js

@@ -359,14 +359,14 @@ describe('Font Optimization', () => {
       )
       expect(inlineStyle.length).toBe(1)
       expect(inlineStyle.html()).toContain(
-        '@font-face{font-family:"roboto-fallback";ascent-override:92.77%;descent-override:24.41%;line-gap-override:0.00%;src:local("Arial")}'
+        '@font-face{font-family:"Roboto Fallback";ascent-override:92.77%;descent-override:24.41%;line-gap-override:0.00%;src:local("Arial")}'
       )
       expect(inlineStyleMultiple.length).toBe(1)
       expect(inlineStyleMultiple.html()).toContain(
-        '@font-face{font-family:"libre-baskerville-fallback";ascent-override:97.00%;descent-override:27.00%;line-gap-override:0.00%;src:local("Times New Roman")}'
+        '@font-face{font-family:"Libre Baskerville Fallback";ascent-override:97.00%;descent-override:27.00%;line-gap-override:0.00%;src:local("Times New Roman")}'
       )
       expect(inlineStyleMultiple.html()).toContain(
-        '@font-face{font-family:"open-sans-fallback";ascent-override:106.88%;descent-override:29.30%;line-gap-override:0.00%;src:local("Arial")}'
+        '@font-face{font-family:"Open Sans Fallback";ascent-override:106.88%;descent-override:29.30%;line-gap-override:0.00%;src:local("Arial")}'
       )
     })
   })