@flexis/favicons

A tool for generating icons for the modern web.

• Traditional web favicons ❤️
• Android and iOS icons, iOS startup screens 🖼
• Generates assets for PWA 📲
• You can run it from the CLI ⌨️
• Works with Gulp and as JS library 🦄
• Based on Sharp library - lightning fast ⚡️

Install

npm i -D @flexis/favicons
# or
yarn add -D @flexis/favicons

Usage

CLI

npx favicons [...sources] [...options]
# or
yarn exec -- favicons [...sources] [...options]

Option	Description	Default
sources	Source icon(s) glob patterns.
‑‑help, -h	Print this message.
‑‑verbose, -v	Print additional info about progress.
‑‑path, -p	Relative public path to use in webmanifest and html-headers.
‑‑background, -b	Background color for icons and startup images.	white
‑‑manifest, -m	Path to webmanifest file to add icons. Also can use it to get background color.
‑‑headers, -H	Create html-file with headers for icons.	false
‑‑skipFavicon	Do not create favicon.	false
‑‑skipAndroid	Do not create icons for Android.	false
‑‑skipApple	Do not create icons for iOS.	false
‑‑skipAppleStartup	Do not create startup screens for iOS.	false
‑‑androidBackground	Background color for Android icons.
‑‑androidOffset	Offset size in percents for Android icons.	0
‑‑appleBackground	Background color for iOS icons.
‑‑appleOffset	Offset size in percents for iOS icons.	0
‑‑appleStartupBackground	Background color for iOS startup screens.
‑‑appleStartupOffset	Offset size in percents for iOS startup screens.	0
‑‑dest, -d	Destination directory.

Example

# From SVG
favicons src/favicon.svg --manifest src/manifest.json --headers -d build
# From some PNGs with different sizes
favicons "src/icons/*.png" --background "#FACE8D" --headers -d build

Configuration

Configuration file is optional. If needed, can be defined through .faviconsrc JSON file in the root directory of the project.

Supported options:

interface IConfig {
    /**
     * Source icon(s) glob patterns.
     */
    src?: string | string[];
    /**
     * Relative public path to use in webmanifest and html-headers.
     */
    path?: string;
    /**
     * Background color for icons and startup images.
     */
    background?: string;
    /**
     * Path to webmanifest or webmanifest object to add icons. Also can use it to get background color.
     */
    manifest?: string | IManifestConfig;
    /**
     * Output icons configuration.
     */
    icons?: IIconsConfig;
    /**
     * Create html-file with headers for icons.
     */
    headers?: boolean | IHeadersConfig;
    /**
     * Print additional info about progress.
     */
    verbose?: boolean;
    /**
     * Destination directory.
     */
    dest?: string;
}

• IIconsConfig
• IManifestConfig
• IHeadersConfig

Gulp

Also you can use @flexis/favicons with Gulp:

import favicons from '@flexis/favicons/lib/stream';
import manifest from './src/manifest.json';

gulp.task('favicons', () =>
    gulp.src('src/favicon.svg')
        .pipe(favicons({
            manifest,
            headers: true
        }))
        .pipe(gulp.dest('build'))
);

Plugin options:

interface IPluginConfig {
    /**
     * Relative public path to use in webmanifest and html-headers.
     */
    path?: string;
    /**
     * Background color for icons and startup images.
     */
    background?: string;
    /**
     * Webmanifest to add icons. Also can use it to get background color.
     */
    manifest?: IManifestConfig;
    /**
     * Output icons configuration.
     */
    icons?: IIconsConfig;
    /**
     * Create html-file with headers for icons.
     */
    headers?: boolean | IHeadersConfig;
    /**
     * Print additional info about progress.
     */
    verbose?: boolean;
}

• IIconsConfig
• IManifestConfig
• IHeadersConfig

JS API

Module exposes next API:

export default FaviconsGenerator;
export {
    IManifestConfig,
    IIconConfig,
    IIconsConfig,
    IHeadersConfig,
    IConfig,
    getHtmlHeadersMarkup
};

Description of all methods you can find in Documentation.

Example

import {
    promises as fs
} from 'fs';
import FaviconsGenerator, {
    getHtmlHeadersMarkup
} from '@flexis/favicons';
import Vinyl from 'vinyl';
import manifest from './src/manifest.json';

async function generate() {

    const path = 'src/favicon.svg';
    const contents = await fs.readFile(path);
    const source = new Vinyl({
        path,
        contents
    });
    const favicons = new FaviconsGenerator({
        manifest
    });
    const icons = favicons.generateIcons(source);

    for await (const icon of icons) {
        icon.base = './build';
        await fs.writeFile(icon.path, icon.contents);
    }

    const headers = favicons.generateHtmlHeaders();
    const html = getHtmlHeadersMarkup(headers);

    await fs.writeFile('build/favicons.html', html);

    const manifest = favicons.generateManifset();
    const json = JSON.stringify(manifest);

    await fs.writeFile('build/manifest.json', json);
}

generate();