@johnfmorton/favicon-generator-craftcms

v0.1.2

Published

8 days ago

Generate favicon assets, manifests, and HTML tags for Craft CMS + Vite projects

0High
0Medium
0Low

johnfmorton

favicon craft-cms vite pwa manifest icons

craft-favicon-generator

Generate a complete set of favicon and web app assets from a single source PNG image. Built for Craft CMS + Vite projects, but works anywhere.

Uses the favicons package (v7+, built on sharp) to produce icons for every major platform, manifest files, and a ready-to-include HTML snippet.

Installation

npm install @johnfmorton/favicon-generator-craftcms

Quick Start

1. Create a Config File

Add craft-favicon-generator.config.mjs to your project root:

export default {
  appName: 'Your Site Name',
}

That's it for the minimum config. All other options have sensible defaults for Craft CMS projects.

2. Add a Source Image

Place a high-resolution PNG (at least 512x512, ideally 1024x1024) at src/img/favicon-src.png, or set a custom source path in your config.

3. Run the Generator

npx craft-favicon-generator

Configuration

Only appName is required. Everything else has defaults tuned for Craft CMS + Vite projects.

Full Example

export default {
  // Required
  appName: 'My Site',

  // Paths (relative to project root)
  source: 'src/img/favicon-src.png',       // default
  outputDir: 'web/dist/assets/favicons',    // default
  pathPrefix: '/dist/assets/favicons',      // default

  // App metadata
  appDescription: 'A short description of your site.',
  appShortName: 'MySite',                   // defaults to appName
  developerName: 'Your Name',
  developerURL: 'https://your-site.com',

  // Appearance
  background: '#fff',
  theme_color: '#fff',

  // Platform toggles (all true by default)
  icons: {
    android: true,
    appleIcon: true,
    appleStartup: true,
    favicons: true,
    windows: true,
    yandex: false,
  },
}

Default Values

| Option | Default | Description | |---|---|---| | source | src/img/favicon-src.png | Path to source PNG image | | outputDir | web/dist/assets/favicons | Where generated files are written | | pathPrefix | /dist/assets/favicons | URL path prefix in generated HTML/manifests | | appDescription | '' | App description for manifests | | appShortName | value of appName | Short name for home screen | | background | #fff | Background color for splash screens | | theme_color | #fff | Browser toolbar color on mobile | | lang | en-US | Language | | display | minimal-ui | PWA display mode | | icons.android | true | Generate Android icons | | icons.appleIcon | true | Generate Apple Touch icons | | icons.appleStartup | true | Generate Apple startup images | | icons.favicons | true | Generate standard favicons | | icons.windows | true | Generate Windows tile images | | icons.yandex | true | Generate Yandex browser assets |

See the favicons documentation for additional options.

Craft CMS Integration

The generator produces a webapp.html file containing all <link> and <meta> tags. Use the Craft Vite plugin's inline() method to embed it in your template's <head>:

<head>
  {# Favicons, webapp manifests, etc. #}
  {{ craft.vite.inline("@webroot/dist/assets/favicons/webapp.html") }}
</head>

Without the Craft Vite plugin:

{{ source('@webroot/dist/assets/favicons/webapp.html', ignore_missing = true) }}

Programmatic API

import { generate } from '@johnfmorton/favicon-generator-craftcms'

const result = await generate({
  source: '/absolute/path/to/favicon-src.png',
  outputDir: '/absolute/path/to/output',
  pathPrefix: '/dist/assets/favicons',
  faviconOptions: {
    appName: 'My App',
    background: '#fff',
    theme_color: '#fff',
    icons: { android: true, appleIcon: true, favicons: true },
  },
})

console.log(result)
// { images: 25, files: 3, html: 1, failed: 0 }

When using the programmatic API, all paths must be absolute. The faviconOptions object is passed directly to the favicons package.

Environment Variables

The CLI will load a .env file if dotenv is installed in your project. This is optional and not a hard dependency.

When to Run

Favicons only need to be regenerated when:

You change the source image
You update app metadata (name, colors, etc.)
You update the favicons npm package

There is no need to run this on every build.

License

MIT