vite-plugin-material-symbols 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +72 -38
  3. package/dist/index.d.ts +8 -2
  4. package/package.json +22 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,11 @@
2
2
 
3
3
  ## Version 0
4
4
 
5
+ ### v0.2.1
6
+
7
+ - Improving documentation;
8
+ - Clarifying Node.js 20 and 22 as the system requirement.
9
+
5
10
  ### v0.2.0
6
11
 
7
12
  - The `placeholder` is now a complete URL of the Material Symbols CDN;
package/README.md CHANGED
@@ -1,11 +1,54 @@
1
1
  # vite-plugin-material-symbols
2
2
 
3
+ ![License](https://img.shields.io/github/license/robintail/vite-plugin-material-symbols)
3
4
  [![coverage](https://coveralls.io/repos/github/RobinTail/vite-plugin-material-symbols/badge.svg?branch=main&)](https://coveralls.io/github/RobinTail/vite-plugin-material-symbols?branch=main)
5
+ ![Downloads](https://img.shields.io/npm/dw/vite-plugin-material-symbols)
4
6
 
5
- The plugin determines which Material Symbols are used in JSX `<Icon>` tags and substitutes this list in `index.html`
6
- for selective download from Google CDN, thus reducing the volume of the font downloaded by the user.
7
+ [Material Symbols](https://fonts.google.com/icons?icon.set=Material+Symbols) is a font-based alternative to SVG icons.
8
+ Compared to [Material Icons](https://www.npmjs.com/package/@mui/icons-material), which are packed into a bundle,
9
+ thereby increasing its size, font-based symbols are loaded on the user side upon request.
7
10
 
8
- ## Demo
11
+ However, the difficulty is that they are either loaded all at once, which is also quite a large volume, or it is
12
+ necessary to specify a list of `icon_names` for filtering the font, which must also be sorted. Therefore, it is
13
+ necessary to maintain the list of icons used within the application.
14
+
15
+ The plugin automates that job by determining which icons are used in the source code of the application and during the
16
+ build substitutes that list into `index.html` for selective download from Google Font CDN, thus reducing the volume of
17
+ the font downloaded by the user.
18
+
19
+ ## Requirements
20
+
21
+ - Node.js `^20 || ^22`;
22
+ - Vite `^6.0.0` (though, it might work with v5 as well).
23
+
24
+ ## Installation
25
+
26
+ Install the plugin using your favourite package manager, for example:
27
+
28
+ ```shell
29
+ yarn add -D vite-plugin-material-symbols
30
+ ```
31
+
32
+ Add it to the Vite configuration:
33
+
34
+ ```ts
35
+ // vite.config.ts
36
+ import { defineConfig } from "vite";
37
+ import react from "@vitejs/plugin-react-swc";
38
+ import materialSymbols from "vite-plugin-material-symbols";
39
+
40
+ export default defineConfig({
41
+ plugins: [react(), materialSymbols()],
42
+ });
43
+ ```
44
+
45
+ Add the following line to the `<head>` of your `index.html`:
46
+
47
+ ```html
48
+ <link href="__MATERIAL_SYMBOLS__" rel="stylesheet" />
49
+ ```
50
+
51
+ ## Usage
9
52
 
10
53
  Consider a sample React component using MUI Icon:
11
54
 
@@ -22,47 +65,38 @@ const Component = () => (
22
65
  );
23
66
  ```
24
67
 
25
- And the Material Symbols linked within `index.html` having `__MATERIAL_SYMBOLS__` placeholder:
68
+ After running `vite build`, that link will have the URL of Material Symbols having the list of required icon names:
26
69
 
27
70
  ```html
28
- <!doctype html>
29
- <html lang="en">
30
- <head>
31
- <link href="__MATERIAL_SYMBOLS__" rel="stylesheet" />
32
- </head>
33
- <body>
34
- <div id="root"></div>
35
- <script type="module" src="/src/index.tsx"></script>
36
- </body>
37
- </html>
71
+ <link
72
+ href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=chevron_right,comment,home"
73
+ rel="stylesheet"
74
+ />
38
75
  ```
39
76
 
40
- Configuring Vite to use the plugin:
77
+ ## Limitations
41
78
 
42
- ```ts
43
- import { defineConfig } from "vite";
44
- import react from "@vitejs/plugin-react-swc";
45
- import materialSymbols from "vite-plugin-material-symbols";
79
+ The plugin substitutes the `icon_names` URL parameter **ONLY** in `vite build` mode. In `vite dev` (serve) mode
80
+ `index.html` is transformed before the application source code, so that all Material Symbols are loaded.
46
81
 
47
- export default defineConfig({
48
- plugins: [
49
- react(),
50
- materialSymbols({
51
- // these are defaults:
52
- component: "Icon",
53
- placeholder: "__MATERIAL_SYMBOLS__",
54
- getUrl: (iconNamesParam) =>
55
- `https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&${iconNamesParam}`,
56
- }),
57
- ],
58
- });
59
- ```
82
+ ## Configuration
60
83
 
61
- After running `vite build`, that link will have the substituted list of sorted icon names:
84
+ The plugin accepts an object of the following options:
62
85
 
63
- ```html
64
- <link
65
- href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=chevron_right,comment,home"
66
- rel="stylesheet"
67
- />
86
+ ```yaml
87
+ component:
88
+ type: string
89
+ description: The name of JSX component to obtain the icon names from
90
+ default: Icon
91
+ placeholder:
92
+ type: string
93
+ description: The text within index.html that should be replaced
94
+ default: __MATERIAL_SYMBOLS__
95
+ getUrl:
96
+ type: function
97
+ description: Material Symbols CSS Provider
98
+ arguments: [string] # icon_names parameter
99
+ exampleArguments: ["icon_names=chevron_right,comment,home"] # can be empty string
100
+ returns: string # the URL
101
+ default: (iconNamesParam) => `https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&${iconNamesParam}`
68
102
  ```
package/dist/index.d.ts CHANGED
@@ -6,9 +6,15 @@ type PluginOptions = {
6
6
  * @default () => `https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined...&${iconNamesParam}`
7
7
  * */
8
8
  getUrl: (iconNamesParam: string) => string;
9
- /** @default __MATERIAL_SYMBOLS__ */
9
+ /**
10
+ * The text within index.html that should be replaced
11
+ * @default __MATERIAL_SYMBOLS__
12
+ * */
10
13
  placeholder: string;
11
- /** @default Icon */
14
+ /**
15
+ * The name of JSX component to obtain the icon names from
16
+ * @default Icon
17
+ * */
12
18
  component: string;
13
19
  };
14
20
  declare const plugin: ({ placeholder, component, getUrl, }?: Partial<PluginOptions>) => Plugin;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vite-plugin-material-symbols",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Selective loading of Material Symbols for production",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
@@ -29,6 +29,9 @@
29
29
  "dist",
30
30
  "*.md"
31
31
  ],
32
+ "engines": {
33
+ "node": "^20 || ^22"
34
+ },
32
35
  "peerDependencies": {
33
36
  "vite": "^6.0.0"
34
37
  },
@@ -50,5 +53,22 @@
50
53
  "semver": "^7.6.3",
51
54
  "tsdown": "^0.3.1",
52
55
  "typescript": "^5.7.2"
53
- }
56
+ },
57
+ "keywords": [
58
+ "css",
59
+ "html",
60
+ "font",
61
+ "material-design",
62
+ "frontend",
63
+ "icons",
64
+ "material-ui",
65
+ "rollup",
66
+ "style",
67
+ "svg-icons",
68
+ "symbols",
69
+ "icon",
70
+ "font-icons",
71
+ "vite",
72
+ "vitejs"
73
+ ]
54
74
  }