Google Fonts Webpack Plugin

0.4.4 verified Sat Apr 25 auth: no javascript maintenance

A webpack plugin that downloads Google Fonts to your build folder using google-webfonts-helper or links to the Google Fonts CDN. Version 0.4.4 is the latest stable release; activity is sporadic with no recent updates. Key differentiators: seamless integration with webpack and html-webpack-plugin, support for multiple font formats (eot, woff, woff2, ttf, svg), and optional local hosting versus CDN linking.

Common errors

error Error: Cannot find module 'google-webfonts-helper' ↓

cause The package does not automatically install peer dependencies; missing google-webfonts-helper.

fix

Run 'npm install google-webfonts-helper' as a dependency.

error TypeError: GoogleFontsPlugin is not a constructor ↓

cause CommonJS require() was used incorrectly or the import was attempted as default import in ESM.

fix

Use 'const GoogleFontsPlugin = require('google-fonts-webpack-plugin');'

error ERROR in Plugin could not be instantiated ↓

cause The options object is empty or malformed (e.g., missing fonts array).

fix

Ensure the plugin is instantiated with an options object containing a 'fonts' array.

error HTML Webpack Plugin Error: No template provided ↓

cause local is false but html-webpack-plugin is not properly configured.

fix

Either set local: true or install and configure html-webpack-plugin.

Warnings

deprecated This package is no longer actively maintained; consider using @next/font or a more modern solution. ↓

fix Migrate to a maintained alternative like @next/font (Next.js) or fontsource packages.

gotcha The 'local' option must be set to true for fonts to be downloaded; otherwise, only a CSS link is generated. ↓

fix Set local: true in the options object if you want fonts bundled locally.

gotcha If html-webpack-plugin is not installed, setting local to false will throw an error because it tries to inject a link into the HTML template. ↓

fix Install html-webpack-plugin or set local: true to avoid dependency on it.

gotcha The google-webfonts-helper API (default apiUrl) may be unreliable or slow; it's a Heroku app that can be down. ↓

fix If the API is down, consider using a self-hosted instance or switch to local: false and use CDN.

gotcha Font variants must match the exact format returned by google-webfonts-helper (e.g., '400', '700italic'); invalid variants cause silent failures. ↓

fix Verify variant strings against the Google Fonts API or google-webfonts-helper.

Install

npm install google-fonts-webpack-plugin

yarn add google-fonts-webpack-plugin

pnpm add google-fonts-webpack-plugin

Imports

GoogleFontsPlugin

wrong

import GoogleFontsPlugin from 'google-fonts-webpack-plugin'

correct

const GoogleFontsPlugin = require('google-fonts-webpack-plugin')

This package does not ship ESM; use CommonJS require(). ECMAScript modules are not supported.

GoogleFontsPlugin
```
import GoogleFontsPlugin = require('google-fonts-webpack-plugin')
```
For TypeScript with esModuleInterop, use import = require() syntax.
options
wrong
```
new GoogleFontsPlugin([{ family: "Roboto" }])
```
correct
```
new GoogleFontsPlugin({ fonts: [] })
```
The constructor expects an options object, not an array. Pass fonts as an array inside the options object.

Quickstart

Demonstrates basic configuration: specifying font families with variants, setting local download with woff2/woff formats, and custom output path and CSS filename.

// webpack.config.js
const GoogleFontsPlugin = require('google-fonts-webpack-plugin');
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  plugins: [
    new GoogleFontsPlugin({
      fonts: [
        { family: 'Roboto', variants: ['400', '700'] },
        { family: 'Open Sans', variants: ['300', '600italic'] }
      ],
      path: 'font/',            // relative to output path
      filename: 'fonts.css',
      formats: ['woff2', 'woff'],
      local: true               // download fonts locally
    })
  ]
};