postcss-font-grabber

PostCSS Font Grabber

🎉 Here is the brand new 2.0 version that is completely rewritten in TypeScript (with typing), for 1.0 please see HERE

A PostCSS plugin, it only does one thing and good at it: download remote fonts that's in your CSS file (@font-face).

Motivation

You may not want to use remote fonts, because:

• it may expose your internal project
• font service may be slow for your users
• you can do more things with local font files

Features

• Written in TypeScript
• Standalone without any dependency
• Concurrent download
• Automatically create directories
• Support HTTP & HTTPS

Installation

Requires: Node >= 8.0

npm install 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({
                // Because PostCSS-Font-Grabber can't get the paths outside itself, you
                // have to set them manually.
                cssSrc: 'src/css/',
                cssDest: 'dist/',
                fontDir: 'dist/fonts/',
                mkdir: true,
            }),
        ]))
        .pipe(gulp.dest('dist/'));
});

With Webpack

This example is using Webpack 4 with these packages:

• 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$/,
                exclude: /node_modules/,
                use: [
                    {
                        loader: 'style-loader',
                    },
                    {
                        loader: 'css-loader',
                        options: {
                            importLoaders: 1,
                        }
                    },
                    {
                        loader: 'postcss-loader'
                    },
                ],
            },
            {
                test: /\.(woff|woff2|eot|ttf|otf)$/,
                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` doesn't output CSS files directly, when done with 
            // `PostCSS`, `Webpack` use `file-loader` to transpile local file
            // references in the CSS.
            cssDest: 'src/css/',
            fontDir: '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 fontDir (to).

Options

Function postcssFontGrabber takes an object of options as parameter:

postcssFontGrabber({
    cssSrc: 'src/css/',
    cssDest: 'dist/',
    fontDir: 'dist/fonts/',
    mkdir: true,
})

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
fontDir	{string}	the same as cssDest	The directory where the downloaded fonts stored
mkdir	{boolean}	true	whether to create non-existing directories automatically or not

Dig Deeper

You can get the metadata of all execution details of PostCSS-Font-Grabber:

import postcss from 'gulp-postcss';
import { makeInstance } from 'postcss-font-grabber';

gulp.task('default', () => {
    // Create instance manually:
    const fontGrabber = makeInstance({
        cssSrc: 'src/css/',
        cssDest: 'dist/',
        fontDir: 'dist/fonts/',
        mkdir: true,
    });

    // Register a callback:
    fontGrabber.onDone(meta => {
        console.log('meta', JSON.stringify(meta, null, '    '));
    });

    return gulp.src('src/css/**/*.css')
        .pipe(postcss([
            fontGrabber.makeTransformer(),
        ]))
        .pipe(gulp.dest('dist/'));
});

Metadata Format

Here is an example:

// Importing module just for demonstration purpose, because the metadata contains URL object.
import url from 'url';

{
    "jobResults": [
        {
            "job": {
                "remoteFont": {
                    "urlObject": url.parse('https://example.com'),
                    "format": "woff2"
                },
                "css": {
                    "sourcePath": "/var/project/public/css/google.css",
                    "destinationDirectoryPath": "/var/project/public/dist/css/fonts"
                },
                "font": {
                    "path": "/var/project/public/dist/css/fonts/ea8XadU7WuTxEub_NdWn8WZFuVs.woff2",
                    "filename": "ea8XadU7WuTxEub_NdWn8WZFuVs.woff2"
                }
            },
            "download": {
                "size": 14312
            }
        },
        /* More JobResults */
    ]
}

License

Licensed under the APACHE LISENCE 2.0.

Credits

PostCSS

PostCSS Copy Assets

Issue Reporters