Installation
traceless-style is published to npm. It has no required dependencies at runtime and one optional dependency (@swc/core) that the SWC-backed extractor uses for large codebases.
1. Install the package
npm install traceless-style
# or
pnpm add traceless-style
# or
yarn add traceless-style
The package ships pre-built. There is no postinstall step.
| Peer dependency | Required? | What for |
|---|---|---|
| react ≥ 18 | Optional | Only needed for the React components in traceless-style/dark and traceless-style/rtl (<TracelessRoot />, <ThemeToggle />, <RtlToggle />). |
| next ≥ 14 | Optional | Only needed if you use traceless-style/nextjs. |
| webpack ≥ 5 | Optional | Only needed if you wire up the raw webpack plugin. |
| vite | Optional | Only needed for traceless-style/vite. |
| @swc/core | Optional | Auto-loaded for projects ≥ 100 source files. Falls back to the legacy parser if installation failed. |
2. Pick an integration
| You're using… | Install one of |
|---|---|
| Next.js (App Router or Pages) | traceless-style/nextjs |
| Webpack directly (CRA-style or Rspack) | traceless-style/webpack |
| Vite | traceless-style/vite |
| Rollup | traceless-style/rollup |
| esbuild | traceless-style/esbuild |
| Just Node + a build script | The CLI: npx traceless-style
|
Each integration page contains a copy-paste config snippet.
3. Run init (recommended)
npx traceless-style init
This zero-config scaffolder:
- Detects your framework (Next, Vite, Remix, Astro).
- Adds the bundler plugin to your config file.
- Adds
<TracelessRoot />to your root layout (anti-flash dark + RTL script). - Creates
traceless-style.config.jsif missing. - Adds
dev/buildscripts topackage.jsonif missing. - Suggests installing the VS Code extension via
.vscode/extensions.json.
The scaffolder is idempotent — re-running it will not duplicate edits.
4. Verify the install
Create a tiny component:
// app/test-install.tsx
import { tl } from "traceless-style";
const $ = tl.create({
hello: { color: "tomato", padding: "1rem", fontSize: "1.25rem" },
});
export default function Test() {
return <div className={$.hello}>traceless-style is working!</div>;
}
Run your dev server (npm run dev for Next, vite for Vite, etc.) and visit the page. The first request triggers a full extraction; subsequent saves trigger incremental rebuilds (≤ 50 ms typical).
You should see public/traceless-style.css appear with three rules.
5. Add the anti-flash script (only if you use dark mode or RTL)
In your root layout (app/layout.tsx for Next App Router):
import { TracelessRoot } from "traceless-style/dark";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<TracelessRoot />
<link rel="stylesheet" href="/traceless-style.css" />
</head>
<body>{children}</body>
</html>
);
}
The Next.js integration (withTracelessStyle) will inject the stylesheet automatically — you do not need the <link> tag if you used the integration. For non-Next users, add the <link> tag pointing at /traceless-style.css (or wherever your outCSS config writes to).
6. Choose strict-by-default lint behavior
Lint is on by default. Inline styles (style={{...}}) and bare class strings (className="px-4") are rejected at extraction time — see Linting. To opt out of an individual rule, add traceless-style.config.js:
module.exports = {
lint: { noTailwind: false }, // keep the others; allow Tailwind
};
lint: false disables the three opt-in rules but leaves noInlineStyles on (inline styles bypass the compiler entirely and there is no legitimate reason for them in a traceless-style project).
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Cannot find module 'traceless-style/nextjs' |
Forgot to install next or used wrong import path |
npm install next and re-import |
Styles appear but tl.merge() doesn't deduplicate |
Webpack DefinePlugin didn't inject __TRACELESS_STYLE_META__
|
Make sure you used withTracelessStyle() and not just TracelessStyleWebpackPlugin directly |
| Build is slow on huge codebases | Default parser is text-mode (legacy) | Set TRACELESS_STYLE_PARSER=swc or run with --parser=swc
|
@swc/core fails to install on Alpine/musl |
Native dep | Pin @swc/core to a known-good version, or stay on the legacy parser |
| FOUC / flash of light theme | Forgot <TracelessRoot />
|
Add it to <head> of your root layout |
Continue to 3. Thinking in atomic CSS for the conceptual model, or jump to 4. Defining styles with tl.create.
SOCIAL SHARE CARD GENERATOR