Icon Pipeline

0.2.0 · active · verified Tue Apr 21

Icon Pipeline is a utility for optimizing SVG icons and generating SVG sprites, along with individual optimized SVG files and a manifest of available icons. It aims to provide a 'no-nonsense' automated pipeline for icon management in web projects. As of version 0.2.0, the package is in early development, suggesting an irregular release cadence and that its API might not yet be stable. Its key differentiator lies in its integrated approach, handling both SVG optimization and sprite generation (for both HTML `<use>` and JavaScript injection) within a single tool, outputting multiple formats ready for different consumption patterns, which simplifies the icon build process compared to using separate tools for each step. It is designed to be included as a development dependency and run as part of a project's build process.

Common errors

```
ReferenceError: iconData is not defined
```
cause Attempting to access the `iconData` variable synchronously after calling the `iconPipeline` function, which is asynchronous and returns a Promise.

fix Access `iconData` only within the `.then()` callback of the `iconPipeline` Promise, or by using `await iconPipeline(...)` within an `async` function.
```
TypeError: require is not a function (when using 'import { iconPipeline } from "icon-pipeline"')
```
cause The `icon-pipeline` package, in its current version, primarily uses CommonJS `module.exports`. When a project is configured for ES Modules, a `require` call might fail.

fix For the main `iconPipeline` function, use `const iconPipeline = require('icon-pipeline')`. If your project strictly uses ESM, you might need to use a CommonJS wrapper or wait for native ESM support in future versions of the package.

Warnings

gotcha This package is currently in early development (version 0.2.0). The API is subject to change without adhering to semantic versioning for breaking changes, and overall stability for critical production environments is not guaranteed.
Fix: Pin to specific patch versions (`~0.2.0` instead of `^0.2.0`) and review the GitHub repository for changes before upgrading. Exercise caution when deploying to production.
gotcha The `iconPipeline` function returns a Promise. Forgetting to handle this Promise with `.then()` or `await` will result in subsequent code attempting to access the `iconData` asynchronously receiving an `undefined` value or a pending Promise object.
Fix: Always use `.then()` to process the results of `iconPipeline` or `await` it within an `async` function to ensure icon data is available when accessed.
gotcha The `includeSpriteInSrc: true` option places generated `sprite.js` and `sprite.svg` directly into the `srcDir`. This can lead to issues with source control (e.g., unintended commits) if not properly managed with `.gitignore`.
Fix: If `includeSpriteInSrc` is true, ensure your `.gitignore` file explicitly excludes `sprite.js` and `sprite.svg` from the source directory, or set `includeSpriteInSrc: false` and manage these files in your `outputDir`.

Install

npm install icon-pipeline npm
yarn add icon-pipeline yarn
pnpm add icon-pipeline pnpm

Imports

iconPipeline
wrong:
```
import { iconPipeline } from 'icon-pipeline'
```
correct:
```
const iconPipeline = require('icon-pipeline')
```
The main `iconPipeline` function is currently exported using CommonJS `module.exports` syntax. Attempting to use ES Modules `import` syntax will result in an error or `undefined`.
sprite
wrong:
```
import { sprite } from 'icon-pipeline'
```
correct:
```
import sprite from './build/icons/sprite.js'
```
The `sprite` (and `icon-list`) files are *generated outputs* of the `icon-pipeline` process, not direct exports from the package itself. They are typically imported from the specified `outputDir` path, using ES Modules syntax for the generated `.js` files.

Quickstart

This quickstart demonstrates how to configure and run the `icon-pipeline` using CommonJS `require`. It sets source and output directories, then executes the pipeline asynchronously to optimize SVGs and generate sprite files, logging the resulting metadata.

const path = require('path');
const iconPipeline = require('icon-pipeline');

const iconSrcFolder = path.join(__dirname, 'src', 'icons');
const iconOutputFolder = path.join(__dirname, 'build', 'icons');

// Ensure output directories exist before running, or icon-pipeline handles it.
// For demonstration, let's assume 'src/icons' contains some .svg files.
// Example: fs.mkdirSync(iconSrcFolder, { recursive: true });
// Example: fs.writeFileSync(path.join(iconSrcFolder, 'profile.svg'), '<svg viewBox="0 0 24 24"><path d="M12 4a4 4 0 014 4 4 4 0 01-4 4 4 4 0 01-4-4 4 4 0 014-4z"></path></svg>');

iconPipeline({
  srcDir: iconSrcFolder,
  outputDir: iconOutputFolder,
  includeSpriteInSrc: true,
  // Optional: disable additional svg classes
  // disableClasses: true,
  // Optional: namespace icon IDs
  // namespace: 'company'
}).then((iconData) => {
  console.log('Icon pipeline completed successfully.');
  console.log('Generated icon data:', iconData);
  // iconData will contain details like the paths to the generated files
}).catch((error) => {
  console.error('Error running icon pipeline:', error);
});

view raw JSON →