Ship less Carbon: up to 70% less CSS and a quarter less JS
carbon-preprocess-svelte v0.11.50
Carbon's stylesheet is about 700 KB, and every Carbon component ships
every variant it supports, whether your app uses them or not. The
next release of carbon-preprocess-svelte reads how your app actually
uses Carbon and drops the rest, from your CSS and from your
JavaScript.
The headline numbers
- Up to 70% less CSS than plain pruning, by reading the props you
pass (propAware): 56–70% across four realistic apps. - 18–27% less JavaScript, by rewriting each Carbon component, and
now your own wrapper components, for the props your app passes
(optimizeComponents). - About 10% less CSS with no configuration change, from smarter
default pruning. - Builds up to 89% faster in the prop analysis, and 48% faster for
a coldoptimizeComponentsrun.
A DataTable app goes from Carbon's 707 KB stylesheet to 30 KB of
CSS: 95.7% removed.
What changed since the last release
Measured against v0.11.49, the first release with propAware and
optimizeComponents, on real production builds:
| What you use | CSS | JS | Build time |
|---|---|---|---|
optimizeCss(), default
| 2–17% smaller (~10% typical) | same | |
optimizeCss({ propAware: true })
| 19–32% smaller | analysis 41–89% faster | |
optimizeComponents()
| 2–8% smaller, on top of what it already removed | cold build 48% faster | |
optimizeImports()
| same | same | same |
And in absolute terms, for four realistic apps (an admin dashboard, a
signup wizard, a docs site and a product catalog):
| App | CSS, no plugin | optimizeCss()
| + propAware
| JS, no plugin | optimizeComponents()
|
|---|---|---|---|---|---|
| Admin dashboard | 679 KB | 261 KB (-62%) | 114 KB (-83%) | 219 KB | 162 KB (-26%) |
| Signup wizard | 679 KB | 210 KB (-69%) | 62 KB (-91%) | 176 KB | 129 KB (-27%) |
| Docs site | 679 KB | 151 KB (-78%) | 67 KB (-90%) | 143 KB | 117 KB (-18%) |
| Product catalog | 679 KB | 250 KB (-63%) | 86 KB (-87%) | 216 KB | 168 KB (-22%) |
CSS percentages are against the full stylesheet. propAware removes
another 56–70% on top of plain optimizeCss().
How it works
optimizeCss already removes the styles of Carbon components you
don't import. propAware goes further and reads the props you pass:
<Button kind="tertiary">Save</Button>
<!-- kept: .bx--btn, .bx--btn--tertiary
pruned: every other kind and size, .bx--skeleton,
the icon-only tooltip -->It follows props through your code the way you write it: constants,
state nothing reassigns, constants exported from your own modules,
your own wrapper components (<ActionButton primary> reaching
<Button kind={primary ? "tertiary" : "ghost"}>), object and array
literals, {#if} branches that can't render, and the props Carbon
passes to its own children. Anything it can't read keeps every
variant, so it errs toward keeping styles, never toward breaking them.
optimizeComponents applies the same analysis to JavaScript. Each
Carbon component your app renders is rewritten for the props it
actually receives: values that never change become literals, branches
that can't run are removed, and so are the child components only those
branches rendered (skeletons, tooltip portals). New in this release,
your own wrappers are rewritten the same way when every place that
renders them is in content.
Get started
npm install -D carbon-preprocess-svelteVite:
// vite.config.js
import { svelte } from "@sveltejs/vite-plugin-svelte";
import {
optimizeComponents,
optimizeCss,
optimizeImports,
} from "carbon-preprocess-svelte";
export default {
plugins: [
optimizeComponents(), // before svelte(): it hands Svelte the rewritten source
svelte({ preprocess: [optimizeImports()] }),
optimizeCss({ propAware: true }),
],
};SvelteKit 3:
// vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import {
optimizeComponents,
optimizeCss,
optimizeImports,
} from "carbon-preprocess-svelte";
export default {
plugins: [
optimizeComponents(),
sveltekit({ preprocess: [vitePreprocess(), optimizeImports()] }),
optimizeCss({ propAware: true }),
],
};webpack and Rspack:
// webpack.config.mjs (or rspack.config.mjs)
import {
OptimizeComponentsPlugin,
OptimizeCssPlugin,
} from "carbon-preprocess-svelte";
export default {
plugins: [
new OptimizeComponentsPlugin(),
new OptimizeCssPlugin({ propAware: true }),
],
};Rollup, Rolldown and Astro work too; see the README for each.
Both run on production builds only, never the dev server. Want to see
what they did? Pass report: true:
Button (4 call sites)
kind "danger", "ghost", "primary", "tertiary" (+ default)
DataTable (1 call site)
page dynamic: App.svelte:231 `page` is bound with `bind:` at line 253
Every value it couldn't read comes with the reason and the line, so you
know exactly what to change if you want more pruned.
Built to be safe
Rewriting a component library for one app only works if nothing else
renders it differently, so optimizeComponents checks:
- It fails the build instead of shipping wrong code when a module
outsidecontentrenders Carbon or one of your rewritten wrappers,
including through re-exports, dynamicimport()and virtual
modules. The message names the file and tells you what to add. - Every change is checked against real renders. On each change,
CI renders 2,400+ apps covering every Carbon component and prop
value and requires identical HTML before and after rewriting, on
Svelte 3, 4 and 5, and checks that no class an app renders loses its
rules. - And against real clicks. Every example and four realistic apps
are driven through the same script of clicks, typing, menus and
modals in Chromium, optimized and not, and must produce the same DOM
and the same pixels at every step.
Upgrade notes
- No configuration changes needed. Existing setups get the default
pruning gains automatically. propAwareandoptimizeComponentsare opt-in. If an analysis
fails, the build warns and falls back to plain pruning.- Wrappers imported through an alias (
#lib/Card.svelte,
$lib/Card.svelte) are now resolved with your bundler's own resolver. optimizeComponentsreads every file incontent(by default all of
src/). If a module outside it renders Carbon, the build tells you
which one to add.
Changelog
Features
optimizeComponents: rewrite the app's own wrapper componentsoptimizeComponents: resolve aliased wrappers with the bundler- analyzer: follow the app's own branches and module constants
- analyzer: read object/array literals, spreads, calls,
typeof, and$$restProps - analyzer: read destructured constants and
readablestores - analyzer: keep a name known when a nested scope reuses it
- analyzer: prune the classes no rendered component can apply
- analyzer: say why a prop value is unknown in the report
Fixes
optimizeCss: credit a CSS-only class to its family's componentoptimizeCss: keep other components' classes out of the indexoptimizeCss: keep a component's own classes out of BEM matchingoptimizeCss: judge a merged:is()selector by its branchesoptimizeComponents: catch re-exports and dynamic imports of CarbonoptimizeComponents: lex virtual modules before failing the build
Performance
index: ~1.3× faster component index with sveast 0.9.3- analyzer: stop repeating work on every analysis pass
- analyzer: read an app module's constants only when imported
- analyzer: clean up each rewrite from one parse