🍩 Coulis

Atomic CSS-in-JS library with a tiny runtime

## 🤔 Motivation With the emergence of design systems, style reusability is key. Atomic CSS is a CSS approach that considers each class name as a single CSS rule: the more the same rule is used across different components, the more the atomic rule is reused and the more the CSS filesize is reduced in contrast to other non-atomic approaches. You can find a great talk about this approach [here](https://www.youtube.com/watch?v=tFFn39lLO-U). In parallel, CSS-in-JS libraries enable (but not only) huge developer experience improvements by integrating transparently into the JavaScript ecosystem and letting a developer share/consume CSS-in-JS dependencies without extra specific CSS bundle steps. Coulis leverages these two approaches to create a great developer experience while maximizing the reusability of your styles.
## 🚀 Quickstart 1️⃣ Install ```bash # Npm npm install coulis # Pnpm pnpm add coulis # Yarn yarn add coulis ``` 2️⃣ Play ✌️ ```tsx import { createCoulis } from "coulis"; const { createKeyframes, createStyles, setGlobalStyles } = createCoulis({ properties(theme) { return { alignItems: true, animation: true, backgroundColor: theme.colors, boxSizing: true, color: theme.colors, display: ["flex"], fontFamily: true, fontSize: true, height: theme.sizes, justifyContent: true, margin: theme.spacings, marginLeft: theme.spacings, marginRight: theme.spacings, padding: theme.spacings, paddingLeft: theme.spacings, paddingRight: theme.spacings, transitionProperty(input: ("background-color" | "color")[]) { return input.join(","); }, width: theme.sizes, }; }, shorthands: { marginHorizontal: ["marginLeft", "marginRight"], paddingHorizontal: ["paddingLeft", "paddingRight"], }, states: { hover: "coulis[selector]:hover{coulis[declaration]}", }, theme: { colors: { neutralDark: "black", neutralLight: "white", neutralTransparent: "transparent", }, sizes: { full: "100%", }, spacings: { none: 0, small: 4, medium: 8, large: 12, }, }, }); setGlobalStyles({ "*,*::before,*::after": { boxSizing: "inherit", }, "@import": "url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap')", "html": { boxSizing: "border-box", }, "html,body": { fontFamily: "Open Sans", margin: "none", padding: "none", }, }); const colorAnimation = createKeyframes({ from: { backgroundColor: "neutralLight", }, to: { backgroundColor: "neutralDark", }, }); export const App = () => { return (

Hello 🤗

); }; ```
## 👨‍🍳 Patterns ### How to implement server-side rendering? Coulis provides a dedicated method called `getMetadata` that allows collecting style instructions for injecting into the `` section of the web page. Its primary use case is server-side rendering. The getter helps prevent the FOUC (Flash Of Unstyled Content) issue, where the user briefly sees the unstyled content before the styles are applied on the browser side. Here's a vanilla React integration example generating HTML content: ```tsx import { renderToString } from "react-dom/server"; import { coulis } from "./helpers/coulis"; // Factory instance created via `createCoulis` (see quickstart guide) import { App } from "./App"; // Main component entry point (depending on your project specificities). export const renderHtml = () => { const bodyContent = renderToString(); const headContent = String(getMetadata()); // Must be get after the `renderToString` traversal to retrieve generated styles. return ` ${headContent}

`) | | `createKeyframes` | Injects `@keyframes` rule, returns class name | ⚠️ Not supported — logs a warning and returns `{}` | | `setGlobalStyles` | Injects global CSS rules | ⚠️ Not supported — logs a warning and does nothing | | `getMetadata` | Returns injected style sheets (for SSR) | ⚠️ Not supported — logs a warning and returns `[]` | Theme values are passed as-is (raw values, not CSS custom properties).
## 🔭 Examples Working integrations are available in the [`examples/`](../examples/) directory: | Example | Description | | ------------------------------------------------------- | ----------------------------------- | | [vite-csr-react](../examples/vite-csr-react/) | Vite + React, client-side rendering | | [vite-ssr-react](../examples/vite-ssr-react/) | Vite + React, server-side rendering | | [nextjs-app-router](../examples/nextjs-app-router/) | Next.js with the App Router | | [nextjs-pages-router](../examples/nextjs-pages-router/) | Next.js with the Pages Router | | [expo](../examples/expo/) | React Native via Expo |