Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Feature Request]: Shorter scoped class names and class-name maps

Open
  • Is something wrong?
#5,106 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
react, scss, typescript, webpack
Domain
build-system, frontend, performance

Research direction

Start with src/build/tasks/postcss/generate-scoped-name.ts and the writeCssModule implementation; trace how buildStyles generates internal helpers and maps. Review the test-utils selector and snapshot coverage, then measure production bundles and verify class-map lookup behavior. Done means the proposed compact names and generated maps preserve the documented selectors, keys, values, ordering, and compatibility while demonstrating the reported bundle savings.

Written by the indexing model from the issue text.

Description

Description

Scoped CSS class names and the JS maps that reference them are about 10% of the minified JS and a quarter of the raw CSS in a typical multi-component app. Two changes to the CSS-module output of theming-build would cut about 8 KB of brotli JS and 4 KB of brotli CSS from a 39-component console page, with no public API change. The code lives in cloudscape-design/theming-core, which has no issue tracker, so I'm filing here.

Today, src/build/tasks/postcss/generate-scoped-name.ts produces awsui_{name}_{fileHash}_{contentHash}_{line}, and writeCssModule emits each styles.css.js as an object literal that repeats every key inside its value:

export default {
  "variant-normal": "awsui_variant-normal_vjswe_1xyge_131",
  "disabled": "awsui_disabled_vjswe_1xyge_152",
  // ...
};

Proposal:

  1. Replace the line number with a constant: awsui_{name}_{fileHash}_{contentHash}_0. The line adds no uniqueness, since names are unique within a file and both hashes are per file. It isn't a reliable line either: it comes from css.indexOf('.' + name), so in button icon gets the line of icon-left. Because it differs for every class, it is the part of each name brotli can't compress. Keeping a numeric fifth segment means test-utils-core's trimContentHash, which drops the last two segments, still yields the same [class*="awsui_{name}_{fileHash}"] selectors, and snapshot serializers that match _\d+ keep working.

  2. With the line gone, every value is 'awsui_' + key + suffix, so emit the maps as:

import './styles.scoped.css';
import createClassMap from '../internal/generated/css-module-map.js';
export default /*#__PURE__*/ createClassMap('_vjswe_1xyge_0', 'content button variant-normal disabled ...');

The helper is a 3-line loop that buildStyles writes into internal/generated/. The result is an ordinary object with the same keys, values and order, so static, computed and missing-key lookups behave as before. styles.selectors.js (test-utils) stays a literal.

Measured with webpack 5 in production mode against main (209caeca3). The console app uses 39 components including AppLayout, Table and PropertyFilter; the form app uses 10 basic components. Bytes saved by both changes together:

Raw Brotli
Console JS, terser 57 KB 7.8 KB (3.5%)
Console JS, esbuild minify 78 KB 9.4 KB (3.6%)
Console CSS 11.7 KB 3.8 KB (5.5%)
Form JS, terser 25.5 KB 3.2 KB (4.2%)
Form CSS 3.5 KB 1.5 KB (3.9%)

The savings hold on webpack 4, webpack 5 with swc minify, Vite 8, the esbuild bundler and rspack; the class-map change alone saves 6.6 to 9.8 KB brotli on the console page depending on toolchain.

Compatibility, checked with a prototype that rewrote a built lib:

  • Public API: none. Every class name changes once, which already happens whenever a file's CSS changes. Unlike #228, the awsui_ prefix and the awsui_{name}_{fileHash} portion that test-utils and consumer integration tests rely on stay the same.
  • test-utils: selectors-flavor queries passed with new DOM and old test-utils and with old DOM and new test-utils. The test-utils-selectors snapshot is unchanged. The legacy literal in table findExpandToggle targets older versions and still works.
  • Multiple versions on one page: isolation is unchanged because the content hash stays, and each copy carries its own helper.
  • Themed builds: buildThemedComponents regenerates maps with the consumer's theming-build, so the helper must be written by buildStyles/writeCssModule itself. That also covers board, chat and code-view, which pick up the new format on their next build.
  • Runtime: building the maps at module init replaces parsing the literals, and startup CPU was a wash in Node (about 2 ms either way for all 238 maps). Maps built by keyed stores are dictionary-mode in V8; lookups stay in the nanosecond range, but a benchmark before landing is reasonable.
  • Server-side rendering output was byte-identical for the components checked.

Follow-up: trimContentHash finds the stable prefix by counting underscore-separated parts from the end, which is why the _0 placeholder is needed. Parsing from the start would make test-utils independent of everything after the file hash: keep awsui_, the name, and the file hash, matching /^awsui_((?:[^_]|__)+)_([a-z0-9]+)/. This works for today's names, the _0 names, and names with no fifth part. It relies on class keys never containing a single underscore. That holds for all 2,882 keys today, including the 24 BEM-style keys such as error__message, and theming-build could enforce it at build time. A rule keyed on whether the last part is numeric would not work, because 2 of the current 224 content hashes are all digits. Once that version of test-utils-core is out, _0 could be dropped in a release that also raises the components dependency floor on test-utils-core. The reverse direction is already safe: selectors built from older names still match new DOM. That last step saves only raw bytes (about 9 KB CSS and 2 KB JS on the console page, under 0.1 KB brotli), and it would break consumer snapshot serializers that expect a numeric last part, so it is optional.

Not proposed here: short ids instead of readable names would save about 9 KB more brotli on the console page, but they change the stable prefix for classes that consumers target, so they need a separate discussion. Shorter random hashes save raw bytes but not brotli.

Code of Conduct
  • I agree to follow this project's Code of Conduct
  • I checked the current issues for duplicate requests
Dominant language
TypeScript
Stars
2.7k
Forks
248
Avg merge
3d 14h
Merged PRs (30d)
83

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cloudscape-design/components

All issues in cloudscape-design/components

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.