@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();