CSS Purge

The Lism CSS purge feature scans your build output and keeps only the Lism CSS classes you actually use. Build integrations are provided by the @lism-css/plugin package.

pnpm add -D @lism-css/plugin

Recommended setup (via the integrated plugin)

If you are using the @lism-css/plugin integrated plugin, just pass purge: true to enable it.

import { defineConfig } from 'astro/config';
import { lismCss } from '@lism-css/plugin/astro';

export default defineConfig({
  integrations: [lismCss({ purge: true })],
});

import { defineConfig } from 'vite';
import { lismCss } from '@lism-css/plugin/vite';

export default defineConfig({
  plugins: [lismCss({ purge: true })],
});

You can also pass an object to configure individual purge plugin options:

lismCss({
  purge: {
    report: true, // Log the file size before/after purging to the build log
    safelist: ['-p:30'], // Keep classes not detected by static analysis
  },
});

When known (the set of known Lism classes that purge targets) is not specified, it is automatically built from the config-reflected full.css at the start of the build. This ensures that unused classes derived from props / tokens you added in lism.config.js are correctly purged. If you explicitly provide known, that value is respected.

How it works

At build time, the plugin scans the generated HTML / JS for class names that follow Lism CSS conventions (the c-- / a-- / l-- / is-- / has-- / set-- / u-- prefixes, plus -prop:value style property classes). It then parses the CSS files and keeps only the rules whose selectors reference the collected classes.

• Only targets CSS produced by Lism CSS (detected via a file-header signature)
• Does not touch your own classes or styles from other libraries
• Classes inside :not() / :has() are excluded from the keep test, since they describe negation / descendant conditions
• Attribute selectors such as [class*="-p:"] are matched against used classes and the safelist so nothing is dropped by mistake

Using the standalone plugin directly

You can also register the standalone plugin directly without the integrated plugin.

import { defineConfig } from 'vite';
import { lismPurge } from '@lism-css/plugin/purge/vite';

export default defineConfig({
  plugins: [lismPurge()],
});

import { defineConfig } from 'astro/config';
import { lismPurgeAstro } from '@lism-css/plugin/purge/astro';

export default defineConfig({
  integrations: [lismPurgeAstro()],
});

The Vite plugin runs as apply: 'build' / enforce: 'post', so nothing happens during vite dev. Unused selectors are stripped only when you run vite build. The Astro integration hooks into astro:build:done, scans HTML / JS under dist/, and rewrites the CSS files in place.

Pairing with full.css

lism-css/full.css is an everything-included build that adds breakpoint-aware classes for every Property Class except variable-only (isVar) ones (sm / md / lg), plus SPACE token utilities for spacing properties. It is large when loaded as-is, so it ships as a build meant to be paired with purge.

// Load full.css instead of main.css
import 'lism-css/full.css';

The default set of known classes (known) used by purge is derived from full.css. Since full.css is a superset of the selectors in main.css, unused classes are removed correctly whether you load main.css or full.css.

Once purge is enabled and you switch to full.css, you gain access to token classes and extended breakpoints that main.css does not include, while the final CSS is narrowed down to only the classes actually used across the whole site.

Options

Both plugins accept the same LismPurgeOptions.

safelist

Class names that are assembled dynamically in JS — i.e. names that never appear as a literal string in the build output — cannot be detected by static analysis. Add them to safelist to prevent accidental removal.

lismPurge({
  safelist: [
    // Exact string match
    '-p:30',
    // Regex match
    /^-bgc:/,
    // Custom predicate
    (className) => className.startsWith('-fz:'),
  ],
});

string entries are also used when matching attribute selectors ([class*="..."] etc.). RegExp and function entries cannot enumerate concrete class names, so attribute selectors are kept conservatively.

report

When true, the total byte count before / after purging and the reduction ratio are printed to the build log.

CSS: 28100 → 13200 bytes (-14900 / -53.0%)

Caveats

• When you build class names dynamically, either keep them as a complete literal (`-p:${size}` and similar partial strings are not enough) or add them to safelist.
• Purge keeps the union of classes used across the entire build output (not per page). A class is retained as long as it is used on any page, even if it is unused on a given page. This is intentional so that a single CSS shared across multiple pages is never broken.
• Only CSS emitted by Lism CSS is purged. Your own CSS and styles from other libraries are left untouched.
• The plugin runs independently of other framework purgers such as Tailwind CSS.
• CSS sourcemaps are not supported. Purge removes rules, so an existing sourcemap no longer lines up. To avoid stale mappings, purge strips sourceMappingURL comments from processed CSS and removes old .css.map files. Disable purge if you need CSS sourcemaps.