Skip to content

A tool for generating icons for the modern web.

License

Notifications You must be signed in to change notification settings

TrigenSoftware/flexis-favicons

Repository files navigation

@flexis/favicons

NPM version Node version Dependencies status Build status Coverage status Dependabot badge Documentation badge

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;
}

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;
}

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