feat: allow experimentally disabling local fallbacks (#225)

docs/content/1.get-started/2.configuration.md

@@ -237,6 +237,8 @@ export default defineNuxtConfig({
     experimental: {
       // Required for TailwindCSS v4. You can enable support for processing CSS variables for font family names. This may have a performance impact.
       processCSSVariables: true
+      // Defines whether to enable adding local fallbacks. Default is `false`.
+      disableLocalFallbacks: true
     }
   }
 })

src/module.ts

@@ -14,9 +14,10 @@ import fontsource from './providers/fontsource'
 
 import { FontFamilyInjectionPlugin, type FontFaceResolution } from './plugins/transform'
 import { generateFontFace } from './css/render'
+import { addLocalFallbacks } from './css/parse'
 import type { GenericCSSFamily } from './css/parse'
 import { setupPublicAssetStrategy } from './assets'
-import type { FontFamilyManualOverride, FontFamilyProviderOverride, FontProvider, ModuleHooks, ModuleOptions } from './types'
+import type { FontFamilyManualOverride, FontFamilyProviderOverride, FontProvider, ModuleHooks, ModuleOptions, NormalizedFontFaceData } from './types'
 import { setupDevtoolsConnection } from './devtools'
 import { logger } from './logger'
 
@@ -80,6 +81,7 @@ export default defineNuxtModule<ModuleOptions>({
     devtools: true,
     experimental: {
       processCSSVariables: false,
+      disableLocalFallbacks: false,
     },
     defaults: {},
     assets: {
@@ -153,16 +155,23 @@ export default defineNuxtModule<ModuleOptions>({
     const { normalizeFontData } = setupPublicAssetStrategy(options.assets)
     const { exposeFont } = setupDevtoolsConnection(nuxt.options.dev && !!options.devtools)
 
+    function addFallbacks(fontFamily: string, font: NormalizedFontFaceData[]) {
+      if (options.experimental?.disableLocalFallbacks) {
+        return font
+      }
+      return addLocalFallbacks(fontFamily, font)
+    }
+
     async function resolveFontFaceWithOverride(fontFamily: string, override?: FontFamilyManualOverride | FontFamilyProviderOverride, fallbackOptions?: { fallbacks: string[], generic?: GenericCSSFamily }): Promise<FontFaceResolution | undefined> {
       const fallbacks = override?.fallbacks || normalizedDefaults.fallbacks[fallbackOptions?.generic || 'sans-serif']
 
       if (override && 'src' in override) {
-        const fonts = normalizeFontData({
+        const fonts = addFallbacks(fontFamily, normalizeFontData({
           src: override.src,
           display: override.display,
           weight: override.weight,
           style: override.style,
-        })
+        }))
         exposeFont({
           type: 'manual',
           fontFamily,
@@ -197,15 +206,16 @@ export default defineNuxtModule<ModuleOptions>({
             logger.warn(`Could not produce font face declaration from \`${override.provider}\` for font family \`${fontFamily}\`.`)
             return
           }
+          const fontsWithLocalFallbacks = addFallbacks(fontFamily, fonts)
           exposeFont({
             type: 'override',
             fontFamily,
             provider: override.provider,
-            fonts,
+            fonts: fontsWithLocalFallbacks,
           })
           return {
             fallbacks: result.fallbacks || defaults.fallbacks,
-            fonts,
+            fonts: fontsWithLocalFallbacks,
           }
         }
 
@@ -221,15 +231,16 @@ export default defineNuxtModule<ModuleOptions>({
             // Rewrite font source URLs to be proxied/local URLs
             const fonts = normalizeFontData(result.fonts)
             if (fonts.length > 0) {
+              const fontsWithLocalFallbacks = addFallbacks(fontFamily, fonts)
               exposeFont({
                 type: 'auto',
                 fontFamily,
                 provider: key,
-                fonts,
+                fonts: fontsWithLocalFallbacks,
               })
               return {
                 fallbacks: result.fallbacks || defaults.fallbacks,
-                fonts,
+                fonts: fontsWithLocalFallbacks,
               }
             }
             if (override) {

src/providers/adobe.ts

@@ -1,7 +1,7 @@
 import { hash } from 'ohash'
 
 import type { FontProvider, ResolveFontFacesOptions } from '../types'
-import { extractFontFaceData, addLocalFallbacks } from '../css/parse'
+import { extractFontFaceData } from '../css/parse'
 import { cachedData } from '../cache'
 import { $fetch } from '../fetch'
 import { logger } from '../logger'
@@ -119,7 +119,7 @@ async function getFontDetails(family: string, variants: ResolveFontFacesOptions)
     // TODO: Not sure whether this css_names array always has a single element. Still need to investigate.
     const cssName = font.css_names[0] ?? family.toLowerCase().split(' ').join('-')
 
-    return addLocalFallbacks(family, extractFontFaceData(css, cssName))
+    return extractFontFaceData(css, cssName)
   }
 
   return []

src/providers/bunny.ts

@@ -1,7 +1,7 @@
 import { hash } from 'ohash'
 
 import type { FontProvider, ResolveFontFacesOptions } from '../types'
-import { extractFontFaceData, addLocalFallbacks } from '../css/parse'
+import { extractFontFaceData } from '../css/parse'
 import { cachedData } from '../cache'
 import { $fetch } from '../fetch'
 import { logger } from '../logger'
@@ -84,5 +84,5 @@ async function getFontDetails(family: string, variants: ResolveFontFacesOptions)
   })
 
   // TODO: support subsets
-  return addLocalFallbacks(family, extractFontFaceData(css))
+  return extractFontFaceData(css)
 }

src/providers/fontshare.ts

@@ -1,7 +1,7 @@
 import { hash } from 'ohash'
 
 import type { FontProvider, ResolveFontFacesOptions } from '../types'
-import { extractFontFaceData, addLocalFallbacks } from '../css/parse'
+import { extractFontFaceData } from '../css/parse'
 import { cachedData } from '../cache'
 import { $fetch } from '../fetch'
 import { logger } from '../logger'
@@ -115,5 +115,5 @@ async function getFontDetails(family: string, variants: ResolveFontFacesOptions)
   const css = await fontAPI<string>(`/css?f[]=${font.slug + '@' + numbers.join(',')}`)
 
   // TODO: support subsets and axes
-  return addLocalFallbacks(family, extractFontFaceData(css))
+  return extractFontFaceData(css)
 }

src/providers/fontsource.ts

@@ -1,7 +1,6 @@
 import { hash } from 'ohash'
 
 import type { FontProvider, NormalizedFontFaceData, ResolveFontFacesOptions } from '../types'
-import { addLocalFallbacks } from '../css/parse'
 import { cachedData } from '../cache'
 import { $fetch } from '../fetch'
 import { logger } from '../logger'
@@ -152,5 +151,5 @@ async function getFontDetails(family: string, variants: ResolveFontFacesOptions)
     }
   }
 
-  return addLocalFallbacks(family, fontFaceData)
+  return fontFaceData
 }

src/providers/google.ts

@@ -1,7 +1,7 @@
 import { hash } from 'ohash'
 
 import type { FontProvider, ResolveFontFacesOptions } from '../types'
-import { extractFontFaceData, addLocalFallbacks } from '../css/parse'
+import { extractFontFaceData } from '../css/parse'
 import { cachedData } from '../cache'
 import { $fetch } from '../fetch'
 import { logger } from '../logger'
@@ -96,7 +96,7 @@ async function getFontDetails(family: string, variants: ResolveFontFacesOptions)
   }
 
   // TODO: support subsets
-  return addLocalFallbacks(family, extractFontFaceData(css))
+  return extractFontFaceData(css)
 }
 
 const userAgents = {

src/providers/googleicons.ts

@@ -1,7 +1,7 @@
 import { hash } from 'ohash'
 
 import type { FontProvider } from '../types'
-import { extractFontFaceData, addLocalFallbacks } from '../css/parse'
+import { extractFontFaceData } from '../css/parse'
 import { cachedData } from '../cache'
 import { $fetch } from '../fetch'
 import { logger } from '../logger'
@@ -86,7 +86,7 @@ async function getFontDetails(family: string) {
     }
   }
 
-  return addLocalFallbacks(family, extractFontFaceData(css))
+  return extractFontFaceData(css)
 }
 
 const userAgents = {

src/types.ts

@@ -179,6 +179,11 @@ export interface ModuleOptions {
    */
   devtools?: boolean
   experimental?: {
+    /**
+     * You can disable adding local fallbacks for generated font faces, like `local('Font Face')`.
+     * @default false
+     */
+    disableLocalFallbacks?: boolean
     /**
      * You can enable support for processing CSS variables for font family names. This may have a performance impact.
      * @default false

test/basic.test.ts

@@ -13,7 +13,7 @@ describe('providers', async () => {
     const html = await $fetch<string>('/providers/local')
     expect(extractFontFaces('Custom Font', html)).toMatchInlineSnapshot(`
       [
-        "@font-face{font-family:Custom Font;src:url(/custom-font.woff2) format(woff2);font-display:swap;font-weight:400;font-style:normal}",
+        "@font-face{font-family:Custom Font;src:local("Custom Font Regular"),local("Custom Font"),url(/custom-font.woff2) format(woff2);font-display:swap;font-weight:400;font-style:normal}",
       ]
     `)
   })