igniteui-cli 15.8.0 → 15.8.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.
- package/package.json +4 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/client-scripts.md +7 -7
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +65 -18
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +1 -1
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +5 -5
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +23 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +4 -3
- package/templates/react/igr-ts/constants.d.ts +1 -1
- package/templates/react/igr-ts/constants.js +1 -1
- package/templates/webcomponents/igc-ts/constants.d.ts +1 -1
- package/templates/webcomponents/igc-ts/constants.js +1 -1
- package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +1 -1
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/README.md +15 -15
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-choose-components/SKILL.md +36 -36
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-choose-components/reference/mcp-setup.md +8 -6
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-customize-component-theme/SKILL.md +62 -60
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-customize-component-theme/references/mcp-setup.md +8 -6
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/SKILL.md +107 -94
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/asset-extraction.md +32 -32
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/design-provenance.md +32 -30
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/design-token-bridge.md +84 -71
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/figma-component-map.md +45 -44
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/figma-exploration.md +57 -51
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/mcp-setup.md +23 -23
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/project-setup.md +28 -26
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/theme-generation.md +45 -35
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/validation-patterns.md +38 -29
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-generate-from-image-design/SKILL.md +63 -63
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-generate-from-image-design/references/component-mapping.md +12 -12
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-generate-from-image-design/references/gotchas.md +24 -24
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-grids/SKILL.md +23 -23
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/SKILL.md +23 -23
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/angular.md +10 -10
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/react.md +9 -9
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/vanilla-js.md +9 -9
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/vue.md +11 -11
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-migrate-grid-lite-to-premium/SKILL.md +18 -18
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-optimize-bundle-size/SKILL.md +78 -48
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Integrating Ignite UI Web Components — Vanilla JavaScript / HTML
|
|
2
2
|
|
|
3
|
-
> Package note: This page shows the default setup for `igniteui-webcomponents`. If the routing step selected `igniteui-webcomponents-charts`, `igniteui-webcomponents-grids`, `igniteui-grid-lite`, or `igniteui-dockmanager`,
|
|
3
|
+
> Package note: This page shows the default setup for `igniteui-webcomponents`. If the routing step selected `igniteui-webcomponents-charts`, `igniteui-webcomponents-grids`, `igniteui-grid-lite`, or `igniteui-dockmanager`, use the setup of that package for the package-specific steps below. These are the install, import, and registration steps.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ npm install igniteui-webcomponents
|
|
|
10
10
|
|
|
11
11
|
## Setup
|
|
12
12
|
|
|
13
|
-
In your main JavaScript/TypeScript entry file, import a theme and register the components you need:
|
|
13
|
+
In your main JavaScript/TypeScript entry file, import a theme and register the components that you need:
|
|
14
14
|
|
|
15
15
|
```typescript
|
|
16
16
|
// 1. Import a theme (required for correct styling)
|
|
@@ -22,7 +22,7 @@ import { defineComponents, IgcButtonComponent, IgcInputComponent } from 'igniteu
|
|
|
22
22
|
defineComponents(IgcButtonComponent, IgcInputComponent);
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
To register all components at
|
|
25
|
+
To register all components at the same time (this increases the bundle size):
|
|
26
26
|
|
|
27
27
|
```typescript
|
|
28
28
|
import 'igniteui-webcomponents/themes/light/bootstrap.css';
|
|
@@ -57,7 +57,7 @@ defineAllComponents();
|
|
|
57
57
|
|
|
58
58
|
## TypeScript Support
|
|
59
59
|
|
|
60
|
-
The `igniteui-webcomponents` package automatically
|
|
60
|
+
The `igniteui-webcomponents` package automatically includes global type declarations for all components in `HTMLElementTagNameMap`. DOM queries are fully typed without more configuration:
|
|
61
61
|
|
|
62
62
|
```typescript
|
|
63
63
|
import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents';
|
|
@@ -79,7 +79,7 @@ const button = document.querySelector('igc-button') as IgcButtonComponent;
|
|
|
79
79
|
|
|
80
80
|
## Working with Complex Properties
|
|
81
81
|
|
|
82
|
-
Attributes only
|
|
82
|
+
Attributes accept only strings. For objects and arrays, use JavaScript to set the properties:
|
|
83
83
|
|
|
84
84
|
```typescript
|
|
85
85
|
// ❌ Wrong — attributes only accept strings
|
|
@@ -111,9 +111,9 @@ document.body.innerHTML = '<igc-button>Click</igc-button>';
|
|
|
111
111
|
|
|
112
112
|
### No styles applied
|
|
113
113
|
|
|
114
|
-
|
|
114
|
+
Make sure that you import a theme CSS file in your entry point. Without it, components render without styles.
|
|
115
115
|
|
|
116
|
-
**`igniteui-webcomponents-grids` inside a Shadow root:** A bare `import '...css'`
|
|
116
|
+
**`igniteui-webcomponents-grids` inside a Shadow root:** A bare `import '...css'` puts the styles in the document head, not in a Shadow root. The internal structure and elements of the grid then get no styles and render with incorrect dimensions. Import the theme as an inline string. Add it as a `<style>` tag in the shadow root. This needs bundler support for `?inline`, for example Vite. For a LitElement component:
|
|
117
117
|
|
|
118
118
|
```typescript
|
|
119
119
|
import { html } from 'lit';
|
|
@@ -129,6 +129,6 @@ render() {
|
|
|
129
129
|
|
|
130
130
|
## Next Steps
|
|
131
131
|
|
|
132
|
-
- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/SKILL.md) — import only the components you use
|
|
132
|
+
- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/SKILL.md) — import only the components that you use
|
|
133
133
|
- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors
|
|
134
|
-
- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference
|
|
134
|
+
- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — the full API reference
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Integrating Ignite UI Web Components — Vue 3
|
|
2
2
|
|
|
3
|
-
> Package note: This page shows the default setup for `igniteui-webcomponents`. If the routing step selected `igniteui-webcomponents-charts`, `igniteui-webcomponents-grids`, `igniteui-grid-lite`, or `igniteui-dockmanager`,
|
|
3
|
+
> Package note: This page shows the default setup for `igniteui-webcomponents`. If the routing step selected `igniteui-webcomponents-charts`, `igniteui-webcomponents-grids`, `igniteui-grid-lite`, or `igniteui-dockmanager`, use the setup of that package for the package-specific steps below. These are the install, import, and registration steps.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -12,7 +12,7 @@ npm install igniteui-webcomponents
|
|
|
12
12
|
|
|
13
13
|
### Step 1 — Configure Vue to recognize custom elements
|
|
14
14
|
|
|
15
|
-
Vue
|
|
15
|
+
Vue must know which tags are custom elements. If it does not know, Vue shows warnings about unknown components.
|
|
16
16
|
|
|
17
17
|
**With Vite** (`vite.config.ts`):
|
|
18
18
|
|
|
@@ -54,7 +54,7 @@ module.exports = {
|
|
|
54
54
|
|
|
55
55
|
### Step 2 — Register the theme and components
|
|
56
56
|
|
|
57
|
-
In `src/main.ts`, import a theme and register the components before
|
|
57
|
+
In `src/main.ts`, import a theme and register the components before you mount the app:
|
|
58
58
|
|
|
59
59
|
```typescript
|
|
60
60
|
import { createApp } from 'vue';
|
|
@@ -111,7 +111,7 @@ const handleChange = (event: CustomEvent) => {
|
|
|
111
111
|
|
|
112
112
|
## Working with Complex Properties
|
|
113
113
|
|
|
114
|
-
Attributes only
|
|
114
|
+
Attributes accept only strings. Use a template ref to pass objects and arrays:
|
|
115
115
|
|
|
116
116
|
```vue
|
|
117
117
|
<template>
|
|
@@ -138,7 +138,7 @@ onMounted(() => {
|
|
|
138
138
|
|
|
139
139
|
| Concern | Details |
|
|
140
140
|
|---------|---------|
|
|
141
|
-
| **isCustomElement** | Required in Vite/CLI config so Vue
|
|
141
|
+
| **isCustomElement** | Required in Vite/CLI config so that Vue does not treat `igc-*` tags as unresolved components |
|
|
142
142
|
| **Event binding** | Use `@igcInput`, `@igcChange`, etc. — not `@input` or `@change` |
|
|
143
143
|
| **Property binding** | Use `:property="value"` or `v-bind:property="value"` for reactive data |
|
|
144
144
|
| **Complex data** | Use a template ref and set the property in `onMounted` |
|
|
@@ -160,24 +160,24 @@ const button = document.querySelector('igc-button');
|
|
|
160
160
|
|
|
161
161
|
### Vue warns "Unknown custom element: igc-button"
|
|
162
162
|
|
|
163
|
-
Configure `isCustomElement` in `vite.config.ts` (or `vue.config.js`) so Vue
|
|
163
|
+
Configure `isCustomElement` in `vite.config.ts` (or `vue.config.js`) so that Vue does not try to resolve `igc-*` tags.
|
|
164
164
|
|
|
165
165
|
### Events not firing
|
|
166
166
|
|
|
167
|
-
Use Vue
|
|
167
|
+
Use the Vue `@igcInput` / `@igcChange` syntax. Ignite UI components emit custom events with a prefix. Standard DOM events such as `input` or `change` behave differently.
|
|
168
168
|
|
|
169
169
|
### No styles applied
|
|
170
170
|
|
|
171
|
-
|
|
171
|
+
Make sure that you import a theme CSS file in `main.ts` before `createApp`. Without it, components render without styles.
|
|
172
172
|
|
|
173
173
|
### Complex data not reflecting
|
|
174
174
|
|
|
175
|
-
|
|
175
|
+
Use a `ref` in `onMounted` to set objects and arrays. Do not bind them as HTML attributes. Attributes accept only serialized strings.
|
|
176
176
|
|
|
177
177
|
---
|
|
178
178
|
|
|
179
179
|
## Next Steps
|
|
180
180
|
|
|
181
|
-
- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/) — import only the components you use
|
|
181
|
+
- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/) — import only the components that you use
|
|
182
182
|
- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors
|
|
183
|
-
- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference
|
|
183
|
+
- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — the full API reference
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
license: MIT
|
|
3
3
|
name: igniteui-wc-migrate-grid-lite-to-premium
|
|
4
|
-
description: "
|
|
4
|
+
description: "Migrate step by step from igniteui-grid-lite (IgcGridLite, igc-grid-lite) to the premium igniteui-webcomponents-grids data grid (IgcGridComponent, igc-grid). Covers the changes to imports, class names, HTML tags, properties, events, templates, sorting, filtering, remote data, and the theming API. WHEN TO USE: the user wants to upgrade from Grid Lite to the premium grid, or needs enterprise features that Grid Lite does not have (editing, selection, paging, grouping, summaries, Excel export, state persistence). WHEN NOT TO USE: the user starts a new grid (use choose-components), migrates between other grids (Tree Grid, Hierarchical Grid, Pivot Grid) or across major versions of the same package, the project uses igniteui-angular or Blazor grids, or the user needs only theming (use customize-component-theme)."
|
|
5
5
|
user-invocable: true
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -9,17 +9,17 @@ user-invocable: true
|
|
|
9
9
|
|
|
10
10
|
## Purpose
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Use this skill to migrate a project from **Grid Lite** (`igniteui-grid-lite`, MIT licensed, `<igc-grid-lite>`) to the **Premium Data Grid** (`igniteui-webcomponents-grids`, commercially licensed, `<igc-grid>`). Grid Lite has read-only capabilities. Use this skill when the project needs enterprise features, for example editing, selection, paging, grouping, summaries, Excel export, or state persistence.
|
|
13
13
|
|
|
14
14
|
## MANDATORY AGENT PROTOCOL
|
|
15
15
|
|
|
16
16
|
> **DO NOT write any code from memory.** Grid APIs change between versions.
|
|
17
17
|
|
|
18
|
-
Before
|
|
18
|
+
Before you write migration code:
|
|
19
19
|
|
|
20
|
-
1. **Identify the current Grid Lite usage** - read the
|
|
21
|
-
2. **Use the MCP server** - call `mcp_igniteui-cli_get_api_reference` or `mcp_igniteui-cli_get_doc` (framework: `webcomponents`) to verify
|
|
22
|
-
3. **Only then produce output** -
|
|
20
|
+
1. **Identify the current Grid Lite usage** - read the existing TypeScript and HTML files of the user. Find the column configuration, cell templates, data binding, and any `dataPipelineConfiguration` usage.
|
|
21
|
+
2. **Use the MCP server** - when you are not sure about an API detail, call `mcp_igniteui-cli_get_api_reference` or `mcp_igniteui-cli_get_doc` (framework: `webcomponents`) to verify it.
|
|
22
|
+
3. **Only then produce output** - write all code from verified references, not from memory.
|
|
23
23
|
|
|
24
24
|
---
|
|
25
25
|
|
|
@@ -47,15 +47,15 @@ Migrate from Grid Lite to the Premium Grid when the user needs **any** of these
|
|
|
47
47
|
| Clipboard support | No | Yes |
|
|
48
48
|
| Cell merging | No | Yes |
|
|
49
49
|
|
|
50
|
-
> **IMPORTANT:** The upgrade path from Grid Lite is **always** to `IgcGridComponent` (`<igc-grid>`).
|
|
50
|
+
> **IMPORTANT:** The upgrade path from Grid Lite is **always** to `IgcGridComponent` (`<igc-grid>`). Do not recommend a different component type as a substitute.
|
|
51
51
|
|
|
52
52
|
---
|
|
53
53
|
|
|
54
54
|
## Step 1 - Install / Verify the Premium Package
|
|
55
55
|
|
|
56
|
-
Grid Lite uses the separate `igniteui-grid-lite` npm package. The Premium Grid
|
|
56
|
+
Grid Lite uses the separate `igniteui-grid-lite` npm package. The Premium Grid is in the `igniteui-webcomponents-grids` package (or `@infragistics/igniteui-webcomponents-grids` for licensed builds).
|
|
57
57
|
|
|
58
|
-
> **AGENT INSTRUCTION:** Check `package.json` to
|
|
58
|
+
> **AGENT INSTRUCTION:** Check `package.json` to find which package variant is installed. If only `igniteui-grid-lite` is present, the user must install the premium package.
|
|
59
59
|
|
|
60
60
|
```bash
|
|
61
61
|
# Remove Grid Lite
|
|
@@ -114,7 +114,7 @@ import {
|
|
|
114
114
|
import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.css?inline';
|
|
115
115
|
```
|
|
116
116
|
|
|
117
|
-
> **Grid inside a Shadow root — required step:** A bare CSS import
|
|
117
|
+
> **Grid inside a Shadow root — required step:** A bare CSS import goes into the document head. It does not go into a Shadow root, so the internal structure and elements of the grid get no styles. Inject the theme as a `<style>` tag inside the shadow root. For a LitElement component, put the tag at the top of `render()`:
|
|
118
118
|
> ```typescript
|
|
119
119
|
> render() {
|
|
120
120
|
> return html`
|
|
@@ -153,7 +153,7 @@ import gridTheme from 'igniteui-webcomponents-grids/grids/themes/light/material.
|
|
|
153
153
|
</igc-grid>
|
|
154
154
|
```
|
|
155
155
|
|
|
156
|
-
> **Note:** `allow-filtering="true"` on `<igc-grid
|
|
156
|
+
> **Note:** To enable filtering, set `allow-filtering="true"` on `<igc-grid>`. Grid Lite has no grid-level filter toggle.
|
|
157
157
|
|
|
158
158
|
## Step 4 - Update TypeScript References
|
|
159
159
|
|
|
@@ -188,17 +188,17 @@ const column = document.querySelector('igc-column[field="name"]') as IgcColumnCo
|
|
|
188
188
|
|
|
189
189
|
**Custom sort strategy migration:**
|
|
190
190
|
|
|
191
|
-
The Premium Grid
|
|
192
|
-
|
|
191
|
+
The Premium Grid does not export a base class for sort strategies. It exports `IgcSortingStrategy`
|
|
192
|
+
as a type only, and the built-in default strategy is internal. A column's `sortStrategy` can be any object that has this method:
|
|
193
193
|
|
|
194
194
|
```typescript
|
|
195
195
|
sort(data: any[], fieldName: string, dir: SortingDirection, ignoreCase: boolean,
|
|
196
196
|
valueResolver: (record: any, fieldName: string, isDate?: boolean, isTime?: boolean) => any): any[]
|
|
197
197
|
```
|
|
198
198
|
|
|
199
|
-
|
|
200
|
-
`valueResolver`, not `record[fieldName]
|
|
201
|
-
date/time columns work.
|
|
199
|
+
The method receives the full data array and returns it sorted. Read cell values through
|
|
200
|
+
`valueResolver`, not through `record[fieldName]`. This makes sure that nested fields (for example,
|
|
201
|
+
`address.city`) and date/time columns work.
|
|
202
202
|
|
|
203
203
|
```typescript
|
|
204
204
|
// Before (Grid Lite) - function comparer on column
|
|
@@ -366,7 +366,7 @@ grid.filteringExpressionsTree = tree;
|
|
|
366
366
|
|
|
367
367
|
## Adding Enterprise Features Post-Migration
|
|
368
368
|
|
|
369
|
-
|
|
369
|
+
After you migrate to the Premium Grid, enable the features that were the reason for the migration:
|
|
370
370
|
|
|
371
371
|
### Row Editing
|
|
372
372
|
|
|
@@ -377,7 +377,7 @@ Once on the Premium Grid, enable the features that motivated the migration:
|
|
|
377
377
|
</igc-grid>
|
|
378
378
|
```
|
|
379
379
|
|
|
380
|
-
> **Note:** `primary-key`
|
|
380
|
+
> **Note:** We strongly recommend that you set `primary-key` when you use editing, selection, or row-targeted APIs (`getRowByKey`, row pinning, transactions). Without it, the grid uses object identity. Object identity breaks across virtualization and remote data.
|
|
381
381
|
|
|
382
382
|
### Row Selection
|
|
383
383
|
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
license: MIT
|
|
3
3
|
name: igniteui-wc-optimize-bundle-size
|
|
4
|
-
description: "Reduce application bundle size with Ignite UI Web Components
|
|
4
|
+
description: "Reduce the application bundle size with Ignite UI Web Components. Register only the necessary components with named imports from the package root and defineComponents, not defineAllComponents. Lazy-load large components, bundle one theme, and use bundle analysis to verify tree-shaking. WHEN TO USE: the user reports a large bundle or a slow load, asks how to import components one at a time, wants to ship only one of the four themes, wants to lazy-load grids, charts, or dock manager, or needs to audit Ignite UI imports in Vite/webpack/Rollup builds. WHEN NOT TO USE: initial package installation or framework configuration (use integrate-with-framework), choosing components (use choose-components), theming (use customize-component-theme), or general performance problems that are not related to bundle size, such as runtime rendering or data virtualization."
|
|
5
5
|
user-invocable: true
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Optimize Bundle Size
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Use this skill to reduce the bundle size of an application that uses Ignite UI Web Components. Import only the necessary components. Follow the best practices for tree-shaking.
|
|
11
11
|
|
|
12
12
|
## Example Usage
|
|
13
13
|
|
|
@@ -19,23 +19,24 @@ This skill helps users minimize their application's bundle size when using Ignit
|
|
|
19
19
|
|
|
20
20
|
## Related Skills
|
|
21
21
|
|
|
22
|
-
- [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) -
|
|
22
|
+
- [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) - Correct integration setup
|
|
23
23
|
- [igniteui-wc-customize-component-theme](../igniteui-wc-customize-component-theme/SKILL.md) - Theming after optimization
|
|
24
24
|
|
|
25
25
|
## When to Use
|
|
26
26
|
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
27
|
+
- The user's bundle size is too large
|
|
28
|
+
- The user wants to optimize the app for production
|
|
29
|
+
- The user imports more components than necessary
|
|
30
|
+
- The user asks about tree-shaking or optimization
|
|
31
|
+
- The user wants faster load times
|
|
32
32
|
|
|
33
33
|
## Key Principles
|
|
34
34
|
|
|
35
|
-
1. **Import only what you use** -
|
|
36
|
-
2. **Use named imports** -
|
|
37
|
-
3. **Analyze your bundle** - Identify what
|
|
38
|
-
4. **Lazy load when possible** - Load components
|
|
35
|
+
1. **Import only what you use** - Do not use `defineAllComponents()`
|
|
36
|
+
2. **Use named imports** - Named imports enable tree-shaking
|
|
37
|
+
3. **Analyze your bundle** - Identify what the bundle includes
|
|
38
|
+
4. **Lazy load when possible** - Load components only when the app needs them
|
|
39
|
+
5. **Bundle one theme** - Set an `igc-theme-<name>` condition if the app uses only one theme
|
|
39
40
|
|
|
40
41
|
## Import Strategies
|
|
41
42
|
|
|
@@ -48,7 +49,7 @@ import { defineAllComponents } from 'igniteui-webcomponents';
|
|
|
48
49
|
defineAllComponents();
|
|
49
50
|
```
|
|
50
51
|
|
|
51
|
-
**Impact:**
|
|
52
|
+
**Impact:** The bundle includes all 60+ components, also the components that you do not use.
|
|
52
53
|
|
|
53
54
|
### ✅ Good: Import Specific Components
|
|
54
55
|
|
|
@@ -64,11 +65,11 @@ import {
|
|
|
64
65
|
defineComponents(IgcButtonComponent, IgcInputComponent, IgcCardComponent);
|
|
65
66
|
```
|
|
66
67
|
|
|
67
|
-
**Impact:**
|
|
68
|
+
**Impact:** The bundle includes only 3 components and their dependencies.
|
|
68
69
|
|
|
69
70
|
## React Applications
|
|
70
71
|
|
|
71
|
-
If you
|
|
72
|
+
If you use React, you can use the **`igniteui-react`** package instead of `igniteui-webcomponents`. It has the same components with React-friendly wrappers. It usually gives better tree-shaking:
|
|
72
73
|
|
|
73
74
|
```bash
|
|
74
75
|
npm install igniteui-react
|
|
@@ -90,27 +91,27 @@ function MyComponent() {
|
|
|
90
91
|
```
|
|
91
92
|
|
|
92
93
|
**Benefits for bundle size:**
|
|
93
|
-
- Automatic tree-shaking (only imported components
|
|
94
|
-
- No
|
|
94
|
+
- Automatic tree-shaking (the bundle includes only the imported components)
|
|
95
|
+
- No component registration overhead
|
|
95
96
|
- Better integration with React build tools
|
|
96
97
|
|
|
97
98
|
For more details, see the [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) skill.
|
|
98
99
|
|
|
99
100
|
## Analyzing Your Bundle
|
|
100
101
|
|
|
101
|
-
Use a bundle analyzer to identify
|
|
102
|
+
Use a bundle analyzer to identify the contents of the bundle before and after optimization.
|
|
102
103
|
|
|
103
104
|
**Vite projects** — [rollup-plugin-visualizer](https://www.npmjs.com/package/rollup-plugin-visualizer):
|
|
104
105
|
```bash
|
|
105
106
|
npm install --save-dev rollup-plugin-visualizer
|
|
106
107
|
```
|
|
107
|
-
Add `visualizer()` to the Vite `plugins` array
|
|
108
|
+
Add `visualizer()` to the Vite `plugins` array. Then run `npm run build`. The plugin opens a treemap in the browser.
|
|
108
109
|
|
|
109
110
|
**Webpack projects** — [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer):
|
|
110
111
|
```bash
|
|
111
112
|
npm install --save-dev webpack-bundle-analyzer
|
|
112
113
|
```
|
|
113
|
-
Add `BundleAnalyzerPlugin` to `webpack.config.js
|
|
114
|
+
Add `BundleAnalyzerPlugin` to the plugins in `webpack.config.js`. Then run `npm run build`.
|
|
114
115
|
|
|
115
116
|
**Framework-agnostic** — [source-map-explorer](https://www.npmjs.com/package/source-map-explorer):
|
|
116
117
|
```bash
|
|
@@ -134,7 +135,7 @@ grep -roh "igc-[a-z-]*" src/ | sort | uniq
|
|
|
134
135
|
|
|
135
136
|
### 2. Compare with Your Imports
|
|
136
137
|
|
|
137
|
-
|
|
138
|
+
Compare the components that you import with the components that you use:
|
|
138
139
|
|
|
139
140
|
```typescript
|
|
140
141
|
// Find in your code
|
|
@@ -150,7 +151,7 @@ import {
|
|
|
150
151
|
|
|
151
152
|
### 3. Remove Unused Imports
|
|
152
153
|
|
|
153
|
-
Remove components you
|
|
154
|
+
Remove the components that you do not use:
|
|
154
155
|
|
|
155
156
|
```typescript
|
|
156
157
|
// Before: 5 components imported
|
|
@@ -184,7 +185,7 @@ defineComponents(IgcButtonComponent, IgcInputComponent, IgcCardComponent);
|
|
|
184
185
|
|
|
185
186
|
## Lazy Loading Components
|
|
186
187
|
|
|
187
|
-
|
|
188
|
+
To make the initial bundle smaller, load components only when the app needs them.
|
|
188
189
|
|
|
189
190
|
### Vanilla JavaScript / TypeScript
|
|
190
191
|
|
|
@@ -314,11 +315,11 @@ export class MyComponent {
|
|
|
314
315
|
|
|
315
316
|
## Route-Based Code Splitting
|
|
316
317
|
|
|
317
|
-
Load Ignite UI components only for the routes that need them
|
|
318
|
+
Load Ignite UI components only for the routes that need them. To do this, put the `defineComponents(...)` calls in the lazy-loaded route module for each framework.
|
|
318
319
|
|
|
319
320
|
### React (using React.lazy)
|
|
320
321
|
|
|
321
|
-
Put component imports and `defineComponents` at the top of each page module. React
|
|
322
|
+
Put the component imports and `defineComponents` at the top of each page module. React `lazy()` + `Suspense` does the async split:
|
|
322
323
|
|
|
323
324
|
```tsx
|
|
324
325
|
// pages/Dashboard.tsx
|
|
@@ -336,7 +337,7 @@ function Dashboard() {
|
|
|
336
337
|
}
|
|
337
338
|
```
|
|
338
339
|
|
|
339
|
-
|
|
340
|
+
To put `pages/Dashboard` in a separate chunk, refer to the lazy-loading documentation of your router (React Router, TanStack Router, etc.).
|
|
340
341
|
|
|
341
342
|
### Vue 3
|
|
342
343
|
|
|
@@ -354,34 +355,63 @@ onMounted(async () => {
|
|
|
354
355
|
</script>
|
|
355
356
|
```
|
|
356
357
|
|
|
357
|
-
Refer to Vue Router
|
|
358
|
+
Refer to the Vue Router documentation for the `() => import('./views/Dashboard.vue')` lazy-route syntax.
|
|
358
359
|
|
|
359
360
|
### Angular
|
|
360
361
|
|
|
361
|
-
|
|
362
|
+
Put `defineComponents(...)` in the module or component of the route. Then only that lazy chunk includes it. Refer to the Angular Router documentation for `loadChildren` / `loadComponent` lazy loading.
|
|
362
363
|
|
|
363
364
|
## Build Configuration Optimizations
|
|
364
365
|
|
|
365
|
-
|
|
366
|
+
Make sure that your build tool runs in production mode with minification enabled. For Vite, `vite build` does this by default. For Webpack, set `mode: 'production'`.
|
|
366
367
|
|
|
367
|
-
To reduce chunk-size warnings from Ignite UI components, increase the `chunkSizeWarningLimit` in Vite
|
|
368
|
+
To reduce chunk-size warnings from Ignite UI components, increase the `chunkSizeWarningLimit` in Vite. In Webpack, configure `splitChunks` to put the `igniteui-*` packages in a named vendor chunk. For the exact configuration options, refer to the documentation of your build tool.
|
|
369
|
+
|
|
370
|
+
## Bundle Only One Theme
|
|
371
|
+
|
|
372
|
+
Each component ships the styles of all four themes (Material, Bootstrap, Indigo and Fluent) and applies the active one. If the app uses only one theme, set the `igc-theme-<name>` condition in the bundler. The bundle then contains only the component styles of that theme, light and dark, and is approximately 15–17% smaller after gzip.
|
|
373
|
+
|
|
374
|
+
For example, in Vite:
|
|
375
|
+
|
|
376
|
+
```typescript
|
|
377
|
+
// vite.config.ts
|
|
378
|
+
import { defaultClientConditions, defineConfig } from 'vite';
|
|
379
|
+
|
|
380
|
+
export default defineConfig({
|
|
381
|
+
resolve: { conditions: ['igc-theme-bootstrap', ...defaultClientConditions] },
|
|
382
|
+
});
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
| Tool | Setting |
|
|
386
|
+
|---|---|
|
|
387
|
+
| Vite | `resolve: { conditions: ['igc-theme-bootstrap', ...defaultClientConditions] }`, with `defaultClientConditions` imported from `vite`. For SSR, also set `ssr.resolve.conditions` with `defaultServerConditions`. |
|
|
388
|
+
| webpack | `resolve: { conditionNames: ['igc-theme-bootstrap', '...'] }` |
|
|
389
|
+
| esbuild | `conditions: ['igc-theme-bootstrap']` |
|
|
390
|
+
| Rollup | `nodeResolve({ exportConditions: ['igc-theme-bootstrap'] })` |
|
|
391
|
+
| Node.js (SSR) | `node --conditions=igc-theme-bootstrap server.js` |
|
|
392
|
+
|
|
393
|
+
- The conditions are `igc-theme-material`, `igc-theme-bootstrap`, `igc-theme-indigo` and `igc-theme-fluent`. Set only one.
|
|
394
|
+
- Use the condition only if the app does not call `configureTheme()` with another theme. A theme that is not in the bundle gives only the structural styles.
|
|
395
|
+
- The app still loads the global theme CSS, for example `igniteui-webcomponents/themes/light/bootstrap.css`.
|
|
396
|
+
- `igniteui-react` uses `igniteui-webcomponents`, so the same condition applies.
|
|
368
397
|
|
|
369
398
|
## Size Comparison
|
|
370
399
|
|
|
371
|
-
|
|
400
|
+
The actual sizes depend mostly on the components that you import. Grid and chart components are much larger than UI components. Use your bundle analyzer to measure the real effect in your project. Do not rely on generic estimates.
|
|
372
401
|
|
|
373
|
-
The key rule:
|
|
402
|
+
The key rule: import a subset of components with `defineComponents()`, not all components with `defineAllComponents()`. The bundle then decreases by the size of each component that you do not include. It also decreases by the size of all exclusive dependencies of these components.
|
|
374
403
|
|
|
375
404
|
## Best Practices Checklist
|
|
376
405
|
|
|
377
|
-
- [ ] **
|
|
378
|
-
- [ ] **Use `defineComponents()` with specific components** you need
|
|
379
|
-
- [ ] **Audit your imports regularly** - remove
|
|
406
|
+
- [ ] **Do not use `defineAllComponents()`** if the app does not need every component
|
|
407
|
+
- [ ] **Use `defineComponents()` with the specific components** that you need
|
|
408
|
+
- [ ] **Audit your imports regularly** - remove the components that you do not use
|
|
380
409
|
- [ ] **Lazy load rarely-used components** (dialogs, modals, etc.)
|
|
410
|
+
- [ ] **Set an `igc-theme-<name>` condition** if the app uses only one theme
|
|
381
411
|
- [ ] **Split by routes** - load components only for active routes
|
|
382
412
|
- [ ] **Analyze your bundle** - use bundle analyzer tools
|
|
383
413
|
- [ ] **Enable tree-shaking** - use named imports, not side-effect imports
|
|
384
|
-
- [ ] **Minify in production** -
|
|
414
|
+
- [ ] **Minify in production** - enable minification in the build tool
|
|
385
415
|
- [ ] **Use compression** - enable gzip/brotli on your server
|
|
386
416
|
|
|
387
417
|
## Common Issues and Solutions
|
|
@@ -390,11 +420,11 @@ The key rule: importing a subset of components with `defineComponents()` instead
|
|
|
390
420
|
|
|
391
421
|
**Investigate:**
|
|
392
422
|
|
|
393
|
-
1. Check if you
|
|
394
|
-
2.
|
|
395
|
-
3.
|
|
396
|
-
4. Check if
|
|
397
|
-
5. For React,
|
|
423
|
+
1. Check if you import many components at the same time
|
|
424
|
+
2. Make sure that tree-shaking works (check the build output)
|
|
425
|
+
3. Search for duplicate dependencies
|
|
426
|
+
4. Check if the production build includes source maps
|
|
427
|
+
5. For React, make sure that you use `igniteui-react` instead of `igniteui-webcomponents`
|
|
398
428
|
|
|
399
429
|
**Solutions:**
|
|
400
430
|
|
|
@@ -418,7 +448,7 @@ async function loadDialog() {
|
|
|
418
448
|
|
|
419
449
|
### Issue: Components not working after optimizing imports
|
|
420
450
|
|
|
421
|
-
**Cause:**
|
|
451
|
+
**Cause:** You did not import a component that you use.
|
|
422
452
|
|
|
423
453
|
**Solution:**
|
|
424
454
|
|
|
@@ -432,7 +462,7 @@ defineComponents(IgcButtonComponent); // Add this
|
|
|
432
462
|
|
|
433
463
|
### Issue: TypeScript errors after changing imports
|
|
434
464
|
|
|
435
|
-
**Solution:** Update type imports:
|
|
465
|
+
**Solution:** Update the type imports:
|
|
436
466
|
|
|
437
467
|
```typescript
|
|
438
468
|
// Import types separately if needed
|
|
@@ -441,15 +471,15 @@ import type { IgcButtonComponent } from 'igniteui-webcomponents';
|
|
|
441
471
|
|
|
442
472
|
## Monitoring Bundle Size
|
|
443
473
|
|
|
444
|
-
|
|
474
|
+
To monitor the bundle size in CI continuously, you can use tools such as [bundlesize](https://www.npmjs.com/package/bundlesize), [size-limit](https://www.npmjs.com/package/size-limit), or the [Bundlewatch GitHub Action](https://github.com/apps/bundlewatch). These tools can fail a pull request if the bundle is larger than a defined limit. After you complete the import optimization, configure a size limit that is applicable to the component set of your project.
|
|
445
475
|
|
|
446
476
|
## Next Steps
|
|
447
477
|
|
|
448
|
-
- Profile your application with Chrome DevTools Performance tab
|
|
449
|
-
-
|
|
450
|
-
-
|
|
478
|
+
- Profile your application with the Chrome DevTools Performance tab
|
|
479
|
+
- Use lazy loading for large components
|
|
480
|
+
- If possible, use a CDN for static assets
|
|
451
481
|
- Enable HTTP/2 for better resource loading
|
|
452
|
-
- Check [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) for
|
|
482
|
+
- Check [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) for the correct setup
|
|
453
483
|
|
|
454
484
|
## Additional Resources
|
|
455
485
|
|