Setting up style blocks
Four steps: install the package, add its plugin to your build, turn on the editor plugin, and check that a block is read. You need a project that builds with Vite or esbuild and type-checks with TypeScript.
Install
npm install @ramonda/cssThe checking is TypeScript's own, so the package needs yours — it writes a virtual file your compiler
reads, and a fault in a block arrives as an ordinary tsc diagnostic rather than as a report from a
tool you have to run separately. TypeScript 5.4 or later, and not 7: TypeScript 7 has no JavaScript
API to read your source with, so the tools stop and say so.
One plugin in the build
The CSS a block compiles to is a module the bundler already knows about, and it follows the JavaScript chunk it belongs to — so there is nothing to import for it, and the same is true of a project's tokens.
import { ramondaCss } from "@ramonda/css/vite";
export const plugins = [ramondaCss()];
esbuild builds the same thing:
import { ramondaCss } from "@ramonda/css/esbuild";
export const plugins = [ramondaCss({ filter: /src\/.*\.tsx?$/ })];
And in the tests. Vitest transforms through its own config, so a file holding a block reaches
it unread unless vitest.config.ts takes the plugin too — beside ramonda(), which lowers the
decorators there as it does in the app.
Set filter on esbuild. esbuild hands a plugin a path rather than the code, so a file has to
be read before it can be asked whether it holds a block. Pointing the plugin at the tree that holds
them means nothing else is opened at all. Name .ts as well as .tsx — \.tsx?$ — so a block in a
file with no markup is compiled too; a file the filter leaves out reaches esbuild unread, and it
stops at the @.
Link the stylesheet esbuild writes. It puts every rule in a .css file beside the bundle —
client.js gets client.css — and nothing loads that file until your HTML links it. Vite does
the linking itself.
A server-rendered app
A server-rendered app from create-ramonda runs Vite in development and
esbuild for the production build, so the plugin goes in two files:
vite.config.ts: addramondaCss()to thepluginsarray besideramonda().scripts/build.mjs: putramondaCss({ filter: /src\/.*\.tsx?$/ })in the emptypluginsarray. Both bundles need it. The server bundle writes the class names into the HTML, and the client bundle carries the rules.
You don't add a <link>. The build writes the page the server sends, and it links the stylesheet
when there is one. In development the rules come with the script, so a page can show unstyled for a
moment before it loads.
A code-split app
Under Vite, a route that is already code-split gets its own stylesheet, without being asked. A
block belongs to the module it was written in and each module imports its own CSS, so splitting is a
decision the bundler was making anyway: a lazily-loaded module gets its own .css asset, carrying
that module's rules and not the entry's, and Vite loads it when the module loads.
esbuild does not split CSS that way. It writes a lazily-loaded module's rules into the entry's
stylesheet as well, so a build there links one sheet holding every rule. Nothing goes missing — every
class a page names is in it — but nothing is held back for later either. One sheet grows with the
number of different declarations, not with the number of components: every display: flex in the
app is one rule.
If you declare tokens
Nothing above changes: the plugin writes a css-system/ folder beside ramonda.css.ts holding the
token groups — $color, $space — and their values, and imports the values' stylesheet beside every
file that holds a block. A page whose blocks read its tokens needs nothing more.
A page that reads a token only from code, and loads no file with a block, imports it once:
import "./css-system/tokens.css";
Commit that folder. It is generated, and it is also what your editor reads, so a fresh clone that
has not built anything yet is still checked. npx ramonda-css codegen writes it without a build,
and --check fails in CI when what is committed no longer matches the config beside it.
Move the type check
tsc cannot read a block — the syntax is not TypeScript — so a project whose build runs
tsc --noEmit stops on the first file that holds one. ramonda-css is the same check with blocks
read, and it reports every type error in the project, inside a block or not, on the line you wrote:
// package.json — a project from `create-ramonda` has this script
"typecheck": "ramonda-css"
Nothing else in the build reads a type. Vite and esbuild strip them and keep going, so without this step a type error ships.
Two things in your editor
They are separate on purpose, and they answer different halves: the plugin decides what is an error, the extension decides what you see while typing.
The compiler, for completion, hover and the red squiggles
A TypeScript language-service plugin, turned on in your own tsconfig.json:
{ "compilerOptions": { "plugins": [{ "name": "@ramonda/css/plugin" }] } }
Your editor has to be running the workspace's TypeScript for any plugin to load. In VS Code: TypeScript: Select TypeScript Version → Use Workspace Version.
What it gives you, drawn from the plugin's own answers over a real project:

The extension, for colours, formatting, and the second TypeScript server
The colours are a TextMate grammar, which is why they are an extension and not part of the plugin: a grammar needs no program and costs nothing. The extension does two more things — it runs your own formatter over a block, and it carries the plugin to the editor's second TypeScript server.
code --install-extension ramonda.css
Or search Ramonda CSS in the Extensions panel.
Update it when you update @ramonda/css. The colours follow the syntax of the version the
extension was made for, so after a new spelling an older extension colours it wrong — the checks
are still your project's own, and still right.
Formatting then depends on what your project already uses, and the two answers are opposite.
Using Prettier? Keep Prettier, and do not touch editor.defaultFormatter. @ramonda/css ships a
Prettier plugin, so your usual formatter handles these files with nothing else to configure:
{ "plugins": ["@ramonda/css/prettier"] }
Using biome? biome has no plugin surface for a syntax it cannot parse, so the formatting goes through this extension, which runs your biome with your config:
{
"[typescriptreact]": { "editor.defaultFormatter": "ramonda.css" },
"editor.formatOnSave": true
}
What that setting does, so you can decide where to put it. editor.defaultFormatter names the
one extension VS Code asks for that language, and it does not fall through to another — so it reaches
every project it is in scope for:
| where the setting is | in a biome project | in a Prettier project | in a project without @ramonda/css |
|---|---|---|---|
the project's .vscode/settings.json | what you want | — | — |
| your user settings | what you want | runs biome, not Prettier | format-on-save does nothing: this extension has no command to run and returns no edits, and Prettier and biome are never asked |
In a workspace it is also what everyone else on the project gets.
TypeScript's own formatter steps aside for a file that holds a block, which is why one of the two above is not optional. The syntax is not TypeScript, and an edit the language service computed for it would land on the wrong characters and corrupt the file rather than merely look wrong — so it is refused for the whole file. In a file with a block, Format Document and Format Selection do nothing by themselves, even on lines nowhere near the block.
Why the extension is not only colours
An editor runs two TypeScript servers — a syntax one for what needs no types, and a semantic one
for everything else. The syntax one owns formatting, code folding, the outline and expand-selection
for as long as the editor is open, and it never opens your tsconfig.json, so a plugin named there
never reaches it.
The extension is what reaches it. It carries the same plugin a second way, which VS Code hands to both servers — so formatting a block leaves it alone, and the outline matches. There is nothing to configure for any of it.
Check that it worked
Write a block with a property that does not exist:
const wrong = <div className={@@( dsiplay: flex; )}>x</div>;
Your editor should underline dsiplay and offer display. If it does, the plugin is loaded and the
workspace TypeScript is the one running. If the whole line is red instead, the syntax server is still
being asked — that is the setting above.
Next
- Writing a block — where a block goes, nesting, and where a value that changes goes instead.
- What is checked — every rule, what it catches, and how to silence one that is wrong.
- The config file —
ramonda.css.tsend to end, and what a project can decide not to allow.