Optimize Bundle Size
Developmentoptimize-bundle-sizeOptimize Bundle Size is an Agent Skill for development published in the elastic/kibana repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/elastic/kibana/blob/HEAD/.agents/skills/optimize-bundle-size/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/optimize-bundle-size, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.mdfor 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
# generate moduleids.txt on both branches and diff them
- Focus on modules imported by the plugin
publicentry/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 sizelow; allowasync chunks sizeto 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-limitsor--dist --watchwhile iterating. - If
check_changes.tsfails 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>