vite-plugin-material-symbols 0.1.1 → 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 (5) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +73 -40
  3. package/dist/index.d.ts +15 -3
  4. package/dist/index.js +1 -1
  5. package/package.json +22 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
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
+
10
+ ### v0.2.0
11
+
12
+ - The `placeholder` is now a complete URL of the Material Symbols CDN;
13
+ - New option `getUrl` is a function returning that URL based on
14
+ the `iconNamesParam` argument;
15
+ - All that allows to keep the HTML link this way:
16
+
17
+ ```html
18
+ <link rel="stylesheet" href="__MATERIAL_SYMBOLS__" />
19
+ ```
20
+
5
21
  ### v0.1.1
6
22
 
7
23
  - Fixed debugging message;
package/README.md CHANGED
@@ -1,11 +1,54 @@
1
1
  # vite-plugin-material-symbols
2
2
 
3
- [![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)
3
+ ![License](https://img.shields.io/github/license/robintail/vite-plugin-material-symbols)
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,48 +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
32
- href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&__MATERIAL_SYMBOLS__"
33
- rel="stylesheet"
34
- />
35
- </head>
36
- <body>
37
- <div id="root"></div>
38
- <script type="module" src="/src/index.tsx"></script>
39
- </body>
40
- </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
+ />
41
75
  ```
42
76
 
43
- Configuring Vite to use the plugin:
77
+ ## Limitations
44
78
 
45
- ```ts
46
- import { defineConfig } from "vite";
47
- import react from "@vitejs/plugin-react-swc";
48
- 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.
49
81
 
50
- export default defineConfig({
51
- plugins: [
52
- react(),
53
- materialSymbols({
54
- // these are defaults:
55
- component: "Icon",
56
- placeholder: "__MATERIAL_SYMBOLS__",
57
- }),
58
- ],
59
- });
60
- ```
82
+ ## Configuration
61
83
 
62
- 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:
63
85
 
64
- ```html
65
- <link
66
- href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=chevron_right,comment,home"
67
- rel="stylesheet"
68
- />
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}`
69
102
  ```
package/dist/index.d.ts CHANGED
@@ -1,9 +1,21 @@
1
1
  import type { Plugin } from "vite";
2
2
  type PluginOptions = {
3
- /** @default __MATERIAL_SYMBOLS__ */
3
+ /**
4
+ * Material Symbols CSS Provider. Default: outlined, no infill, 24px, weight 400
5
+ * @see https://fonts.google.com/icons?icon.set=Material+Symbols
6
+ * @default () => `https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined...&${iconNamesParam}`
7
+ * */
8
+ getUrl: (iconNamesParam: string) => string;
9
+ /**
10
+ * The text within index.html that should be replaced
11
+ * @default __MATERIAL_SYMBOLS__
12
+ * */
4
13
  placeholder: string;
5
- /** @default Icon */
14
+ /**
15
+ * The name of JSX component to obtain the icon names from
16
+ * @default Icon
17
+ * */
6
18
  component: string;
7
19
  };
8
- declare const plugin: ({ placeholder, component, }?: Partial<PluginOptions>) => Plugin;
20
+ declare const plugin: ({ placeholder, component, getUrl, }?: Partial<PluginOptions>) => Plugin;
9
21
  export default plugin;
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- import esquery from "esquery";const plugin=({placeholder:d="__MATERIAL_SYMBOLS__",component:e="Icon"}={})=>{const f=new Set();return {name:"material-symbols",enforce:"pre",moduleParsed:function({id:g,ast:h}){if(!h)return;const i=esquery.query(h,`CallExpression[callee.name='jsx'][arguments.0.name='${e}'] > .arguments > Property[key.name='children'] Literal`);for(const {value:j}of i)if(typeof j==="string")this.debug({id:g,message:j}),f.add(j)},transformIndexHtml:(g)=>g.replace(d,f.size?`icon_names=${Array.from(f.values()).toSorted().join(",")}`:"")}};var src_default=plugin;export {src_default as default};
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};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vite-plugin-material-symbols",
3
- "version": "0.1.1",
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
  }