mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 03:09:50 +08:00
9c22002f57
Human-facing overview alongside SKILL.md, matching the convention used by platform-soql-query and other single-purpose skills: features, quick start, the before/after numbers from the reference sample, and related-skills links.
69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
# experience-ui-bundle-performance-optimize
|
||
|
||
Frontend performance auditing and optimization skill for Salesforce React UI Bundles. Measures Vite build output against size budgets, then applies route-level code splitting and vendor chunking to cut first-load JavaScript — without touching data layer, routing structure, or visual design.
|
||
|
||
## Features
|
||
|
||
- **Bundle Measurement**: Reads Vite's build report (or runs the bundled analyzer) against explicit size budgets for entry chunks, individual chunks, route chunks, and CSS
|
||
- **Route-Level Code Splitting**: Converts eager page imports in `routes.tsx` to `React.lazy`, so each page ships its own chunk fetched on first navigation
|
||
- **Vendor Chunking**: Configures `manualChunks` in `vite.config.ts` to separate rarely-changing dependencies (React, router, UI primitives, charts) into their own cacheable chunks
|
||
- **Render-Waste Diagnosis**: Guidance for `memo`/`useMemo`/debouncing/virtualization — applied only against a reported symptom, not speculatively
|
||
- **Verification Workflow**: Rebuild, re-measure, and click through every navigation entry to confirm lazy chunks load correctly
|
||
|
||
## Quick Start
|
||
|
||
### 1. Invoke the skill
|
||
|
||
```
|
||
Skill: experience-ui-bundle-performance-optimize
|
||
Request: "This UI bundle's build is throwing a chunk-size warning, can you fix it?"
|
||
```
|
||
|
||
The skill also self-activates when a build prints Vite's `"Some chunks are larger than 500 kB"` warning, or when the user mentions slow load, bundle size, code splitting, or Core Web Vitals for a project under `uiBundles/*/src/`.
|
||
|
||
### 2. Run the analyzer directly
|
||
|
||
```bash
|
||
node skills/experience-ui-bundle-performance-optimize/scripts/analyze-bundle.mjs <app-dir>/dist
|
||
```
|
||
|
||
Add `--json` for machine-readable output. Exits `0` when every budget passes, `1` when any budget is exceeded (suitable for CI gating), `2` on usage/IO errors.
|
||
|
||
### 3. Typical use cases
|
||
|
||
- Diagnose why a UI bundle's `npm run build` prints a chunk-size warning
|
||
- Reduce first-load JavaScript before deploying a UI bundle to an org
|
||
- Add code splitting to a UI bundle app that has grown past its initial page set
|
||
- Investigate reported UI sluggishness (typing lag, slow list scroll, tab-switch delay)
|
||
|
||
## Results on the Reference Sample
|
||
|
||
Applied to `samples/ui-bundle-template-app-react-sample-b2e` (Property Management app):
|
||
|
||
| | Before | After |
|
||
|---|---|---|
|
||
| Entry chunk | 1,104.74 kB (326.44 kB gzip) | 50.21 kB (16.28 kB gzip) |
|
||
| Route chunks | none — all pages eager | 4 chunks, 9–16 kB each, loaded on navigation |
|
||
| Vendor chunks | none | `react`, `router`, `radix`, `charts` — cacheable across deploys |
|
||
| Vite size warning | yes | no |
|
||
|
||
Verified at runtime: the home route renders correctly, and navigating to each page fetches exactly that page's lazy chunk (confirmed via network trace), nothing more.
|
||
|
||
## Documentation
|
||
|
||
- [SKILL.md](SKILL.md) — full workflow: measure → split routes → split vendors → fix render waste → verify, with size budgets and template-specific rules
|
||
- [scripts/analyze-bundle.mjs](scripts/analyze-bundle.mjs) — standalone budget checker for `dist/` output
|
||
|
||
## Boundaries
|
||
|
||
- Does not touch the GraphQL data layer, router library, or component library — that is a rewrite, not an optimization
|
||
- Does not enable production sourcemaps to "measure" — uses the build report or the analyzer instead
|
||
- Does not change `outDir`, `assetsDir`, or `base` in `vite.config.ts` — those are relied on by deployment
|
||
|
||
## Related Skills
|
||
|
||
- `experience-ui-bundle-frontend-generate` — for visual/styling changes to an existing UI bundle app
|
||
- `experience-ui-bundle-app-coordinate` — for building a new UI bundle app from scratch
|
||
- `experience-ui-bundle-deploy` — for deploying the optimized bundle to a Salesforce org
|
||
- `experience-ui-bundle-salesforce-data-access` — for GraphQL/data-layer concerns (org latency, query shape) that this skill does not address
|