AaronJan/postcss-font-grabber

README

PostCSS Font Grabber

A postcss plugin, it grabs remote font files and update your CSS, just like that.

postcss-font-grabber v3.x only works with postcss v8，for postcss v7, please take a look at the v2.x branch.

Motivation

You may not want to use remote fonts, because:

It may expose your internal project
Font services could be unstable sometimes
You can do more things with local font files
GDPR compliance

Features

Standalone without any dependency
Written in TypeScript
Infer font file extension from HTTP response header (Thanks to @FTWinston)
Support custom download function (the download option)

Installation

Requires: Node >= 10.0, postcss 8.*

npm install postcss postcss-font-grabber --save-dev

Usages

With Gulp

gulp.task('css', () => {
  const postcss = require('gulp-postcss');
  const { postcssFontGrabber } = require('postcss-font-grabber');

  return gulp
    .src('src/css/**/*.css')
    .pipe(
      postcss([
        postcssFontGrabber({
          // postcss-font-grabber needs to know the CSS output
          // directory in order to calculate the new font URL.
          cssDest: 'dist/',
          fontDest: 'dist/fonts/',
        }),
      ]),
    )
    .pipe(gulp.dest('dist/'));
});

With Rollup

This example is using Rollup 2 with:

rollup-plugin-postcss

rollup.config.js:

import postcss from 'rollup-plugin-postcss';

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs',
  },
  plugins: [
    postcss({
      plugins: [
        postcssFontGrabber({
          // postcss-font-grabber needs to know the CSS output
          // directory in order to calculate the new font URL.
          cssDest: 'dist/',
          fontDest: 'dist/fonts/',
        }),
      ],
    }),
  ],
};

With Webpack

This example is using Webpack 5 with:

postcss-loader

css-loader

file-loader

webpack.config.js:

import path from 'path';

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader', 'postcss-loader'],
      },
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/i,
        use: ['file-loader'],
      },
    ],
  },
};

postcss.config.js:

import { postcssFontGrabber } from 'postcss-font-grabber';

module.exports = {
  plugins: [
    postcssFontGrabber({
      cssSrc: 'src/css/',
      // When using with `Webpack` you must set `cssDest` as the same as `cssSrc`,
      // since `Webpack` kept updated CSS files in memory, your source files will
      // be fine.
      // When `PostCSS` is done its job, `Webpack` then use `file-loader` to
      // embedding font file references into the dist file.
      cssDest: 'src/css/',
      fontDest: 'tmp/css/fonts/',
    }),
  ],
};

With Only PostCSS

PostCSS-Font-Grabber will use from and to options of PostCSS setting as the default options of cssSrc (from), cssDest and fontDest (to).

Options

Name	Type	Default	Description
cssSrc	`string`	`opts.from` from `PostCSS`'s setting	The root directory path of all CSS files
cssDest	`string`	`opts.to` from `PostCSS`'s setting	The directory where the transpiled CSS files are in
fontDest	`string`	the same as `cssDest`	The directory where the downloaded fonts stored
download	`(fontSpec: FontSpec) => Promise<{ data: Readable, mimeType?: string }>`	-	Custom function to download font files. Maybe you want to customize UserAgent or something?

TypeScript

You can import types if you need to (only in TypeScript):

import { FontSpec, Downloader, DownloadResult } from 'postcss-font-grabber';

License

Licensed under the APACHE LISENCE 2.0.

Credits

PostCSS

PostCSS Copy Assets

Issue Reporters