[BREAKING CHANGE][Chore] Drop CJS builds

[weronikaolejniczak]

Summary

Important

This is a BREAKING CHANGE. Until the current version: v117.1.0, CJS is supported and consumers that need it should prioritize migrating to ESM to be able to use latest EUI. For internal Elastic projects, this is done parallel to dropping CJS builds.

Closes https://github.com/elastic/eui-private/issues/553

API Changes

❗ We are dropping the lib and optimize/lib outputs.

Screenshots

N/A

Impact Assessment

Note: Most PRs should be tested in Kibana to help gauge their Impact before merging.

• 🔴 Breaking changes — What will break? How many usages in Kibana/Cloud UI are impacted?
• 💅 Visual changes — May impact style overrides; could require visual testing. Explain and estimate impact.
• 🧪 Test impact — May break functional or snapshot tests (e.g., HTML structure, class names, default values).
• 🔧 Hard to integrate — If changes require substantial updates to Kibana, please stage the changes and link them here.

Impact level: 🟡 Moderate
Kibana PR: elastic/kibana#274696 (CI: 🔴)
Cloud UI PR: https://github.com/elastic/cloud-ui/pull/3746 (CI: 🟢)

Release Readiness

• Documentation:
  • Supported environments
  • Tree-shaking > (Advanced) Deep imports
• Figma: {link to Figma or issue}
• Migration guide: {steps or link, for breaking/visual changes or deprecations} (mentioned briefly in the changelog)
• Adoption plan (new features): {link to issue/doc or outline who will integrate this and where}

QA instructions for reviewer

• Run yarn workspaces @elastic/eui-website build:workspaces && yarn workspaces @elastic/eui-website start - it should succeed (includes all EUI dependencies + Docusaurus)
• EUI CI is green
• Kibana CI is green
• Cloud UI CI is green

Checklist before marking Ready for Review

• Filled out all sections above
• QA: Tested light/dark modes, high contrast, mobile, Chrome/Safari/Edge/Firefox, keyboard-only, screen reader
• QA: Tested in CodeSandbox and Kibana
• QA: Tested docs changes
• Tests: Added/updated Jest, Cypress, and VRT
• Changelog: Added changelog entry
• Breaking changes: Added breaking change label (if applicable)

Reviewer checklist

• Approved Impact Assessment — Acceptable to merge given the consumer impact.
• Approved Release Readiness — Docs, Figma, and migration info are sufficient to ship.

[elastic-vault-github-plugin-prod]

2 visual difference(s) found - expand to review, then click Approve visual changes to update baselines

euipopover (1 difference)

Story	Before	After	Diff
playground desktop

euidatagrid (1 difference)

Story	Before	After	Diff
additional controls options desktop

[elastic-vault-github-plugin-prod]

1 visual difference(s) found - expand to review, then click Approve visual changes to update baselines

euidatagrid (1 difference)

Story	Before	After	Diff
compact desktop

[elastic-vault-github-plugin-prod]

1 visual difference(s) found - expand to review, then click Approve visual changes to update baselines

euidatagrid (1 difference)

Story	Before	After	Diff
additional controls options desktop

[elastic-vault-github-plugin-prod]

2 visual difference(s) found - expand to review, then click Approve visual changes to update baselines

euidatagrid (2 differences)

Story	Before	After	Diff
compact desktop
additional controls options desktop

[Copilot]

Pull request overview

This PR removes EUI’s distributable CommonJS (lib/) build output and updates packaging/docs/consumers to use the ESM (es/) output, while retaining the Jest-only CommonJS test-env/ build for consuming projects’ test environments.

Changes:

• Remove generation and publishing of the lib/ build from the EUI compile script and package metadata, and add an explicit exports map for ESM + test-env.
• Update internal website/docusaurus consumption and docs to reference es/ and test-env/ paths instead of lib/.
• Add a breaking change changelog entry describing the build output change.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
wiki/contributing-to-eui/testing/unit-testing.md	Updates guidance for consuming projects to use test-env/es test utilities.
wiki/consuming-eui/README.md	Updates consumer docs around test utility locations and test-env Jest mapping.
packages/website/src/components/homepage/header/index.tsx	Switches deep import away from lib/ to es/.
packages/website/docs/getting-started/working-with-emotion/migrating-from-sass.mdx	Updates deep import example from lib/ to es/.
packages/website/docs/getting-started/tree-shaking.mdx	Updates build output docs and deep import examples post-CJS removal.
packages/website/docs/getting-started/setup.mdx	Updates setup docs to reflect test-env and ESM usage.
packages/website/docs/components/navigation/buttons/button.mdx	Updates test matcher import paths to test-env.
packages/eui/src/test/README.md	Updates published test util import paths in internal test README.
packages/eui/scripts/compile-eui.js	Removes lib/ + optimize/lib/ compilation/copy targets.
packages/eui/package.json	Switches entrypoints to es/index.js, adds exports, and stops publishing lib/.
packages/eui/changelogs/upcoming/9751.md	Adds breaking change note for dropping the CJS build.
packages/eui-theme-common/package.json	Adjusts entry fields toward ESM-first resolution.
packages/eui-theme-borealis/package.json	Adjusts entry fields toward ESM-first resolution.
packages/docusaurus-theme/src/theme/Navbar/Content/index.tsx	Switches deep import away from lib/ to es/.
packages/docusaurus-theme/src/theme/Footer/index.tsx	Adds explicit .js extension to an ESM deep import.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

This PR contains breaking changes. The opener of this pull request is asked to perform the following due diligence steps below, to assist EUI in our next Kibana upgrade:

• If this PR contains prop/API changes:
  • Search through Kibana for <EuiComponent usages (example search)
  • In the PR description or in a PR comment, include a count or list with the number of component usages in Kibana that will need to be updated (if that amount is "none", include that information as well)
• If this PR contains CSS changes:
  • Search through Kibana for the changed EUI selectors, e.g. .euiComponent (example search)
  • In the PR description or in a PR comment, include a count or list with the number of custom CSS overrides in Kibana that will need to be updated (if that amount is "none", include that information as well)
• 🔍 Tip: When searching through Kibana, consider excluding **/target, **/*.snap, **/*.storyshot files to reduce noise and only look at source code usages
• ⚠️ For extremely risky changes, the EUI team should potentially consider the following precautions:
  • Using a pre-release release candidate to test Kibana CI ahead of time
  • Using kibana-a-la-carte for manual QA, and to give other Kibana teams a staging server to quickly test against

Log | Bot Usage

[infra-vault-gh-plugin-prod]

💚 Build Succeeded

• Buildkite Build
• Commit: 04cb73c

History

• 💚 Build #7156 succeeded c7aa889
• 💚 Build #7149 succeeded 43ab20b
• 💚 Build #6871 succeeded 3f42f19
• 💚 Build #6869 succeeded ba8f765
• 💚 Build #6868 succeeded 6e81b09
• 💚 Build #6866 succeeded 6e81b09

cc @weronikaolejniczak

[infra-vault-gh-plugin-prod]

💚 Build Succeeded

• Buildkite Build
• Commit: 04cb73c
• Documentation website
• Storybook
• ✅ Visual regression tests passed

History

• 💚 Build #4392 succeeded c7aa889
• 💚 Build #4380 succeeded 43ab20b
• 💔 Build #3997 failed 3f42f19
• 💔 Build #3995 failed ba8f765
• 💔 Build #3994 failed 6e81b09
• 💔 Build #3993 failed 38763df

cc @weronikaolejniczak