You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Socket
Socket
Sign inDemoInstall

@neodx/svg

Package Overview
Dependencies
Maintainers
1
Versions
23
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@neodx/svg

Supercharge your icons ⚡️


Version published
Maintainers
1
Created

Readme

Source

@neodx/svg

npm license

Supercharge your icons ⚡️

We're working on the new documentation, please, visit neodx.pages.dev to see the latest version.

  • TypeScript support out of box - generated types and information about your sprites
  • Built-in integrated plugins for all major bundlers: vite, webpack, rollup, esbuild, etc.
  • Optional grouping by folders
  • Optimization with svgo
  • Automatically reset colors

Installation and usage

# npm
npm install -D @neodx/svg
# yarn
yarn add -D @neodx/svg
# pnpm
pnpm add -D @neodx/svg

We're highly recommended to start with our "Getting started" guide.

Integrate with your bundler

For better understanding and to access the latest version, please visit our documentation.

Our plugins are built upon unplugin and provide a consistent interface and working principle across all multiple bundlers and frameworks.

For instance, here's an example of vite plugin with some options:

import svg from '@neodx/svg/vite';

export default defineConfig({
  plugins: [
    svg({
      root: 'assets',
      output: 'public'
    })
  ]
});

It will search for all SVG files in assets folder, group them by folders, optimize them with svgo, reset all colors to currentColor and generate sprites in public folder.

For more details, see our Step-by-step guide.

Features

🆕 Automatically reset colors

Automate your icons and forget about colors management issues.

The problem

When we're working with SVG icons, we always need to control icon colors from our CSS. Well-known approach is to use currentColor inside SVG and set color property in CSS.

However, usually, we have different issues with this approach, for example:

  • Icons are automatically generated, and we can't control their content
  • Icons are not generated, but we don't want to manually edit them (for example, we're using some external library)
  • We have a lot of icons, and we don't want to manually edit them
  • We have different SVG assets: flags, logos, etc. and we want to control their colors separately
The solution

To solve these issues, we're providing a powerful color reset mechanism (resetColors option, enabled by default):

  • Automatically detects all colors in all forms (thx colord) from SVG content
  • Enabled by default to reset all colors (you can disable it with resetColors: false)
  • Multiple configurations for different colors strategies
  • Granular control with colors and files filters

Check out our documentation for more details.

🆕 Content-based hashes and runtime metadata generation

Note: If you used definitions or experimentalRuntime options before, you need to update your configuration, see Migration guide.

By default, you will get the following sprites in your output:

public/
+  sprite-foo.svg
+  sprite-bar.svg

But this is not very good for caching, because if you change any of the SVG files, the sprite filename won't be updated, which could result in an infinite cache.

To solve this issue and achieve content-based hashes in filenames, you need to take three steps:

  1. Provide the fileName option with a hash variable (e.g. fileName: "{name}.{hash:8}.svg")
  2. Configure the metadata option to get additional information about the file path by sprite name during runtime
  3. Update your Icon component (or whatever you use) to support the new runtime information
// vite.config.ts

export default defineConfig({
  plugins: [
    svg({
      root: 'assets',
      output: 'public/sprites',
      fileName: '{name}.{hash:8}.svg',
      metadata: {
        path: 'src/sprite.gen.ts',
        runtime: {
          // generate runtime metadata (path and other information) for each sprite
          size: true, // will add `width` and `height` properties
          viewBox: true // will add `viewBox` property
        }
      }
    })
  ]
});

In the result, you will get the following sprites in your output:

/
├── assets
│   ├── common
│   │   ├── left.svg
│   │   └── right.svg
│   └── actions
│       └── close.svg
├── public
+   └── sprites
+       ├── common.12ghS6Uj.svg
+       └── actions.1A34ks78.svg
└── src
+   └── sprite.gen.ts

To learn how to use it, check out our "Writing an Icon component" guide or detailed basic tutorials:

Step-by-step

It's a simplified tutorial, for detailed one check our "Getting started" guide.

Our example stack details:

  • vite
  • react
  • typescript
  • tailwindcss

We'll be working with the following icons in our project:

/
├── assets
│   ├── common
│   │   ├── left.svg
|   |   ... other icons
│   │   └── right.svg
│   └── actions
│       ... other icons
│       └── close.svg

We want to generate separate sprites for each folder and use them in our React components.

Build icons

import { defineConfig } from 'vite';
import svg from '@neodx/svg/vite';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    react(),
    tsconfigPaths(),
    svg({
      root: 'assets',
      group: true,
      output: 'public/sprites',
      metadata: 'src/shared/ui/icon/sprite.gen.ts'
    })
  ]
});

Now let's run vite (or vite build) and see what we have:

/
├── assets
│   ├── common
│   │   ├── left.svg
│   │   └── right.svg
│   └── actions
│       └── close.svg
├── public
+   └── sprites
+       ├── common.svg
+       └── actions.svg
└── src
    └── shared
        └── ui
            └── icon
+               └── sprite.gen.ts

Now you could visit our "Writing an Icon component" guide to learn how to use it.

Guides

Migrations

Move from definitions and experimentalRuntime options to metadata API

Now metadata is stable and covered under one metadata option.

svg({
-  definitions: 'src/shared/ui/icon/sprite.gen.ts',
-  experimentalRuntime: true,
+  metadata: {
+    path: 'src/shared/ui/icon/sprite.gen.ts',
+    runtime: {
+      size: true,
+      viewBox: true,
+    }
+  }
});

Keywords

FAQs

Package last updated on 21 May 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc