Summary

• Updates icon_map.ts to use dynamic imports instead of string values. 84b73d1
• Use the updated icon_map.ts loaders directly in packages/eui/src/components/icon/icon.tsx. 84b73d1
• Removed icon preloading in Storybook. a1bc973
• Removed icon workaround section from wiki. e51ae23
• Updated website supported environments section. 48b2168

Why are we making this change?

Resolves #5463
Resolves #5305
Relates to #8860

The gist of EUI icon approach

We hold all SVG files in: packages/eui/src/components/icon/svgs. We use svgr in packages/eui/scripts/compile-icons.js (that's executed in our building pipeline) to transform the SVG files into React components. We add .tsx files into packages/eui/src/components/icon/assets folder and in packages/eui/src/components/icon/icon_map.ts we reference the paths. Later, in EuiIcon source: packages/eui/src/components/icon/icon.tsx we reference this map:

and access the assets/ folder paths using iconType passed to the EuiIcon component, importing the path dynamically and rendering the React components.

Problem context

For a long time, the way icons were loaded was by using one dynamic import with path string concatenation, as you can see above, and letting Webpack know to chunk it with magic comments. This is convenient because we can load them all with one import. Likely because Kibana uses Webpack and EUI was predominantly written for Kibana use.

The biggest downside to this approach is the vendor lock-in. As soon as modern bundlers started becoming standard, now tools like Vite, NextJS successfully burying CRA and Webpack-based tooling, this became an issue. In parallel, bundlers like Parcel started supporting dynamic imports. Modern bundlers need to see explicit dynamic imports to be able to load the modules.

Solution

The solution is very simple. Instead of writing path strings in icon_map.ts:

export const typeToPathMap = {
  accessibility: 'accessibility',
  // ...
}

we use dynamic imports:

export const typeToPathMap = {
  accessibility: () => import('./assets/accessibility'),
  // ...
}

that should allow all bundlers to statically see all needed modules, and chunk them accordingly.

Advantages

The bonus to this approach as opposed to appendIconComponentCache is:

1. The icons just work no matter the bundler, no additional code needed on consumer side to make them work. This alleviates the preloaded icon list maintenance burden from consumers.
2. The icons are loaded dynamically in runtime as they show up and not preloaded all at once. This improves the initial page loads. As icons appear, they are added to the cache and resolved from cache.

Disadvantages

The only downside of on-demand loading is a tiny delay when an icon appears but we have an in-built loading state (fade in) to prevent layout shifts. Once the icon is loaded, it is cached for the rest of the session.

Performance audits

Storybook (Webpack but no preloading)

Measured on the EuiButton Playground story.

Kibana (Webpack)

Followed Testing in Kibana wiki. Resolved @elastic/eui to package.tgz generated by running build-pack on this branch. Tested before and after.

CLS was repeatedly lower by ~0.076 but it's fluctuating. Speed Index was reported 1s lower but I'm not confident it's saying much considering Kibana's size. What would warrant any worry would be the decrease in JS Requests (i.e. icons are possibly incorrectly chunked).

The bottom line is, there's no regression for the main consumer.

Icons are chunked correctly. Since we removed the magic comments, the names are just hashes.

AutoOps (Vite/Rollup)

Followed AutoOps README.md. Resolved @elastic/eui to package.tgz generated by running build-pack on this branch. Tested before and after.

This effectively demonstrates the dynamically loaded icons (as opposed to preloaded ones).

Additional details

#5463 (comment)

We had a brief sync about this today, and we'd be open to changing the import method.
One difficulty I see with the referenced path is that we have 4 different builds (es, lib, optimize/es, and optimize/lib) and the import path would need to change for each:

accessibility: () => import('@elastic/eui/es/components/icon/assets/accessibility')

Right now each build, as well as local dev (with webpack dev server), work because of the relative './assets/' pathing in the concatenated string. We'd need to alter the import at build time to accommodate each build but keep local imports working for dev environments.

This is simply not the case. The relative path dynamic imports work identically to the current string concatenation "./assets/" + type. When the project is built, no matter the target (es, lib, optimize/es, optimize/lib), the build preserves the directory structure. So the source icon_map.js is right next to assets/ folder. Because they move together to the destination folder, the relative path remains valid for all 4 build targets and local dev.

Missing extensions

All modern bundlers are capable of resolving the extension. There is no need to provide them directly in our source code. If we did that, it would have to be .js and that would lead to references not being resolved on our side and TypeScript overrides / muting comments.

Impact to users

🟢 Webpack-based projects keep resolving and chunking the icons as needed. Projects using modern bundlers like Rollup, Parcel don't require appendIconComponentCache usage and all icons are loaded runtime as used, not all preloaded.

QA

Specific checklist

• Verify that Kibana CI is passing ([Test] EuiIcon rewrite kibana#251263)
• Verify VRTs pass
• Verify that icons can be used without appendIconComponentCache in a boilerplate Parcel project
  • yarn workspace @elastic/eui build-pack
  • npm create parcel react-client test-eui-parcel (see docs)
• Verify that icons can be used without appendIconComponentCache in a boilerplate Vite project (Rollup)
  • yarn workspace @elastic/eui build-pack
  • npm create vite@latest test-eui-vite -- --template react-ts (see docs)
• Verify that icons can be used without appendIconComponentCache in AutoOps project (thanks @dfvalero 🙌🏻)
• Icons render as expected in Storybook staging and locally
• Icons render as expected in the documentation website staging and locally
• Run performance tests on Storybook
• Run performance tests on AutoOps
• Run performance tests on Kibana

I went through these myself, feel free to double-check.

General checklist

• Browser QA
  • Checked in both light and dark modes
  • Checked in both MacOS and Windows high contrast modes
    • (emulate forced colors if you do not have access to a Windows machine.)
  • Checked in mobile
  • Checked in Chrome, Safari, Edge, and Firefox
  • Checked for accessibility including keyboard-only and screenreader modes
• Docs site QA
  • Added documentation
  • Props have proper autodocs (using @default if default values are missing) and playground toggles
  • Checked Code Sandbox works for any docs examples
• Code quality checklist
  • Added or updated jest and cypress tests
  • Updated visual regression tests
• Release checklist
  • A changelog entry exists and is marked appropriately
  • If applicable, added the breaking change issue label (and filled out the breaking change checklist)
  • If the changes unblock an issue in a different repo, smoke tested carefully (see Testing EUI features in Kibana ahead of time)
• Designer checklist
  • If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)