Unverified Commit 5788f602 authored by Hannes Bornö's avatar Hannes Bornö Committed by GitHub

Improve @next/font error handling (#43298)

Use `WellKnownErrorsPlugin` when formatting `@next/font` errors.

The error handling is different for expected errors (like validation
errors) and unknown ones. If the error is expected it just displays the
formatted error message. If it's an unknown error it will also display
the stacktrace, and in case the versions of `@next/font` and `next` are
different it will encourage you to try to update them both.

Removes the usage of `error-loader` when importing from
`pages/_document.js`, handle that case with `WellKnownErrorsPlugin` as
well.

The current warning when using different versions is removed. If the
versions are incompatible you'll get an error in the overlay instead.

## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have a helpful link attached, see
[`contributing.md`](https://github.com/vercel/next.js/blob/canary/contributing.md)

## 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
- [ ] 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)
parent ec7609e2
......@@ -13,6 +13,7 @@ import {
getUrl,
validateData,
} from './utils'
import { nextFontError } from '../utils'
const cssCache = new Map<string, Promise<string>>()
const fontCache = new Map<string, any>()
......@@ -104,7 +105,7 @@ const downloadGoogleFonts: FontLoader = async ({
cssCache.delete(url)
}
if (fontFaceDeclarations === null) {
throw new Error(`Failed to fetch \`${fontFamily}\` from Google Fonts.`)
nextFontError(`Failed to fetch \`${fontFamily}\` from Google Fonts.`)
}
// CSS Variables may be set on a body tag, ignore them to keep the CSS module pure
......@@ -151,9 +152,7 @@ const downloadGoogleFonts: FontLoader = async ({
fontCache.delete(googleFontFileUrl)
}
if (fontFileBuffer === null) {
throw new Error(
`Failed to fetch \`${fontFamily}\` from Google Fonts.`
)
nextFontError(`Failed to fetch \`${fontFamily}\` from Google Fonts.`)
}
const ext = /\.(woff|woff2|eot|ttf|otf)$/.exec(googleFontFileUrl)![1]
......
import fs from 'fs'
// @ts-ignore
import fetch from 'next/dist/compiled/node-fetch'
import { nextFontError } from '../utils'
import fontData from './font-data.json'
const allowedDisplayValues = ['auto', 'block', 'swap', 'fallback', 'optional']
......@@ -32,7 +33,7 @@ export function validateData(functionName: string, data: any): FontOptions {
subsets,
} = data[0] || ({} as any)
if (functionName === '') {
throw new Error(`@next/font/google has no default export`)
nextFontError(`@next/font/google has no default export`)
}
const fontFamily = functionName.replace(/_/g, ' ')
......@@ -40,7 +41,7 @@ export function validateData(functionName: string, data: any): FontOptions {
const fontFamilyData = (fontData as any)[fontFamily]
const fontWeights = fontFamilyData?.weights
if (!fontWeights) {
throw new Error(`Unknown font \`${fontFamily}\``)
nextFontError(`Unknown font \`${fontFamily}\``)
}
const fontStyles = fontFamilyData.styles
......@@ -56,7 +57,7 @@ export function validateData(functionName: string, data: any): FontOptions {
if (fontWeights.includes('variable')) {
weights.push('variable')
} else {
throw new Error(
nextFontError(
`Missing weight for font \`${fontFamily}\`.\nAvailable weights: ${formatValues(
fontWeights
)}`
......@@ -65,14 +66,14 @@ export function validateData(functionName: string, data: any): FontOptions {
}
if (weights.length > 1 && weights.includes('variable')) {
throw new Error(
nextFontError(
`Unexpected \`variable\` in weight array for font \`${fontFamily}\`. You only need \`variable\`, it includes all available weights.`
)
}
weights.forEach((selectedWeight) => {
if (!fontWeights.includes(selectedWeight)) {
throw new Error(
nextFontError(
`Unknown weight \`${selectedWeight}\` for font \`${fontFamily}\`.\nAvailable weights: ${formatValues(
fontWeights
)}`
......@@ -90,7 +91,7 @@ export function validateData(functionName: string, data: any): FontOptions {
styles.forEach((selectedStyle) => {
if (!fontStyles.includes(selectedStyle)) {
throw new Error(
nextFontError(
`Unknown style \`${selectedStyle}\` for font \`${fontFamily}\`.\nAvailable styles: ${formatValues(
fontStyles
)}`
......@@ -99,7 +100,7 @@ export function validateData(functionName: string, data: any): FontOptions {
})
if (!allowedDisplayValues.includes(display)) {
throw new Error(
nextFontError(
`Invalid display value \`${display}\` for font \`${fontFamily}\`.\nAvailable display values: ${formatValues(
allowedDisplayValues
)}`
......@@ -107,7 +108,7 @@ export function validateData(functionName: string, data: any): FontOptions {
}
if (weights[0] !== 'variable' && axes) {
throw new Error('Axes can only be defined for variable fonts')
nextFontError('Axes can only be defined for variable fonts')
}
return {
......@@ -191,7 +192,7 @@ export async function fetchCSSFromGoogleFonts(url: string, fontFamily: string) {
const mockFile = require(process.env.NEXT_FONT_GOOGLE_MOCKED_RESPONSES)
mockedResponse = mockFile[url]
if (!mockedResponse) {
throw new Error('Missing mocked response for URL: ' + url)
nextFontError('Missing mocked response for URL: ' + url)
}
}
......@@ -208,7 +209,7 @@ export async function fetchCSSFromGoogleFonts(url: string, fontFamily: string) {
})
if (!res.ok) {
throw new Error(`Failed to fetch font \`${fontFamily}\`.\nURL: ${url}`)
nextFontError(`Failed to fetch font \`${fontFamily}\`.\nURL: ${url}`)
}
cssResponse = await res.text()
......@@ -252,10 +253,10 @@ export function getFontAxes(
.map(({ tag }) => tag)
.filter((tag) => tag !== 'wght')
if (defineAbleAxes.length === 0) {
throw new Error(`Font \`${fontFamily}\` has no definable \`axes\``)
nextFontError(`Font \`${fontFamily}\` has no definable \`axes\``)
}
if (!Array.isArray(selectedVariableAxes)) {
throw new Error(
nextFontError(
`Invalid axes value for font \`${fontFamily}\`, expected an array of axes.\nAvailable axes: ${formatValues(
defineAbleAxes
)}`
......@@ -263,7 +264,7 @@ export function getFontAxes(
}
selectedVariableAxes.forEach((key) => {
if (!defineAbleAxes.some((tag) => tag === key)) {
throw new Error(
nextFontError(
`Invalid axes value \`${key}\` for font \`${fontFamily}\`.\nAvailable axes: ${formatValues(
defineAbleAxes
)}`
......
......@@ -5,7 +5,7 @@ import type { AdjustFontFallback, FontLoader } from 'next/font'
import { promisify } from 'util'
import { validateData } from './utils'
import { calculateFallbackFontValues } from '../utils'
import { calculateFallbackFontValues, nextFontError } from '../utils'
const NORMAL_WEIGHT = 400
const BOLD_WEIGHT = 700
......@@ -27,7 +27,7 @@ function getDistanceFromNormalWeight(weight?: string) {
.map(getWeightNumber)
if (Number.isNaN(firstWeight) || Number.isNaN(secondWeight)) {
throw new Error(
nextFontError(
`Invalid weight value in src array: \`${weight}\`.\nExpected \`normal\`, \`bold\` or a number.`
)
}
......
import { nextFontError } from '../utils'
const allowedDisplayValues = ['auto', 'block', 'swap', 'fallback', 'optional']
const formatValues = (values: string[]) =>
......@@ -30,7 +32,7 @@ type FontOptions = {
}
export function validateData(functionName: string, fontData: any): FontOptions {
if (functionName) {
throw new Error(`@next/font/local has no named exports`)
nextFontError(`@next/font/local has no named exports`)
}
let {
src,
......@@ -45,7 +47,7 @@ export function validateData(functionName: string, fontData: any): FontOptions {
} = fontData || ({} as any)
if (!allowedDisplayValues.includes(display)) {
throw new Error(
nextFontError(
`Invalid display value \`${display}\`.\nAvailable display values: ${formatValues(
allowedDisplayValues
)}`
......@@ -53,21 +55,21 @@ export function validateData(functionName: string, fontData: any): FontOptions {
}
if (!src) {
throw new Error('Missing required `src` property')
nextFontError('Missing required `src` property')
}
if (!Array.isArray(src)) {
src = [{ path: src, weight, style }]
} else {
if (src.length === 0) {
throw new Error('Unexpected empty `src` array.')
nextFontError('Unexpected empty `src` array.')
}
}
src = src.map((fontFile: any) => {
const ext = /\.(woff|woff2|eot|ttf|otf)$/.exec(fontFile.path)?.[1]
if (!ext) {
throw new Error(`Unexpected file \`${fontFile.path}\``)
nextFontError(`Unexpected file \`${fontFile.path}\``)
}
return {
......@@ -88,7 +90,7 @@ export function validateData(functionName: string, fontData: any): FontOptions {
'font-style',
].includes(declaration?.prop)
) {
throw new Error(`Invalid declaration prop: \`${declaration.prop}\``)
nextFontError(`Invalid declaration prop: \`${declaration.prop}\``)
}
})
}
......
......@@ -55,3 +55,9 @@ export function calculateFallbackFontValues(
sizeAdjust: formatOverrideValue(sizeAdjust),
}
}
export function nextFontError(message: string): never {
const err = new Error(message)
err.name = 'NextFontError'
throw err
}
......@@ -10,7 +10,6 @@ import {
getGlobalImportError,
getGlobalModuleImportError,
getLocalModuleImportError,
getFontLoaderDocumentImportError,
} from './messages'
import { getPostCssPlugins } from './plugins'
import { nonNullable } from '../../../../../lib/non-nullable'
......@@ -191,25 +190,6 @@ export const css = curry(async function css(
// Font loaders cannot be imported in _document.
fontLoaders?.forEach(([fontLoaderPath, fontLoaderOptions]) => {
fns.push(
loader({
oneOf: [
markRemovable({
test: fontLoaderPath,
// Use a loose regex so we don't have to crawl the file system to
// find the real file name (if present).
issuer: /pages[\\/]_document\./,
use: {
loader: 'error-loader',
options: {
reason: getFontLoaderDocumentImportError(),
},
},
}),
],
})
)
// Matches the resolved font loaders noop files to run next-font-loader
fns.push(
loader({
......
......@@ -31,9 +31,3 @@ export function getCustomDocumentError() {
'pages/_document.js'
)}. Please move global styles to ${chalk.cyan('pages/_app.js')}.`
}
export function getFontLoaderDocumentImportError() {
return `Font loader error:\nFont loaders ${chalk.bold(
'cannot'
)} be used within ${chalk.cyan('pages/_document.js')}.`
}
......@@ -2,16 +2,37 @@ import type { FontLoader } from '../../../../font'
import { promises as fs } from 'fs'
import path from 'path'
import chalk from 'next/dist/compiled/chalk'
import loaderUtils from 'next/dist/compiled/loader-utils3'
import postcssFontLoaderPlugn from './postcss-font-loader'
import { promisify } from 'util'
import chalk from 'next/dist/compiled/chalk'
import { CONFIG_FILES } from '../../../../shared/lib/constants'
export default async function nextFontLoader(this: any) {
const fontLoaderSpan = this.currentTraceSpan.traceChild('next-font-loader')
return fontLoaderSpan.traceAsyncFn(async () => {
const callback = this.async()
// next-swc next_font_loaders turns each font loader call into JSON
const {
path: relativeFilePathFromRoot,
import: functionName,
arguments: data,
variableName,
} = JSON.parse(this.resourceQuery.slice(1))
// Throw error if @next/font is used in _document.js
if (/pages[\\/]_document\./.test(relativeFilePathFromRoot)) {
const err = new Error(
`${chalk.bold('Cannot')} be used within ${chalk.cyan(
'pages/_document.js'
)}.`
)
err.name = 'NextFontError'
callback(err)
return
}
const {
isDev,
isServer,
......@@ -53,14 +74,6 @@ export default async function nextFontLoader(this: any) {
return outputPath
}
// next-swc next_font_loaders turns each font loader call into JSON
const {
path: relativeFilePathFromRoot,
import: functionName,
arguments: data,
variableName,
} = JSON.parse(this.resourceQuery.slice(1))
try {
const fontLoader: FontLoader = require(path.join(
this.resourcePath,
......@@ -122,11 +135,6 @@ export default async function nextFontLoader(this: any) {
fontFamilyHash,
})
} catch (err: any) {
err.stack = false
err.message = `Font loader error:\n${err.message}`
err.message += `
${chalk.cyan(`Location: ${relativeFilePathFromRoot}`)}`
callback(err)
}
})
......
import { SimpleWebpackError } from './simpleWebpackError'
export function getNextFontError(
err: Error,
module: any
): SimpleWebpackError | false {
try {
const resourceResolveData = module.resourceResolveData
if (resourceResolveData.descriptionFileData.name !== '@next/font') {
return false
}
// Parse the query and get the path of the file where the font function was called.
// provided by next-swc next_font_loaders
const file = JSON.parse(resourceResolveData.query.slice(1)).path
if (err.name === 'NextFontError') {
// Known error thrown by @next/font, display the error message
return new SimpleWebpackError(
file,
`\`@next/font\` error:\n${err.message}`
)
} else {
// Unknown error thrown by @next/font
// It might be becuase of incompatible versions of @next/font and next are being used, or it might be a bug
// eslint-disable-next-line import/no-extraneous-dependencies
const nextFontVersion = require('@next/font/package.json').version
const nextVersion = require('next/package.json').version
let message = `An error occured in \`@next/font\`.`
// Using different versions of @next/font and next, add message that it's possibly fixed by updating both
if (nextFontVersion !== nextVersion) {
message += `\n\nYou might be using incompatible version of \`@next/font\` (${nextFontVersion}) and \`next\` (${nextVersion}). Try updating both \`@next/font\` and \`next\`, if the error still persists it may be a bug.`
}
message += `\n\n${err.stack}`
return new SimpleWebpackError(file, message)
}
} catch {
return false
}
}
......@@ -9,6 +9,7 @@ import { getNotFoundError, getImageError } from './parseNotFoundError'
import { SimpleWebpackError } from './simpleWebpackError'
import isError from '../../../../lib/is-error'
import { getRscError } from './parseRSC'
import { getNextFontError } from './parseNextFontError'
function getFileData(
compilation: webpack.Compilation,
......@@ -102,5 +103,10 @@ export async function getModuleBuildError(
return rsc
}
const nextFont = getNextFontError(err, input.module)
if (nextFont !== false) {
return nextFont
}
return false
}
......@@ -171,19 +171,10 @@ function formatMessage(message, verbose, importTraceNote) {
function formatWebpackMessages(json, verbose) {
const formattedErrors = json.errors.map(function (message) {
let importTraceNote
if (
message &&
message.message &&
/Font loader error:/.test(message.message)
) {
return message.message.slice(
message.message.indexOf('Font loader error:')
)
}
return formatMessage(message, verbose, importTraceNote)
const isUnknownNextFontError = message.message.includes(
'An error occured in `@next/font`.'
)
return formatMessage(message, isUnknownNextFontError || verbose)
})
const formattedWarnings = json.warnings.map(function (message) {
return formatMessage(message, verbose)
......
......@@ -95,13 +95,7 @@ export function setHttpClientAndAgentOptions(config: {
function setFontLoaderDefaults(config: NextConfigComplete) {
try {
// eslint-disable-next-line import/no-extraneous-dependencies
const nextFontVersion = require('@next/font/package.json').version
const nextVersion = require('next/package.json').version
if (nextFontVersion !== nextVersion) {
Log.warn(
`Different versions of @next/font (${nextFontVersion}) and next (${nextVersion}) detected. This may lead to unexpected behavior.`
)
}
require('@next/font/package.json')
const googleFontLoader = {
loader: '@next/font/google',
......
......@@ -5,14 +5,8 @@ import webdriver from 'next-webdriver'
import { join } from 'path'
describe('font-loader-in-document-error', () => {
const isDev = (global as any).isNextDev
let next: NextInstance
if (!isDev) {
it('should only run on next dev', () => {})
return
}
beforeAll(async () => {
next = await createNext({
files: {
......@@ -25,12 +19,13 @@ describe('font-loader-in-document-error', () => {
})
afterAll(() => next.destroy())
test('font loader inside _document', async () => {
test('@next/font inside _document', async () => {
const browser = await webdriver(next.appPort, '/')
expect(await hasRedbox(browser, true)).toBeTrue()
expect(await getRedboxSource(browser)).toMatch(/Font loaders/)
expect(await getRedboxSource(browser)).toInclude(
'Font loaders cannot be used within pages/_document.js'
)
expect(await getRedboxSource(browser)).toMatchInlineSnapshot(`
"pages/_document.js
\`@next/font\` error:
Cannot be used within pages/_document.js."
`)
})
})
import { createNext, FileRef } from 'e2e-utils'
import { NextInstance } from 'test/lib/next-modes/base'
import { join } from 'path'
import webdriver from 'next-webdriver'
import { getRedboxSource, hasRedbox } from 'next-test-utils'
describe('incompatible-versions', () => {
let next: NextInstance
beforeAll(async () => {
next = await createNext({
files: {
pages: new FileRef(join(__dirname, 'incompatible-versions/pages')),
},
// Make sure @next/font 13.0.0 is installed from npm - not the version from the monorepo
installCommand: 'pnpm add @next/font@13.0.0',
})
})
afterAll(() => next.destroy())
it('should warn that you might be using incompatible versions of next and @next/font on unknown error', async () => {
const browser = await webdriver(next.url, '/')
expect(await hasRedbox(browser, true)).toBeTrue()
const errorMessage = await getRedboxSource(browser)
// @next/font error info
expect(errorMessage).toInclude('pages/index.js')
expect(errorMessage).toInclude('An error occured in `@next/font`.')
expect(errorMessage).toInclude(
'You might be using incompatible version of `@next/font` (13.0.0) and `next`'
)
// Error
expect(errorMessage).toInclude(
'TypeError: Cannot read properties of undefined'
)
// Stacktrace
expect(errorMessage).toInclude('at fetchFonts')
})
})
import localFont from '@next/font/local'
const font = localFont({ src: './fake-font.woff2' })
export default function Index() {
return <p className={font.className}>Hello world!</p>
}
import { createNext, FileRef } from 'e2e-utils'
import { NextInstance } from 'test/lib/next-modes/base'
import { join } from 'path'
import webdriver from 'next-webdriver'
import { getRedboxSource, hasRedbox } from 'next-test-utils'
describe('validation-error', () => {
let next: NextInstance
beforeAll(async () => {
next = await createNext({
files: {
pages: new FileRef(join(__dirname, 'validation-error/pages')),
},
dependencies: {
'@next/font': 'canary',
},
})
})
afterAll(() => next.destroy())
it('show a @next/font error when input is wrong', async () => {
const browser = await webdriver(next.url, '/')
expect(await hasRedbox(browser, true)).toBeTrue()
expect(await getRedboxSource(browser)).toMatchInlineSnapshot(`
"pages/index.js
\`@next/font\` error:
Missing required \`src\` property"
`)
})
})
import localFont from '@next/font/local'
const font = localFont()
export default function Index() {
return <p className={font.className}>Hello world!</p>
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment