vite-plugin-material-symbols 0.2.0 → 0.2.2

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 (5) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +88 -38
  3. package/dist/index.d.ts +8 -2
  4. package/dist/index.js +1 -1
  5. package/package.json +23 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  ## Version 0
4
4
 
5
+ ### v0.2.2
6
+
7
+ - Performance improvement:
8
+ - using `for..of` and `Array::push()` instead of `Array::from()`.
9
+ - Extracted helpers to make the plugin code more readable.
10
+
11
+ ### v0.2.1
12
+
13
+ - Improving documentation;
14
+ - Clarifying Node.js 20 and 22 as the system requirement.
15
+
5
16
  ### v0.2.0
6
17
 
7
18
  - The `placeholder` is now a complete URL of the Material Symbols CDN;
package/README.md CHANGED
@@ -1,11 +1,70 @@
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
+ Ensure assigning the [required](https://developers.google.com/fonts/docs/material_symbols) `className` to your icons.
52
+ When using Material UI it can be [globally configured](https://mui.com/material-ui/customization/theme-components/):
53
+
54
+ ```ts
55
+ const theme = createTheme({
56
+ components: {
57
+ MuiIcon: {
58
+ defaultProps: {
59
+ /* @see https://fonts.google.com/icons?icon.set=Material+Symbols */
60
+ className: "material-symbols-outlined", // or -rounded or -sharp
61
+ },
62
+ },
63
+ },
64
+ });
65
+ ```
66
+
67
+ ## Usage
9
68
 
10
69
  Consider a sample React component using MUI Icon:
11
70
 
@@ -22,47 +81,38 @@ const Component = () => (
22
81
  );
23
82
  ```
24
83
 
25
- And the Material Symbols linked within `index.html` having `__MATERIAL_SYMBOLS__` placeholder:
84
+ After running `vite build`, that link will have the URL of Material Symbols having the list of required icon names:
26
85
 
27
86
  ```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>
87
+ <link
88
+ href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=chevron_right,comment,home"
89
+ rel="stylesheet"
90
+ />
38
91
  ```
39
92
 
40
- Configuring Vite to use the plugin:
93
+ ## Limitations
41
94
 
42
- ```ts
43
- import { defineConfig } from "vite";
44
- import react from "@vitejs/plugin-react-swc";
45
- import materialSymbols from "vite-plugin-material-symbols";
95
+ The plugin substitutes the `icon_names` URL parameter **ONLY** in `vite build` mode. In `vite dev` (serve) mode
96
+ `index.html` is transformed before the application source code, so that all Material Symbols are loaded.
46
97
 
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
- ```
98
+ ## Configuration
60
99
 
61
- After running `vite build`, that link will have the substituted list of sorted icon names:
100
+ The plugin accepts an object of the following options:
62
101
 
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
- />
102
+ ```yaml
103
+ component:
104
+ type: string
105
+ description: The name of JSX component to obtain the icon names from
106
+ default: Icon
107
+ placeholder:
108
+ type: string
109
+ description: The text within index.html that should be replaced
110
+ default: __MATERIAL_SYMBOLS__
111
+ getUrl:
112
+ type: function
113
+ description: Material Symbols CSS Provider
114
+ arguments: [string] # icon_names parameter
115
+ exampleArguments: ["icon_names=chevron_right,comment,home"] # can be empty string
116
+ returns: string # the URL
117
+ default: (iconNamesParam) => `https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&${iconNamesParam}`
68
118
  ```
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/dist/index.js CHANGED
@@ -1 +1 @@
1
- import esquery from "esquery";const plugin=({placeholder:d="__MATERIAL_SYMBOLS__",component:e="Icon",getUrl:f=(h)=>`https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&${h}`}={})=>{const g=new Set();return {name:"material-symbols",enforce:"pre",moduleParsed:function({id:h,ast:i}){if(!i)return;const j=esquery.query(i,`CallExpression[callee.name='jsx'][arguments.0.name='${e}'] > .arguments > Property[key.name='children'] Literal`);for(const {value:k}of j)if(typeof k==="string")this.debug({id:h,message:k}),g.add(k)},transformIndexHtml:(h)=>h.replace(d,f(g.size?`icon_names=${Array.from(g.values()).toSorted().join(",")}`:""))}};var src_default=plugin;export {src_default as default};
1
+ import esquery from "esquery";const isStringLiteral=(h)=>h.type==="Literal"&&"value"in h&&typeof h.value==="string",defaultUrlProvider=(h)=>`https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&${h}`,makeSelector=(h)=>[`CallExpression[callee.name='jsx'][arguments.0.name='${h}']`,".arguments","Property[key.name='children'] Literal"].join(" > "),makeIconNamesParam=(h)=>{if(!h.size)return "";const i=[];for(const j of h.values())i.push(j);return `icon_names=${i.toSorted().join(",")}`},plugin=({placeholder:h="__MATERIAL_SYMBOLS__",component:i="Icon",getUrl:j=defaultUrlProvider}={})=>{const k=new Set();return {name:"material-symbols",enforce:"pre",moduleParsed:function({id:l,ast:m}){if(!m)return;const n=esquery.query(m,makeSelector(i)).filter(isStringLiteral);for(const {value:o}of n)this.debug({id:l,message:o}),k.add(o)},transformIndexHtml:(l)=>l.replace(h,j(makeIconNamesParam(k)))}};var src_default=plugin;export {src_default as default};
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.2",
4
4
  "description": "Selective loading of Material Symbols for production",
5
5
  "main": "dist/index.js",
6
6
  "repository": {
@@ -16,7 +16,7 @@
16
16
  "build": "tsdown",
17
17
  "postbuild": "attw --pack --profile esm-only",
18
18
  "mdfix": "bunx --bun prettier *.md --write",
19
- "version": "bun run version.ts",
19
+ "version": "bun run tools/version.ts",
20
20
  "prepublishOnly": "bun lint && bun test && bun run build"
21
21
  },
22
22
  "exports": {
@@ -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
  }