coulis

v0.22.0

Published

25 days ago

Yet another atomic CSS-in-JS library

0High
0Medium
0Low

adbayb

atomic css css-in-js js

🤔 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.

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

# Npm
npm install coulis
# Pnpm
pnpm add coulis
# Yarn
yarn add coulis

2️⃣ Play ✌️

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 (
		<main
			className={createStyles({
				alignItems: "center",
				animation: `${colorAnimation} 2000ms linear infinite`,
				display: "flex",
				height: "full",
				justifyContent: "center",
				width: "full",
			})}
		>
			<p
				className={createStyles({
					color: {
						base: "neutralDark",
						hover: "neutralLight",
					},
					fontSize: 26,
					marginHorizontal: "medium",
					paddingHorizontal: "large",
					transitionProperty: ["background-color", "color"],
				})}
			>
				Hello 🤗
			</p>
		</main>
	);
};

👨‍🍳 Patterns

How to implement server-side rendering?

Coulis provides a dedicated method called getMetadata that allows collecting style instructions for injecting into the <head /> 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:

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(<App />);
	const headContent = String(getMetadata()); // Must be get after the `renderToString` traversal to retrieve generated styles.

	return `<html>
		<head>
			${headContent}
		</head>
		<body>
			<div id="root>${bodyContent}</div>
		</body>
	</html>`;
};

For more server-side integration recipes, the following examples can be checked:

React
- Next.js with the app router, more specifically, this snippet.
- Next.js with the pages router, more specifically, this snippet.
- Vite.js with server-side rendering, more specifically, this snippet.
Angular
- Welcome to any contribution.
Vue
- Welcome to any contribution.
...
- Welcome to any contribution.

How to use Coulis with React Native?

Import from the dedicated entry point:

import { createCoulis } from "coulis/react-native";

The API is identical to the web adapter with the following differences:

| Method | Web | React Native | | ----------------- | --------------------------------------------- | -------------------------------------------------- | | createStyles | Returns a CSS class name string | Returns a style object (Record<string, unknown>) | | 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/ directory:

| Example | Description | | ------------------------------------------------------- | ----------------------------------- | | vite-csr-react | Vite + React, client-side rendering | | vite-ssr-react | Vite + React, server-side rendering | | nextjs-app-router | Next.js with the App Router | | nextjs-pages-router | Next.js with the Pages Router | | expo | React Native via Expo |

Published

Vulnerabilities

Links

Maintainers

Keywords