vite-awesome-svg-loader 1.4.1 → 2.0.1

package/README.md

@@ -9,8 +9,8 @@ A Vite plugin that:
    1. Source code base64.
    1. Source code base64 [data URI](https://en.wikipedia.org/wiki/Data_URI_scheme).
 1. Can preserve line width, i.e. make icons and line art have same line width when scaling.
-1. Can replace colors with `currentColor`.
-1. Will minimize your SVGs using [SVGO](https://github.com/svg/svgo).
+1. Can replace colors with `currentColor` or a custom color via configuration (see `replaceColorsList` option).
+1. Will automatically minimize your SVGs using [SVGO](https://github.com/svg/svgo).
 1. Allows you to create SVG sprites using provided integrations.
 
 `vite-awesome-svg-loader` is framework-agnostic. All integrations are done in form of subpath imports (for example, `vite-awesome-svg-loader/vue-integration`). This means that you'll get only what you need in your app bundle. This also means that you can develop your own integration using `vite-awesome-svg-loader/integration-utils` import.
@@ -103,10 +103,41 @@ viteAwesomeSvgLoader({
   skipPreserveLineWidthList: [/line-width-not-preserved\.svg/],
 
   // A list of files or directories to preserve color of
-  setCurrentColorList: [/config-demo\/set-current-color\//, /config-demo\/all\//],
+  replaceColorsList: [
+    // File names
+    "some-file.svg",
 
-  // A list of files to skip while replacing colors. Overrides setCurrentColorList.
-  skipSetCurrentColorList: [/colors-not-preserved\.svg/],
+    // Regexes that are checked against whole path and file name with extension
+    /config-demo\/set-current-color\//,
+    /config-demo\/all\//,
+
+    // Map of color replacements. Key is an original color, value is its replacement. Both can be any values:
+    // HEX, name, rgb() or arbitrary custom values. Applied to all files.
+    {
+      "#003147": "red",
+      "rgb(0, 49, 71)": "#003147",
+      "myCustomColor": "var(--some-color-var)",
+    },
+
+    // Map of color replacements per files
+    {
+      files: ["vars.svg"], // File names or regexes, same format as above
+
+      // Replacements, same format as above
+      replacements: {
+        red: "var(--primary-color)",
+        green: "var(--secondary-color)",
+        blue: "var(--tertiary-color)",
+      },
+
+      // Default value for colors that are not in replacements map. Set an empty string to preserve original colors.
+      // Default value is "currentColor",
+      default: "currentColor"
+    },
+  ],
+
+  // A list of files to skip while replacing colors. Overrides replaceColorsList.
+  skipReplaceColorsList: [/colors-not-preserved\.svg/],
 
   // A list of files to skip while transforming. File skip-transforms.svg is present in every directory.
   skipTransformsList: [/skip-transforms\.svg/, /ignore-elements-orig\.svg/],
@@ -126,14 +157,14 @@ viteAwesomeSvgLoader({
     },
   ],
 
-  // These two options are not recommended due to architectural and performance considerations (see JSDoc):
+  // These options are not recommended due to architectural and performance reasons (see JSDoc):
 
   // A list of selectors to skip while replacing colors. Same format as above.
-  skipSetCurrentColorSelectors: ['*[data-original-color="true"], *[data-original-color="true"] *'],
+  skipReplaceColorsSelectors: ['*[data-original-color="true"], *[data-original-color="true"] *'],
 
   // A list of selectors to skip while transforming. Same format as above.
   skipTransformsSelectors: ['*[data-no-transforms="true"], *[data-no-transforms="true"] *'],
-}),
+})
 ```
 
 6. Optional. Use integrations to create sprite sheets. Or [write your own integration](https://github.com/matafokka/vite-awesome-svg-loader/tree/main/#custom-integration).
@@ -323,6 +354,15 @@ See: https://vitejs.dev/guide/features#glob-import
 
 **Note**: if you want to support browsers without [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import), use [@vitejs/plugin-legacy](https://www.npmjs.com/package/@vitejs/plugin-legacy) as shown in the demos.
 
+### For library authors
+
+If your icon set is not extensible, just add `vite-awesome-svg-loader` and build your library.
+
+If your icon set is extensible, you'll need to:
+
+1. Provide a plugin that wraps `vite-awesome-svg-loader` and sets your settings.
+1. Tell your users to use your plugin, import icons as source code and pass it to your components.
+
 ### Comparison with other loaders
 
 **[vite-svg-loader](https://github.com/jpkleemans/vite-svg-loader)**

package/declarations.d.ts

@@ -0,0 +1,77 @@
+declare module "*.svg?url" { const src: string; export default src; }
+declare module "*.svg?source" { const src: string; export default src; }
+declare module "*.svg?source-data-uri" { const src: string; export default src; }
+declare module "*.svg?base64" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri" { const src: string; export default src; }
+declare module "*.svg?preserve-line-width" { const src: string; export default src; }
+declare module "*.svg?preserve-line-width=true" { const src: string; export default src; }
+declare module "*.svg?preserve-line-width=false" { const src: string; export default src; }
+declare module "*.svg?url&preserve-line-width" { const src: string; export default src; }
+declare module "*.svg?url&preserve-line-width=true" { const src: string; export default src; }
+declare module "*.svg?url&preserve-line-width=false" { const src: string; export default src; }
+declare module "*.svg?source&preserve-line-width" { const src: string; export default src; }
+declare module "*.svg?source&preserve-line-width=true" { const src: string; export default src; }
+declare module "*.svg?source&preserve-line-width=false" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&preserve-line-width" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&preserve-line-width=true" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&preserve-line-width=false" { const src: string; export default src; }
+declare module "*.svg?base64&preserve-line-width" { const src: string; export default src; }
+declare module "*.svg?base64&preserve-line-width=true" { const src: string; export default src; }
+declare module "*.svg?base64&preserve-line-width=false" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&preserve-line-width" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&preserve-line-width=true" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&preserve-line-width=false" { const src: string; export default src; }
+declare module "*.svg?set-current-color" { const src: string; export default src; }
+declare module "*.svg?set-current-color=true" { const src: string; export default src; }
+declare module "*.svg?set-current-color=false" { const src: string; export default src; }
+declare module "*.svg?url&set-current-color" { const src: string; export default src; }
+declare module "*.svg?url&set-current-color=true" { const src: string; export default src; }
+declare module "*.svg?url&set-current-color=false" { const src: string; export default src; }
+declare module "*.svg?source&set-current-color" { const src: string; export default src; }
+declare module "*.svg?source&set-current-color=true" { const src: string; export default src; }
+declare module "*.svg?source&set-current-color=false" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&set-current-color" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&set-current-color=true" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&set-current-color=false" { const src: string; export default src; }
+declare module "*.svg?base64&set-current-color" { const src: string; export default src; }
+declare module "*.svg?base64&set-current-color=true" { const src: string; export default src; }
+declare module "*.svg?base64&set-current-color=false" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&set-current-color" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&set-current-color=true" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&set-current-color=false" { const src: string; export default src; }
+declare module "*.svg?skip-transforms" { const src: string; export default src; }
+declare module "*.svg?skip-transforms=true" { const src: string; export default src; }
+declare module "*.svg?skip-transforms=false" { const src: string; export default src; }
+declare module "*.svg?url&skip-transforms" { const src: string; export default src; }
+declare module "*.svg?url&skip-transforms=true" { const src: string; export default src; }
+declare module "*.svg?url&skip-transforms=false" { const src: string; export default src; }
+declare module "*.svg?source&skip-transforms" { const src: string; export default src; }
+declare module "*.svg?source&skip-transforms=true" { const src: string; export default src; }
+declare module "*.svg?source&skip-transforms=false" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&skip-transforms" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&skip-transforms=true" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&skip-transforms=false" { const src: string; export default src; }
+declare module "*.svg?base64&skip-transforms" { const src: string; export default src; }
+declare module "*.svg?base64&skip-transforms=true" { const src: string; export default src; }
+declare module "*.svg?base64&skip-transforms=false" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&skip-transforms" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&skip-transforms=true" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&skip-transforms=false" { const src: string; export default src; }
+declare module "*.svg?skip-awesome-svg-loader" { const src: string; export default src; }
+declare module "*.svg?skip-awesome-svg-loader=true" { const src: string; export default src; }
+declare module "*.svg?skip-awesome-svg-loader=false" { const src: string; export default src; }
+declare module "*.svg?url&skip-awesome-svg-loader" { const src: string; export default src; }
+declare module "*.svg?url&skip-awesome-svg-loader=true" { const src: string; export default src; }
+declare module "*.svg?url&skip-awesome-svg-loader=false" { const src: string; export default src; }
+declare module "*.svg?source&skip-awesome-svg-loader" { const src: string; export default src; }
+declare module "*.svg?source&skip-awesome-svg-loader=true" { const src: string; export default src; }
+declare module "*.svg?source&skip-awesome-svg-loader=false" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&skip-awesome-svg-loader" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&skip-awesome-svg-loader=true" { const src: string; export default src; }
+declare module "*.svg?source-data-uri&skip-awesome-svg-loader=false" { const src: string; export default src; }
+declare module "*.svg?base64&skip-awesome-svg-loader" { const src: string; export default src; }
+declare module "*.svg?base64&skip-awesome-svg-loader=true" { const src: string; export default src; }
+declare module "*.svg?base64&skip-awesome-svg-loader=false" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&skip-awesome-svg-loader" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&skip-awesome-svg-loader=true" { const src: string; export default src; }
+declare module "*.svg?base64-data-uri&skip-awesome-svg-loader=false" { const src: string; export default src; }

package/index.d.mts

@@ -0,0 +1,260 @@
+import { Plugin } from 'vite';
+
+/**
+ * SVG loader options.
+ *
+ * **Paths**
+ *
+ * Both file name and its path relative to the project's root with leading slash will be compared.
+ *
+ * For example, if you have a file `/src/assets/icons/menu.svg` then following strings will be checked:
+ *
+ * 1. `/assets/icons/menu.svg` - note that it doesn't start with `/src`
+ * 2. `menu.svg`
+ *
+ * To avoid transforming multiple files with the same name, always include path into each entry.
+ *
+ * Examples:
+ *
+ * ```js
+ * plugins: [
+ *   viteReBinSvgLoader({
+ *     preserveLineWidthList: [
+ *       // Recommended formats:
+ *       /\/img\/icons/, // Matches all paths containing "/img/line-art/"
+ *       "/assets/img/logo.svg", // Matches single file "/assets/img/logo.svg".
+ *
+ *       // Not recommended formats:
+ *       "splash.svg", // Matches all files named "splash.svg"
+ *       /\/icons\/plus\.svg/, // Matches all paths containing "/icons/plus.svg"
+ *     ],
+ *   }),
+ * ],
+ * ```
+ */
+interface SvgLoaderOptions {
+    /**
+     * Temporary directory where SVG files will be stored in dev mode.
+     *
+     * @default "temp"
+     */
+    tempDir?: string;
+    /**
+     * A list of files or directories to preserve line width of, i.e. to set `vector-effect="non-scaling-stroke"`.
+     *
+     * This option is primarily for icons and line art.
+     *
+     * This also can be done in an import: `import imageSrc from "./path/to/image.svg?preserve-line-width"`.
+     */
+    preserveLineWidthList?: (string | RegExp)[];
+    /**
+     * A list of files or directories to disable preserving line width of. Overrides {@link preserveLineWidthList}.
+     */
+    skipPreserveLineWidthList?: (string | RegExp)[];
+    /**
+     * A list of CSS selectors to disable {@link preserveLineWidthList} for. Use it to leave specific elements stroke
+     * width as-is.
+     *
+     * Can be a list of selectors or selectors-per-files specifiers.
+     *
+     * Unlike {@link skipSetCurrentColorSelectors} and {@link skipTransformsSelectors}, doesn't impact build performance.
+     */
+    skipPreserveLineWidthSelectors?: (string | SelectorsPerFiles)[];
+    /**
+     * A list of files or directories to replace fill, stroke and `<stop>` colors with `currentColor` (default) or other
+     * colors (if {@link ColorMapPerFiles} or {@link ColorMap} is specified), i.e.:
+     *
+     * 1. `fill`, `stroke` and `stop-color` attributes and CSS identifiers will be replaced with `currentColor` or other
+     * given color.
+     * 2. `none`, `transparent` or `currentColor` values will not be replaced.
+     *
+     * Opacity (i.e. `rgba()`) won't be preserved.
+     * You have to manually set opacity by setting `fill-opacity` and `stroke-opacity` attributes.
+     *
+     * This is done because opacity may be handled with a stylesheet selector. This case is hard to implement, and it may
+     * slow down build process. This behavior might be changed in future, but it shouldn't break your project.
+     *
+     * Setting `currentColor` can be done with an import: `import imageSrc from "./path/to/image.svg?set-current-color"`.
+     *
+     * Replacements priority:
+     *
+     * 1. {@link ColorMapPerFiles}
+     * 1. {@link ColorMap}
+     * 1. `string | RegExp`
+     */
+    replaceColorsList?: (string | RegExp | ColorMap | ColorMapPerFiles)[];
+    /**
+     * A list of files or directories to disable color replacements of. Overrides {@link replaceColorsList}.
+     */
+    skipReplaceColorsList?: (string | RegExp)[];
+    /**
+     * A list of CSS selectors to disable {@link skipReplaceColorsList} for. Use it to leave specific elements colors
+     * as-is.
+     *
+     * Can be a list of selectors or selectors-per-files specifiers.
+     *
+     * **You probably don't need this option.** Think of other ways to solve your problem. "Recipes" section
+     * in the demos may help you.
+     *
+     * **Heavy usage may significantly slow down build time.** Limit selectors to specific files to improve performance.
+     */
+    skipReplaceColorsSelectors?: (string | SelectorsPerFiles)[];
+    /**
+     * A list of files to skip while transforming.
+     *
+     * For example, if you add a directory to {@link preserveLineWidthList} and add a file in that directory to this list,
+     * line width of added file won't be preserved.
+     *
+     * SVGO is still applied to the added files.
+     */
+    skipTransformsList?: (string | RegExp)[];
+    /**
+     * A list of CSS selectors to disable all transforms for. Use it to leave specific elements as-is.
+     *
+     * Can be a list of selectors or selectors-per-files specifiers.
+     *
+     * **You probably don't need this option.** Think of other ways to solve your problem. "Recipes" section
+     * in the demos may help you.
+     *
+     * **Heavy usage may significantly slow down build time.** Limit selectors to specific files to improve performance.
+     */
+    skipTransformsSelectors?: (string | SelectorsPerFiles)[];
+    /**
+     * A list of files to skip loading of. Useful for passing original files to another loader.
+     *
+     * This also can be done in an import: `import imageSrc from "./path/to/image.svg?skip-transforms"`.
+     */
+    skipFilesList?: (string | RegExp)[];
+    /**
+     * Default import type, i.e. what you get without specifying anything in the import URL.
+     *
+     * This also can be done in an import:
+     *
+     * ```ts
+     * // Source code
+     * import imageSrc from "./path/to/image.svg?source";
+     *
+     * // URL
+     * import imageUrl from "./path/to/image.svg?url";
+     *
+     * // Source code Data URI
+     * import imageSrcDataUri from "./path/to/image.svg?source-data-uri";
+     *
+     * // Base64
+     * import imageBase64 from "./path/to/image.svg?base-64";
+     *
+     * // Base64 data URI
+     * import imageBase64DataUri from "./path/to/image.svg?base-64-data-uri";
+     * ```
+     *
+     * @default "source"
+     */
+    defaultImport?: ImportType;
+    /**
+     * A list of files or directories to replace fill, stroke and `<stop>` colors of with `currentColor`.
+     *
+     * Overrides {@link replaceColorsList}.
+     *
+     * @deprecated Deprecated in favor of {@link replaceColorsList}
+     */
+    setCurrentColorList?: (string | RegExp)[];
+    /**
+     * A list of files or directories to disable setting current color of. Overrides {@link setCurrentColorList} and
+     * {@link replaceColorsList}.
+     *
+     * @deprecated Deprecated in favor of {@link replaceColorsList}
+     */
+    skipSetCurrentColorList?: (string | RegExp)[];
+    /**
+     * A list of CSS selectors to disable {@link setCurrentColorList} for.Overrides {@link setCurrentColorList},
+     * {@link replaceColorsList} and {@link skipReplaceColorsSelectors}.
+     *
+     * @deprecated Deprecated in favor of {@link skipReplaceColorsSelectors}
+     */
+    skipSetCurrentColorSelectors?: (string | SelectorsPerFiles)[];
+}
+type ImportType = "url" | "source" | "source-data-uri" | "base64" | "base64-data-uri";
+/**
+ * CSS selector per file or files
+ */
+interface SelectorsPerFiles {
+    /**
+     * List of filenames and/or paths matchers
+     */
+    files: (string | RegExp)[];
+    /**
+     * List of selectors
+     */
+    selectors: string[];
+}
+/**
+ * Maps original SVG colors (case-insensitive) to their replacements
+ */
+type ColorMap = Record<string, string>;
+/**
+ * Maps original SVG colors (case-insensitive) to their replacements. Can be applied to specific files via {@link files} property.
+ *
+ * @example
+ *
+ * {
+ *   // Optional list of files to apply replacements to.
+ *   files: ["my-file.svg", /icon\-*.\.svg/],
+ *
+ *   // Will replace all colors with "red" value with "var(--primary-color)".
+ *   // It'll replace only "red". HEX ("#ff0000"), RGB ("rgb(255, 0, 0)") and other values won't be replaced.
+ *   "red": "var(--primary-color)",
+ *
+ *   // Same as above: this HEX value (case-insensitive) will be replaced with "var(--secondary-color)".
+ *   // Just "blue" or any other values with the same resulting color won't be replaced.
+ *   "#0000ff": "var(--secondary-color)",
+ *
+ *   // Again, only this value (case-insensitive) will be replaced with "var(--tertiary-color)". Any other value will be
+ *   // left as-is.
+ *   "rgb(0, 255, 0)": "var(--tertiary-color)",
+ * }
+ */
+interface ColorMapPerFiles {
+    /**
+     * A list of files to apply replacements to. If omitted, replacements will be applied to all files
+     */
+    files: (string | RegExp)[];
+    /**
+     * Maps original SVG colors (case-insensitive) to their replacements
+     */
+    replacements: ColorMap;
+    /**
+     * Replacement for other colors. Set to empty string to leave colors as-is.
+     *
+     * @default "currentColor"
+     */
+    default?: string;
+}
+
+/**
+ * A Vite plugin that:
+ *
+ * 1. Can import SVGs (see also: {@link SvgLoaderOptions.defaultImport}) as:
+ *    1. Source code (default import type): `import imageSrc from "./path/to/image.svg"`.
+ *    1. URL: `import imageUrl from "./path/to/image.svg?url"`.
+ *    1. Source code data URI: `import imageSrcDataUri from "./path/to/image.svg?source-data-uri"`.
+ *    1. Source code Base64: `import imageBase64 from "./path/to/image.svg?base64"`.
+ *    1. Source code Base64 data URI: `import imageBase64DataUri from "./path/to/image.svg?base64-data-uri"`.
+ *
+ * 1. Can preserve line width (make icons and line art have same line width when scaling):
+ * `import imageSrc from "./path/to/image.svg?preserve-line-width"`.
+ * Can be configured via {@link SvgLoaderOptions.preserveLineWidthList}.
+ *
+ * 1. Can replace colors with `currentColor` (or a custom color via {@link SvgLoaderOptions.replaceColorsList}):
+ * `import imageSrc from "./path/to/image.svg?set-current-color"`.
+ * Can be configured via {@link SvgLoaderOptions.replaceColorsList}.
+ *
+ * 1. Will automatically minimize your SVGs using [SVGO](https://github.com/svg/svgo).
+ *
+ * 1. Allows you to create SVG sprites using provided integrations.
+ *
+ * @param options Plugin options
+ */
+declare function viteAwesomeSvgLoader(options?: SvgLoaderOptions): Plugin;
+
+export { type ColorMap, type ColorMapPerFiles, type ImportType, type SelectorsPerFiles, type SvgLoaderOptions, viteAwesomeSvgLoader };
+import "./declarations";