feat(preset-web-fonts): add onDownload callback to createLocalFontProcessor (#5199)

jack-old-archive · zyyv · autofix-ci[bot] · web-flow · commit 36509feb3897 · 2026-05-20T05:46:28.000Z
Co-authored-by: Chris &lt;hizyyv@gmail.com&gt;
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
diff --git a/docs/presets/web-fonts.md b/docs/presets/web-fonts.md
@@ -253,3 +253,57 @@ This will download the fonts assets to `public/assets/fonts` and serve them from
 This feature is Node.js specific and will not work in the browser.
 
 :::
+
+## Emit Fonts to Build Output
+
+In CI environments or during the first build, fonts downloaded to the `public` directory might not be copied to `dist` before the build finishes. To ensure fonts are always included in the production build, use the `onDownload` callback with a custom Vite plugin.
+
+**vite.config.ts**
+
+```ts
+import { createLocalFontProcessor } from '@unocss/preset-web-fonts/local'
+import { defineConfig } from 'vite'
+
+const emittedFonts = new Map()
+
+// 1. Create the processor with onDownload hook
+export const fontProcessor = createLocalFontProcessor({
+  onDownload(filename, buf) {
+    emittedFonts.set(filename, buf)
+  }
+})
+
+export default defineConfig({
+  plugins: [
+    UnoCSS(),
+    // 2. Emit the collected fonts as assets during build
+    {
+      name: 'unocss:font-emit',
+      apply: 'build',
+      generateBundle() {
+        for (const [filename, source] of emittedFonts) {
+          this.emitFile({ type: 'asset', fileName: `assets/fonts/${filename}`, source })
+        }
+        emittedFonts.clear()
+      }
+    },
+  ],
+})
+```
+
+**uno.config.ts**
+
+```ts
+import presetWebFonts from '@unocss/preset-web-fonts'
+import { fontProcessor } from './vite.config'
+
+export default defineConfig({
+  presets: [
+    presetWebFonts({
+      provider: 'google',
+      fonts: { sans: 'Roboto' },
+      processors: [fontProcessor],
+    }),
+  ],
+})
+```
diff --git a/packages-presets/preset-web-fonts/src/local.ts b/packages-presets/preset-web-fonts/src/local.ts
@@ -6,11 +6,9 @@ import fsp from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import process from 'node:process'
 import { fetch } from 'ofetch'
-import { replaceAsync } from '#integration/utils'
 
 const fontUrlRegex = /[-\w@:%+.~#?&/=]+\.(?:woff2?|eot|ttf|otf|svg)/gi
-// eslint-disable-next-line regexp/no-unused-capturing-group
-const urlProtocolRegex = /^[\s\w\0+.-]{2,}:([/\\]{1,2})/
+const urlProtocolRegex = /^[\s\w\0+.-]{2,}:[/\\]{1,2}/
 
 export interface LocalFontProcessorOptions {
   /**
@@ -45,6 +43,13 @@ export interface LocalFontProcessorOptions {
    * Custom fetch function to provide the font data.
    */
   fetch?: typeof fetch
+
+  /**
+   * Callback invoked when a font file is downloaded during build.
+   * Receives the filename and file buffer, useful for emitting fonts
+   * directly to the build output instead of relying on public dir copy.
+   */
+  onDownload?: (filename: string, buf: Buffer) => void | Promise<void>
 }
 
 export function createLocalFontProcessor(options?: LocalFontProcessorOptions): WebFontProcessor {
@@ -58,8 +63,11 @@ export function createLocalFontProcessor(options?: LocalFontProcessorOptions): W
     const fetcher = options?.fetch ?? fetch
     const response = await fetcher(url)
       .then(r => r.arrayBuffer())
+    const buf = Buffer.from(response)
+    const filename = assetPath.split(/[\\/]/).pop()!
+    await options?.onDownload?.(filename, buf)
     await fsp.mkdir(fontAssetsDir, { recursive: true })
-    await fsp.writeFile(assetPath, Buffer.from(response))
+    await fsp.writeFile(assetPath, buf)
   }
 
   const cache = new Map<string, Promise<void>>()
@@ -75,9 +83,9 @@ export function createLocalFontProcessor(options?: LocalFontProcessorOptions): W
       const hash = getHash(JSON.stringify(fonts))
       const cachePath = join(cacheDir, `${hash}.css`)
 
-      if (fs.existsSync(cachePath)) {
+      if (fs.existsSync(cachePath))
         return fsp.readFile(cachePath, 'utf-8')
-      }
+
       const css = await getCSSDefault(fonts, providers)
 
       await fsp.mkdir(cacheDir, { recursive: true })
@@ -86,12 +94,17 @@ export function createLocalFontProcessor(options?: LocalFontProcessorOptions): W
       return css
     },
     async transformCSS(css) {
-      return await replaceAsync(css, fontUrlRegex, async (url) => {
+      // Find all font URLs in the CSS
+      const matches = css.match(fontUrlRegex) || []
+      const replacements = new Map<string, string>()
+
+      // Process each unique URL found in the CSS
+      await Promise.all(Array.from(new Set(matches)).map(async (url) => {
         const hash = getHash(url)
         const ext = url.split('.').pop()
 
         let name = ''
-        const match1 = url.match(/\/s\/([^/]+)\//) // Google Fonts
+        const match1 = url.match(/\/s\/([^/]+)\//)
         if (match1)
           name = match1[1].replace(/\W/g, ' ').trim().replace(/\s+/, '-').toLowerCase()
 
@@ -103,8 +116,11 @@ export function createLocalFontProcessor(options?: LocalFontProcessorOptions): W
           await downloadFont(_url, assetPath)
         }
 
-        return `${fontServeBaseUrl}/${filename}`
-      })
+        replacements.set(url, `${fontServeBaseUrl}/${filename}`)
+      }))
+
+      // Replace all occurrences using the populated map
+      return css.replace(fontUrlRegex, match => replacements.get(match) || match)
     },
   }
 }
