| name | optimize-bundle-size |
| description | Reduce plugin `page load bundle size` and avoid unnecessary increases in `packages/kbn-optimizer/limits.yml`. Use when proactively optimizing bundles, investigating CI page-load overages, or reviewing PRs that change bundle limits. |
| disable-model-invocation | true |
Optimize Bundle Size
Use this workflow to keep limits stable by moving non-critical code out of the entry bundle.
1) Set a baseline
- Reference
docs/extend/ci-metrics.md for metric definitions and limits workflow details.
- Build dist metrics for the target plugin and record current
page load bundle size.
node scripts/build_kibana_platform_plugins --focus <pluginId> --dist --workers 4
cat <pluginDir>/target/public/metrics.json
- If this is a regression investigation, compare plugin limits on branch vs upstream.
git show upstream/main:packages/kbn-optimizer/limits.yml | rg '^\\s{2}<pluginId>:'
rg '^\\s{2}<pluginId>:' packages/kbn-optimizer/limits.yml
2) Identify entry-chunk drivers
- Generate a profile build.
node scripts/build_kibana_platform_plugins --focus <pluginId> --dist --profile --no-cache --workers 4
- Find the entry chunk id and top modules in that chunk.
entry_id=$(jq -r '.chunks[] | select((.names|index("<pluginId>")) != null) | .id' <pluginDir>/target/public/stats.json)
jq -r --argjson cid "$entry_id" '.modules[] | select((.chunks|index($cid)) != null) | [.size, (.name // .identifier)] | @tsv' <pluginDir>/target/public/stats.json | sort -nr | head -40
- Compare with upstream when the delta is unclear.
jq -r .modules[].id <pluginDir>/target/public/stats.json | sort - > moduleids.txt
- Focus on modules imported by the plugin
public entry/start contract.
3) Apply high-impact fixes
- Replace eager imports in the plugin start contract with lazy boundaries for optional UI.
- Avoid importing broad barrel files (
index.ts) from entry paths; import only required modules directly.
- Split heavy UI into a separate file and load it with
React.lazy(() => import(...)).
- Keep
page load bundle size low; allow async chunks size to grow when code is not needed at initial load.
4) Re-measure and decide limits
- Rebuild dist metrics and compare before/after.
- Keep or restore the old limit if the new value is below it.
- Raise limits only if no meaningful split is possible, then document why.
- If a limit increase is required, use
--update-limits (sets current size +15kb) and include findings in PR notes.
node scripts/build_kibana_platform_plugins --focus <pluginId> --update-limits
5) Validate changes
- Run targeted lint/type checks for touched files.
- Run
node scripts/check_changes.ts.
- Optionally run
--validate-limits or --dist --watch while iterating.
- If
check_changes.ts fails due unrelated pre-existing files, call that out explicitly in PR notes.
node scripts/build_kibana_platform_plugins --validate-limits --focus <pluginId>
node scripts/build_kibana_platform_plugins --dist --watch --focus <pluginId>