# tailwind-styled-v4
### ⚡ Rust-powered CSS-in-JS untuk React
**Build-time compiler · Zero runtime overhead · Type-safe variants · RSC-ready**
[](https://npmjs.com/package/tailwind-styled-v4)
[](LICENSE)
[](https://rust-lang.org)
[](https://nodejs.org)
[](#)
[](https://bundlephobia.com/package/tailwind-styled-v4)
---
`tailwind-styled-v4` adalah library styling React yang menggabungkan **DX styled-components** dengan **performa Tailwind CSS v4** — dikompilasi oleh engine Rust. Tulis komponen sekali dengan `tw.button({ variants })`, Rust extract dan optimasi seluruh CSS di build time.
**Perbandingan:**
| | tailwind-styled-v4 | styled-components | Tailwind biasa | Panda CSS |
|---|---|---|---|---|
| Build-time CSS | ✅ | ❌ runtime inject | ✅ | ✅ |
| Runtime JS | ~0 | ~15KB | ~0 | ~0 |
| Variants API | ✅ type-safe | terbatas | ❌ | ✅ |
| SSR / RSC | ✅ zero config | ⚠️ ServerStyleSheet | ✅ manual | ✅ |
| Hydration mismatch | ✅ tidak ada | ⚠️ hash drift | ✅ | ✅ |
| DevTools readable | ✅ | ❌ `sc-abc123` | ✅ | ✅ |
| Engine | 🦀 Rust | JS | JS | JS |
| TypeScript | ✅ full inference | partial | ✅ | ✅ |
---
## Instalasi
```bash
npm install tailwind-styled-v4
npx tw setup
```
`npx tw setup` mendeteksi bundler (Next.js / Vite / Rspack), meng-inject plugin ke config, dan membuat `tailwind-styled.config.json` secara otomatis.
---
## API
### 1. Template Literal
API paling sederhana — satu tag, satu string kelas.
```tsx
import { tw } from "tailwind-styled-v4"
const Button = tw.button`
inline-flex items-center rounded-lg px-4 py-2
bg-blue-600 text-white font-medium
hover:bg-blue-700 transition
`
```
---
### 2. Object Config *(direkomendasikan)*
API utama — mendukung `variants`, `states`, `sub`, `compoundVariants`, `container`, dan lebih. Semua di-resolve Rust di build time.
```tsx
const Button = tw.button({
base: "inline-flex items-center rounded-lg font-medium transition-all",
variants: {
intent: {
primary: "bg-indigo-600 text-white hover:bg-indigo-700",
secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300",
danger: "bg-red-600 text-white hover:bg-red-700",
ghost: "text-gray-600 hover:bg-gray-100",
},
size: {
sm: "px-3 py-1.5 text-xs",
md: "px-4 py-2 text-sm",
lg: "px-5 py-2.5 text-base",
},
},
defaultVariants: { intent: "primary", size: "md" },
compoundVariants: [
// intent=primary + size=lg → tambah shadow
{ intent: "primary", size: "lg", class: "shadow-md shadow-indigo-200" },
],
})
// TypeScript tahu props yang valid — autocomplete penuh
// ❌ Type error
```
---
### 3. Sub-Components
Definisi slot anak langsung di config. Format `"tag:name"` untuk kontrol tag HTML — penting untuk SEO dan aksesibilitas.
```tsx
const Card = tw.article({
base: "rounded-2xl border border-gray-200 bg-white shadow-sm overflow-hidden",
sub: {
// "tag:name" → render tag HTML, akses via Card.name
"header:header": "px-6 pt-5 pb-0 flex items-start justify-between",
"h2:title": "text-base font-semibold text-gray-900",
"section:body": "px-6 py-4 text-sm text-gray-500 leading-relaxed",
"footer:footer": "px-6 pb-5 pt-0 flex items-center gap-2",
"img:image": "w-full aspect-video object-cover",
// tanpa tag → render (default)
badge: "rounded-full px-2.5 py-0.5 text-xs font-semibold bg-indigo-100 text-indigo-700",
},
})
// Penggunaan
Judul Card
New
Konten card di sini.
```
Tag prefix di-strip otomatis dari TypeScript inference — `Card.title` bukan `Card["h2:title"]`.
---
### 4. `cv()` — Class Variant Function
Untuk styling non-komponen (className string) — berguna di utility functions, dynamic class lists, dll.
```tsx
import { cv } from "tailwind-styled-v4"
const badge = cv({
base: "inline-flex items-center gap-1.5 rounded-full font-medium",
variants: {
color: {
gray: "bg-gray-100 text-gray-700",
blue: "bg-blue-100 text-blue-700",
green: "bg-green-100 text-green-700",
red: "bg-red-100 text-red-700",
},
size: {
sm: "px-2 py-0.5 text-[10px]",
md: "px-2.5 py-0.5 text-xs",
lg: "px-3 py-1 text-sm",
},
},
defaultVariants: { color: "gray", size: "md" },
})
// Returns string className, bukan komponen
Active
// Merge className tambahan
Error
```
---
### 5. `states` — Boolean Props
Boolean props yang di-resolve via Rust bitmask lookup table. Tidak ada string comparison, tidak ada kondisional di render path.
```tsx
const Button = tw.button({
base: "inline-flex items-center px-4 py-2 rounded-lg font-medium",
variants: {
intent: { primary: "bg-indigo-600 text-white", ghost: "text-gray-600" },
},
defaultVariants: { intent: "primary" },
states: {
loading: "opacity-60 cursor-wait pointer-events-none",
fullWidth: "w-full",
disabled: "opacity-50 cursor-not-allowed",
},
})
// Boolean props langsung — tidak perlu className kondisional
```
Maksimal 16 states per komponen (2¹⁶ kombinasi pre-generated di build time).
---
### 6. `state` — CSS Data-Attribute (Zero JS State)
Untuk toggle style tanpa React re-render — cocok untuk animasi dan transisi.
```tsx
const Dropdown = tw.div({
base: "overflow-hidden transition-all duration-200",
state: {
open: {
true: "max-h-96 opacity-100",
false: "max-h-0 opacity-0",
},
},
})
// Set data attribute langsung — tidak butuh setState
dropdownRef.current?.setAttribute("data-open", "true")
// Atau via React state
{children}
```
---
### 7. `.extend()` — Inheritance
Extend komponen yang sudah ada tanpa duplikasi class.
```tsx
// Template literal extend
const PrimaryButton = Button.extend`
bg-indigo-600 text-white hover:bg-indigo-700
`
// Object config extend — tambah variant sekaligus
const BigDangerButton = Button.extend({
classes: "text-lg px-8 shadow-lg",
variants: { loading: { true: "animate-pulse" } },
defaultVariants: { intent: "danger" },
})
```
---
### 8. `container` — Container Queries
Responsive berdasarkan ukuran container parent, bukan viewport.
```tsx
const Card = tw.div({
base: "p-4 flex flex-col",
container: {
sm: "flex-col", // @container (min-width: 320px)
md: "flex-row", // @container (min-width: 640px)
lg: "grid-cols-3",// @container (min-width: 1024px)
},
containerName: "card", // opsional — named container
})
// Wrapper wajib punya @container
const CardWrapper = tw.div`@container`
{/* responsive berdasarkan lebar CardWrapper */}
```
Breakpoint default: `xs=240px`, `sm=320px`, `md=640px`, `lg=1024px`, `xl=1280px`, `2xl=1536px`.
---
### 9. `server.` — Server Components Only
Komponen yang di-enforce hanya boleh render di server. Dev warning otomatis jika render di browser.
```tsx
import { server } from "tailwind-styled-v4"
// Sama persis API-nya dengan tw — tapi compiler enforce server-only
const PageHeader = server.header({
base: "w-full border-b px-6 py-4 bg-white",
sub: {
"h1:title": "text-2xl font-bold",
"p:subtitle": "text-sm text-gray-500",
},
})
const AvatarRoot = server.div({
base: "relative inline-flex rounded-full overflow-hidden",
variants: {
size: {
sm: "h-8 w-8",
md: "h-10 w-10",
lg: "h-14 w-14",
},
},
defaultVariants: { size: "md" },
})
```
---
### 10. `createStyledSystem()` — Design System Factory
Untuk design system dengan token terpusat. Token di-inject sebagai CSS custom properties `--sys-{group}-{name}`.
```tsx
import { createStyledSystem } from "tailwind-styled-v4"
const ui = createStyledSystem({
tokens: {
colors: {
primary: "#6366f1",
danger: "#ef4444",
muted: "#6b7280",
},
radius: {
base: "0.5rem",
full: "9999px",
},
},
components: {
button: {
tag: "button",
base: "inline-flex items-center font-medium transition-colors",
variants: {
intent: {
primary: "bg-[var(--sys-colors-primary)] text-white",
danger: "bg-[var(--sys-colors-danger)] text-white",
ghost: "bg-transparent text-current hover:bg-black/5",
},
size: {
sm: "h-8 px-3 text-sm",
md: "h-10 px-4 text-base",
lg: "h-12 px-6 text-lg",
},
},
defaultVariants: { intent: "primary", size: "md" },
},
},
})
// Komponen dari sistem
const Button = ui.button()
// Token reference — "var(--sys-colors-primary)"
const primaryVar = ui.token("colors.primary")
// Update token runtime
ui.setTokens({ colors: { primary: "#8b5cf6" } })
```
---
### 11. `liveToken()` — Live Design Tokens
Token yang bisa diupdate runtime dan subscribe ke perubahannya.
```tsx
import { liveToken, tokenVar, createUseTokens } from "tailwind-styled-v4"
// Deklarasi token
const tokens = liveToken({
primary: "#6366f1",
surface: "#ffffff",
text: "#111827",
})
// CSS variable reference — dipakai di className
const Card = tw.div({
base: `
bg-[${tokenVar(tokens.surface)}]
text-[${tokenVar(tokens.text)}]
border-[${tokenVar(tokens.primary)}]
`,
})
// Hook untuk subscribe token di React
const useTokens = createUseTokens(tokens)
function ThemePanel() {
const { primary } = useTokens()
return Current primary: {primary}
}
// Update token langsung — semua subscriber re-render
tokens.primary.set("#8b5cf6")
```
---
### 12. `cn()`, `cx()`, `twMerge`
Utility untuk merge dan deduplicate Tailwind classes.
```tsx
import { cn, cx, twMerge } from "tailwind-styled-v4"
// cn — merge dengan dedup (alias twMerge)
cn("px-4 py-2", isActive && "bg-blue-500", className)
// cx — conditional class join (tanpa dedup)
cx("base-class", { "active-class": isActive, "disabled-class": !enabled })
// twMerge — eksplisit Tailwind conflict resolution
twMerge("px-4 px-8") // → "px-8" (konflik di-resolve, yang terakhir menang)
```
---
## Setup
### Next.js
**`next.config.ts`:**
```ts
import { withTailwindStyled } from "tailwind-styled-v4/next"
import type { NextConfig } from "next"
const nextConfig: NextConfig = {}
export default withTailwindStyled({
// routeCss: true — generate css-manifest.json yang dibutuhkan TwCssInjector.
// Tanpa ini, TwCssInjector diam-diam return kosong (manifest tidak ada).
routeCss: true,
})(nextConfig)
```
**`layout.tsx`:**
```tsx
import { TwCssInjector } from "tailwind-styled-v4/runtime-css"
export default function RootLayout({ children }) {
return (
{/*
* TwCssInjector — opsional tapi direkomendasikan untuk production.
*
* Cara kerja:
* 1. withTailwindStyled({ routeCss: true }) emit css-manifest.json
* ke .next/static/css/tw/ saat build
* 2. Per request, TwCssInjector baca manifest di server dan inject CSS
* route-specific langsung sebagai