🍣 surimi

Getting Started

Welcome to Surimi! This is a quick guide to get you started. If you want to dive right into code, check out the Playground. If you’re just curious how it works under the hood, see How it works.

Surimi is a TS-in-CSS library to write type-safe, zero-runtime CSS. It is a modern alternative to CSS preprocessors and CSS-in-JS libraries like Vanilla Extract. They can be nice, but Surimi takes another, CSS-first approach. We embrace CSS for what it is and put a modern, functional API on top - with as much support as you could possibly need.

At the end of the day, Surimi is a way to write CSS in typescript. If you know these two things, you know Surimi.

NOTE

Surimi is still in early development. The API might change, and some features are not yet implemented. If you have feedback or issues, open an issue on GitHub

Installation

Install Surimi with your package manager of choice:

npm install -D surimi
# or
yarn add -D surimi
# or
pnpm add -D surimi

If you use any vite based tool like Astro, Vue, Nuxt or use Vite with React etc. you should install our vite plugin. For more options, have a look at our Guides Overview. Vite is NOT required for Surimi, but it’s the easiest way to get started. More on that in a bit.

Adding the Vite plugin

The Vite plugin ships with surimi itself, so there’s nothing extra to install. Just import it from surimi/vite and add it to your vite.config.ts:

import { defineConfig } from 'vite';
import surimi from 'surimi/vite';

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

Note that surimi is installed as a dev dependency, as it has zero runtime.

For more details on the vite plugin see Using Surimi with Vite.

If you’re not using vite, you can still use Surimi! Using it with rollup/rolldown is easy, but you can also use the compiler manually. Check out the Compiler page for more details.

Usage

Create a .css.ts file somewhere in your project, e.g. src/styles.css.ts:

import { select } from 'surimi';

select('body').style({
  margin: 0,
  backgroundColor: 'coral',
});

And import that file somewhere in your app, e.g. in src/main.ts or src/App.tsx:

import './styles.css';

NOTE

Note, that we left out the .ts extension from the import. This is because by default, vite and typescript are setup to resolve the extension automatically. Depending on your setup, you might need to include it.

🎉 And that’s it! The Surimi file will be automatically compiled (with HMR support), and exports from the file will be preserved (With some exceptions).

What surimi offers now:

  • Type-safe, autocompleted CSS properties and values
  • Hints when hovering over properties, selectors and values
    • It will even tell you what you’re targetting, like
    SelectorBuilder<"body > #container .button:hover">
  • A query-builder API to build complex selectors
  • Support for media queries, pseudo selectors, nesting and more
  • Zero runtime, all CSS is compiled away
  • Full integration with your build tool via the vite plugin