svelvg

Convert SVG files into Svelte components with TypeScript definitions.

Successor to svg-to-svelte

The minimum Svelte version required to use types generated by this library is v3.55.0.

This library transforms SVG files into Svelte components through the following:

• convert the svg file name into a valid module name (e.g., alarm-fill --> AlarmFill)
• forward $$restProps to the svg element while preserving attributes from the original svg
• add a default slot as child element to svg
• generate a TypeScript definition by extending the SvelteComponentTyped interface

Usage

CLI

The easiest way to use this library is through npx.

The glob value represents the relative path to the folder containing SVG files inside node_modules/.

For example, say you have bootstrap-icons installed as a development dependency, which contains icon SVG files in the "icons" folder.

npx svelvg glob=bootstrap-icons/icons

By default, the output directory is "lib". Customize the directory using the outDir flag:

npx svelvg glob=bootstrap-icons/icons outDir=dist

Optionally, generate an index of icons (a list of all module names) by enabling the iconIndex flag. It will default to creating a ICON_INDEX.md file in your working directory.

npx svelvg glob=bootstrap-icons/icons iconIndex

Customize the icon index file name like so:

npx svelvg glob=bootstrap-icons/icons iconIndex=ICONS.md

Node.js

Alternatively, install svelvg from NPM to use it programmatically.

# Yarn
yarn add -D svelvg

# NPM
npm i -D svelvg

# pnpm
pnpm i -D svelvg

Note that the top-level await requires Node.js v14 or greater.

const svelvg = require("svelvg");

// Emits components to the `lib` folder
svelvg.createLibrary("bootstrap-icons/icons");

// Customize the output directory to be `dist`
svelvg.createLibrary("bootstrap-icons/icons", { outDir: "dist" });

API

createLibrary

interface CreateLibraryOptions {
  /** @default "lib" */
  outDir: string;

  /** @default false */
  iconIndex: boolean | string;

  /**
   * Callback to add a list of classes to the SVG element
   * provided the original filename and module name
   * @example
   * filename: "alarm-fill"
   * moduleName: "AlarmFill"
   */
  appendClassNames: (filename: string, moduleName: string) => string[];

  /**
   * Override the default module name
   */
  toModuleName: (params: {
    path: path.ParsedPath;
    moduleName: string;
  }) => string;
}

Template

Scaffold a new project using the template:

npx degit metonym/svelvg/template <folder-name>

IconLibrary.svelte

svelvg exports an IconLibrary.svelte to make listing and searching icons easier.

See template/index.html for an example.

<script type="module">
  import IconLibrary from "svelvg/lib/IconLibrary.svelte";
  import * as icons from "./lib";
  import pkg from "./package.json";

  const app = new IconLibrary({
    target: document.getElementById("svelte"),
    props: {
      pkg,
      icons,
    },
  });
</script>

License

MIT

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.12.2 - 2024-06-19

• createLibrary options should be optional
• createLibrary should alphabetize module names

0.12.1 - 2023-06-25

• revert back to using SvelteComponentTyped, since SvelteComponent cannot be used in Svelte 3

0.12.0 - 2023-06-25

Breaking Changes

• update generated types to support Svelte 4, while still supporting Svelte version >=3.55

0.11.4 - 2023-02-09

• escape file extension regex for Windows

0.11.3 - 2022-10-01

• use type-only import for SvelteComponentTyped interface

0.11.2 - 2022-06-20

• escape icon names beginning with "\" in icon index

0.11.1 - 2022-06-19

• remove all spaces/dashes in IconLibrary regex when searching icon names

0.11.0 - 2022-06-19

• render meta description in IconLibrary component
• disable spellcheck in IconLibrary search input

0.10.1 - 2022-04-03

• generated TypeScript definitions should correctly extend SVG attributes

0.10.0 - 2022-02-19

• add IconLibrary Svelte component for searching the icon library

0.9.0 - 2022-02-19

• switch library format to CJS only
• rename Options interface to CreateLibraryOptions
• omit trailing line break in generated icon index file

0.8.4 - 2021-12-31

• use fs.rm instead of fs.rmdir

0.8.3 - 2021-12-14

• use fs.existsSync method to check if outDir exists

0.8.2 - 2021-12-14

• check if outDir folder exists before removing it

0.8.1 - 2021-11-26

• convert cli.js from CJS to ESM

0.8.0 - 2021-11-26

• set "type" to "module" in package.json
• allow createLibrary.appendClassNames to return undefined

0.7.0 - 2021-09-11

• add toModuleName callback to createLibrary options to override the default module name
• prefix module name if begins with !

0.6.0 - 2021-09-09

• glob for *.svg should account for nested folders **/*.svg
• emit success message creating the icon index

0.5.0 - 2021-08-31

• emit success message when creating a library

0.4.0 - 2021-08-28

• preserve underscores (_) when generating the module name

0.3.2 - 2021-08-28

• avoid duplicate module names in generated lib/index.js, lib/index.d.ts

0.3.1 - 2021-08-09

• generate index.d.ts

0.3.0 - 2021-07-31

Features

• add callback appendClassNames to add class names provided the filename/module name

Fixes

• cli.js should convert undefined values to true

0.2.0 - 2021-07-31

• Add option to generate an icon index in Markdown format

0.1.1 - 2021-07-31

• Use UMD entry in cli.js

0.1.0 - 2021-07-31

• Initial release