OpenParable
Skip to content
← Back to skills

Optimize Bundle Size

Development
optimize-bundle-size

Optimize 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. 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

  1. Reference docs/extend/ci-metrics.md for metric definitions and limits workflow details.
  2. 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
  1. 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

  1. Generate a profile build.
node scripts/build_kibana_platform_plugins --focus <pluginId> --dist --profile --no-cache --workers 4
  1. 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
  1. 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
  1. Focus on modules imported by the plugin public entry/start contract.

3) Apply high-impact fixes

  1. Replace eager imports in the plugin start contract with lazy boundaries for optional UI.
  2. Avoid importing broad barrel files (index.ts) from entry paths; import only required modules directly.
  3. Split heavy UI into a separate file and load it with React.lazy(() => import(...)).
  4. 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

  1. Rebuild dist metrics and compare before/after.
  2. Keep or restore the old limit if the new value is below it.
  3. Raise limits only if no meaningful split is possible, then document why.
  4. 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

  1. Run targeted lint/type checks for touched files.
  2. Run node scripts/check_changes.ts.
  3. Optionally run --validate-limits or --dist --watch while iterating.
  4. 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>