next-style 2.2.2 → 2.2.3

package/README.md

@@ -7,6 +7,8 @@
 Write styles in TypeScript. Ship pure CSS. Zero overhead.
 
 [![npm version](https://img.shields.io/npm/v/next-style?color=7F77DD&labelColor=000)](https://www.npmjs.com/package/next-style)
+[![npm downloads](https://img.shields.io/npm/dm/next-style?color=7F77DD&labelColor=000)](https://www.npmjs.com/package/next-style)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-7F77DD?labelColor=000)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-7F77DD?labelColor=000)](https://opensource.org/licenses/MIT)
 [![Turbopack](https://img.shields.io/badge/Turbopack-ready-7F77DD?labelColor=000)](https://turbo.build/pack)
 
@@ -14,8 +16,102 @@ Write styles in TypeScript. Ship pure CSS. Zero overhead.
 
 ---
 
+## Overview
+
 **next-style** extracts all styles at build time through a PostCSS plugin — no style injection, no hydration cost, no runtime. The compiled CSS lands in your `globals.css` exactly once.
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Installation](#installation)
+- [Setup](#setup)
+- [API](#api)
+- [Responsive Design](#responsive-design)
+- [TypeScript](#typescript)
+- [Advanced](#advanced)
+- [Performance](#performance)
+- [Best Practices](#best-practices--common-patterns)
+- [Troubleshooting](#troubleshooting)
+- [Browser Support](#browser-support)
+- [How It Works](#how-it-works)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick Start
+
+1. **Install the package:**
+```bash
+npm install next-style
+```
+
+2. **Configure PostCSS** (`postcss.config.js`):
+```js
+export default {
+  plugins: {
+    "next-style/plugin": {},
+  },
+}
+```
+
+3. **Import in `globals.css`:**
+```css
+@import "next-style";
+```
+
+4. **Use in your components:**
+```tsx
+import { css } from "next-style"
+
+const button = css({
+  padding: "8px 16px",
+  borderRadius: "6px",
+  backgroundColor: "#7F77DD",
+  ":hover": { backgroundColor: "#534AB7" },
+})
+
+export function Button() {
+  return <button className={button}>Click me</button>
+}
+```
+
+That's it! No providers, wrappers, or complex configuration. All styles are extracted at build time.
+
+### App Router & Server Components
+
+next-style works seamlessly with Next.js 13+ App Router and Server Components:
+
+```tsx
+// app/components/Button.tsx (Server Component)
+import { css } from "next-style"
+
+const button = css({ /* styles */ })
+
+export function Button() {
+  return <button className={button}>Click</button>
+}
+```
+
+```tsx
+// app/components/Counter.tsx (Client Component)
+'use client'
+
+import { css } from "next-style"
+import { useState } from "react"
+
+const counter = css({ /* styles */ })
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <div className={counter}>{count}</div>
+}
+```
+
+Both work identically — the `css()` call is evaluated at build time regardless of component type.
+
+## Example
+
 ```tsx
 import { css } from "next-style"
 
@@ -23,7 +119,10 @@ const button = css({
   padding: "8px 16px",
   borderRadius: "6px",
   backgroundColor: "#7F77DD",
+  cursor: "pointer",
+  transition: "background-color 0.2s",
   ":hover": { backgroundColor: "#534AB7" },
+  ":active": { transform: "scale(0.98)" },
   "@md": { padding: "10px 20px" },
 })
 
@@ -37,16 +136,26 @@ export function Button() {
 | | |
 |---|---|
 | ⚡ **Zero runtime** | All styles extracted at build time — 0 bytes of style JS shipped |
-| 🔷 **Turbopack ready** | Works out of the box with Next.js 15+ and Turbopack |
+| 🔷 **Turbopack ready** | Works out of the box with Next.js 16+ and Turbopack |
 | 🔒 **Fully typed** | Every CSS property and value typed via [csstype](https://github.com/frenic/csstype) |
 | 📱 **Responsive first** | Shorthand breakpoints (`@sm` → `@2xl`) sorted mobile-first automatically |
 | ♻️ **Deduplication** | Identical style objects always hash to the same class name |
 | 🌍 **Global styles** | `global()` for resets, base typography, and third-party overrides |
 | 🎞️ **Keyframes** | Declare `@keyframes` inline next to the style that uses them |
 | 📦 **Tiny** | ~2 KB minified + gzipped |
+| 🚀 **Fast builds** | Negligible build-time overhead — simple hashing and string concatenation |
+| 🎨 **CSS-in-JS power** | All CSS features: pseudo-classes, container queries, `@supports`, `@layer`, CSS variables |
 
 Full support for pseudo-classes, pseudo-elements, media queries, container queries, `@supports`, `@layer`, and CSS variables.
 
+### Next.js Version Support
+
+| Next.js Version | Supported |
+|-----------------|-----------|
+| 16+ | ✅ Full support with Turbopack |
+| 15.x | ✅ Supported |
+| < 15.0 | ❌ Not supported |
+
 ## Installation
 
 ```bash
@@ -60,7 +169,11 @@ pnpm add next-style
 bun add next-style
 ```
 
-> **Peer dependency:** `postcss >= 8.0.0` is required. Most Next.js projects already include it.
+**Peer dependencies required:**
+- `next >= 15.0.0`
+- `postcss >= 8.0.0`
+
+> Most Next.js projects already include PostCSS. If you're unsure, check your `package.json` or run `npm list postcss`.
 
 ## Setup
 
@@ -350,22 +463,329 @@ Styles are emitted in this order to ensure correct cascade:
 
 Because styles are extracted at build time, there is no style recalculation, no `<style>` injection, and no FOUC. The output is a single static CSS file.
 
+## Best Practices & Common Patterns
+
+### Reusable Style Objects
+
+Create reusable style definitions by storing them in separate files:
+
+```tsx
+// styles/components.ts
+import { type CSSObject } from "next-style"
+
+export const buttonBase: CSSObject = {
+  padding: "8px 16px",
+  borderRadius: "6px",
+  fontWeight: 500,
+  cursor: "pointer",
+  transition: "all 0.2s",
+  ":active": { transform: "scale(0.98)" },
+}
+
+export const buttonPrimary: CSSObject = {
+  ...buttonBase,
+  backgroundColor: "#7F77DD",
+  color: "white",
+  ":hover": { backgroundColor: "#534AB7" },
+}
+```
+
+```tsx
+// components/Button.tsx
+import { css } from "next-style"
+import { buttonPrimary } from "@/styles/components"
+
+export function Button({ children }: { children: React.ReactNode }) {
+  return <button className={css(buttonPrimary)}>{children}</button>
+}
+```
+
+### Design Tokens with CSS Variables
+
+Centralize your design system using CSS variables:
+
+```tsx
+// app/globals.ts
+import { global } from "next-style"
+
+global({
+  ":root": {
+    // Colors
+    "--color-primary":   "#7F77DD",
+    "--color-secondary": "#534AB7",
+    "--color-text":      "#1a1a1a",
+    "--color-bg":        "#ffffff",
+    
+    // Spacing
+    "--spacing-xs": "4px",
+    "--spacing-sm": "8px",
+    "--spacing-md": "16px",
+    "--spacing-lg": "24px",
+    "--spacing-xl": "32px",
+    
+    // Radius
+    "--radius-sm": "4px",
+    "--radius-md": "8px",
+    "--radius-lg": "12px",
+  },
+  "body": {
+    backgroundColor: "var(--color-bg)",
+    color: "var(--color-text)",
+  },
+})
+```
+
+```tsx
+// Use in components
+const card = css({
+  backgroundColor: "var(--color-bg)",
+  padding: "var(--spacing-md)",
+  borderRadius: "var(--radius-md)",
+})
+```
+
+### Variant Patterns
+
+Create component variants by conditionally merging styles:
+
+```tsx
+import { css, type CSSObject } from "next-style"
+
+interface ButtonProps {
+  variant?: "primary" | "secondary" | "ghost"
+  size?: "sm" | "md" | "lg"
+  children: React.ReactNode
+}
+
+export function Button({ variant = "primary", size = "md", children }: ButtonProps) {
+  const baseStyles: CSSObject = {
+    fontWeight: 500,
+    borderRadius: "6px",
+    cursor: "pointer",
+    transition: "all 0.2s",
+  }
+  
+  const variantStyles: Record<string, CSSObject> = {
+    primary: {
+      backgroundColor: "var(--color-primary)",
+      color: "white",
+      ":hover": { backgroundColor: "var(--color-secondary)" },
+    },
+    secondary: {
+      backgroundColor: "var(--color-secondary)",
+      color: "white",
+    },
+    ghost: {
+      backgroundColor: "transparent",
+      color: "var(--color-primary)",
+      ":hover": { backgroundColor: "rgba(127, 119, 221, 0.1)" },
+    },
+  }
+  
+  const sizeStyles: Record<string, CSSObject> = {
+    sm: { padding: "4px 12px", fontSize: "14px" },
+    md: { padding: "8px 16px", fontSize: "16px" },
+    lg: { padding: "12px 24px", fontSize: "18px" },
+  }
+  
+  const className = css({
+    ...baseStyles,
+    ...variantStyles[variant],
+    ...sizeStyles[size],
+  })
+  
+  return <button className={className}>{children}</button>
+}
+```
+
+### Dark Mode Support
+
+Use CSS variables to implement dark mode:
+
+```tsx
+// app/globals.ts
+import { global } from "next-style"
+
+global({
+  ":root": {
+    "--bg-primary": "#ffffff",
+    "--text-primary": "#1a1a1a",
+  },
+  
+  "[data-theme='dark']": {
+    "--bg-primary": "#1a1a1a",
+    "--text-primary": "#ffffff",
+  },
+})
+```
+
+```tsx
+// components/ThemeToggle.tsx
+'use client'
+
+import { useEffect, useState } from "react"
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useState("light")
+  
+  useEffect(() => {
+    const current = document.documentElement.getAttribute("data-theme") || "light"
+    setTheme(current)
+  }, [])
+  
+  const toggle = () => {
+    const newTheme = theme === "light" ? "dark" : "light"
+    document.documentElement.setAttribute("data-theme", newTheme)
+    setTheme(newTheme)
+  }
+  
+  return <button onClick={toggle}>Toggle Theme</button>
+}
+```
+
 ## Troubleshooting
 
-**Styles not appearing**
+### Styles not appearing
+
+1. ✅ Check that `postcss.config.js` includes `"next-style/plugin": {}`
+2. ✅ Check that `@import "next-style";` is at the **top** of `globals.css` (before other styles)
+3. ✅ Verify you imported `css` from the correct package:
+   ```tsx
+   import { css } from "next-style"  // ✓ correct
+   import { css } from "next-style/plugin"  // ✗ incorrect
+   ```
+4. ✅ Restart the dev server after any PostCSS config change
+5. ✅ Clear the Next.js cache: `rm -rf .next` and restart
+
+### First cold boot shows no styles
+
+On the very first build, no `css()` calls have been evaluated yet so the cache file doesn't exist. Run the dev server once to populate the cache. Subsequent builds will include all styles. This is expected behavior on cold starts.
+
+**For production/CI builds:** The PostCSS plugin automatically scans your source files to extract styles if the cache file is missing, so cold builds on GitHub Actions, Vercel, or other CI systems work without extra setup.
+
+### Build errors after adding PostCSS plugins
+
+Ensure `next-style` is listed **first** in the plugins object — it must run before other transformations:
+
+```js
+// ✓ Correct order
+export default {
+  plugins: {
+    "next-style/plugin": {},
+    autoprefixer: {},
+    "postcss-preset-env": {},
+  },
+}
+
+// ✗ Wrong order (next-style must be first)
+export default {
+  plugins: {
+    autoprefixer: {},
+    "next-style/plugin": {},
+  },
+}
+```
+
+### Styles working in dev but not in production
+
+1. Check that the PostCSS plugin is configured in your build environment
+2. Verify `NODE_ENV=production` is set during build
+3. Look for CSS minification errors in the build logs
+
+### Breakpoints not working
+
+Ensure you're using the correct shorthand:
+
+```tsx
+// ✓ Correct
+css({ "@md": { fontSize: "20px" } })
+
+// ✗ Incorrect (use @md, not md)
+css({ "md": { fontSize: "20px" } })
+```
+
+### TypeScript errors
+
+Install type definitions (usually automatic):
+
+```bash
+npm install --save-dev @types/node
+```
+
+If types are still missing, ensure `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "strict": true
+  }
+}
+```
+
+### Performance concerns
+
+next-style is extremely lightweight:
+- **Runtime JS:** 0 bytes (all styles extracted at build time)
+- **Build time:** Negligible (simple hashing and string operations)
+- **CSS output:** Automatically deduplicated and minified in production
+
+No additional optimizations are needed.
+
+## Browser Support
+
+**next-style** outputs standard CSS and supports all modern browsers:
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome / Chromium | 90+ |
+| Firefox | 87+ |
+| Safari | 14+ |
+| Edge | 90+ |
 
-1. Check that `postcss.config.js` includes `"next-style/plugin": {}`
-2. Check that `@import "next-style";` is at the top of `globals.css`
-3. Restart the dev server after any PostCSS config change
-4. Clear the Next.js cache: `rm -rf .next` and restart
+Older browsers are supported through standard CSS features used. All advanced CSS (container queries, `@supports`, etc.) gracefully degrade in unsupported browsers.
+
+## How It Works
+
+### Architecture Overview
+
+1. **Build Time (Development & Production)**
+   - Your `css()` and `global()` calls are evaluated
+   - Each unique style object is hashed and assigned a class name (e.g., `ns-abc123`)
+   - Compiled CSS is written to `node_modules/.cache/next-style/styles.css`
+
+2. **PostCSS Processing**
+   - The PostCSS plugin reads the cache file
+   - Replaces `@import "next-style"` in your `globals.css` with the collected CSS
+   - Minifies CSS in production using `cssnano`
+
+3. **Runtime (Production)**
+   - Zero JavaScript overhead — styles are already in the static CSS file
+   - No style injection, no hydration cost, no runtime recalculation
+
+### Deduplication
+
+Identical style objects always hash to the same class name:
+
+```tsx
+// These produce the same class name and CSS rule
+const style1 = css({ color: "red", fontSize: "16px" })
+const style2 = css({ color: "red", fontSize: "16px" })
+
+// style1 === style2 → true
+// Output: only one `.ns-xyz { color: red; font-size: 16px; }` rule
+```
 
-**First cold boot shows no styles**
+### File-Based Bridge
 
-On the very first build, no `css()` calls have been evaluated yet so the cache file doesn't exist. Run the dev server once to populate the cache, then styles will appear on reload. This is expected behaviour on cold starts.
+Since PostCSS runs in a separate process, next-style uses a file-based bridge:
+- Every `css()` / `global()` call writes compiled CSS to a cache file
+- The PostCSS plugin reads that file and injects it into your CSS
+- This enables dev-server hot-reloading and zero-setup cold builds
 
-**Build errors after adding PostCSS plugins**
+## Contributing
 
-Ensure next-style is listed **first** in the plugins object — it must run before any other transformations.
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "next-style",
-	"version": "2.2.2",
+	"version": "2.2.3",
 	"description": "Zero-Runtime CSS-in-JS for Next.js + Turbopack",
 	"type": "module",
 	"repository": {
@@ -47,8 +47,8 @@
 		"csstype": "latest"
 	},
 	"peerDependencies": {
-		"next": ">=16.0.0",
-		"postcss": ">=8.0.0"
+		"next": ">=15",
+		"postcss": ">=8"
 	},
 	"keywords": [
 		"css-in-js",