stailwc

0.17.0 verified Fri May 01 auth: no javascript

An experimental SWC transpiler that brings compile-time Tailwind macros to SWC and Next.js, similar to twin.macro but with better performance via SWC instead of Babel. Current stable version is 0.17.0, actively developed with a focus on Next.js compatibility (tested with v13.4.3). Supports both emotion and styled-components as CSS-in-JS engines, with features like the tw JSX attribute, tw template tag, component syntax, and global styles. Key differentiator: 10-100x faster compilation compared to Babel-based alternatives due to SWC's Rust-based implementation.

Common errors

error Error: Cannot find module 'stailwc/install' ↓

cause Incorrect import path or module not installed.

fix

Ensure stailwc is installed (e.g., npm install -D stailwc) and use require('stailwc/install') in next.config.js.

error Module parse failed: Unexpected token (1:8) for stailwc install file ↓

cause Webpack or bundler trying to parse the plugin config file.

fix

Ensure stailwc/install is only required in next.config.js (Node.js context), not in client-side code.

error TypeError: stailwc is not a function ↓

cause Incorrect usage of the plugin function; maybe double-called or missing options.

fix

Call stailwc({ engine: 'emotion' }) directly in the swcPlugins array, not as a reference.

Warnings

breaking stailwc 0.17.0 requires SWC plugin API v1; older versions incompatible with SWC 1.3.24+ ↓

fix Upgrade to stailwc 0.17.0 or later and use SWC 1.3.24+

deprecated The `tw` template tag import may be stripped at build time but still required for TypeScript types; if missing, TypeScript will error on `tw` usage. ↓

fix Add `import { tw } from 'stailwc'` in any file using the template tag.

gotcha The `install` module must be required with CommonJS `require()` in next.config.js; using `import` will fail. ↓

fix Use `const stailwc = require('stailwc/install')` instead of ESM import.

gotcha Emotion or styled-components must be enabled in Next.js compiler options alongside the plugin; missing compiler option causes runtime errors. ↓

fix Set `compiler.emotion: true` for emotion or `compiler.styledComponents: true` for styled-components in next.config.js.

Install

npm install stailwc

yarn add stailwc

pnpm add stailwc

Imports

stailwc
wrong
```
import stailwc from 'stailwc/install'
```
correct
```
const stailwc = require('stailwc/install')
```
The install module must be required in next.config.js due to SWC plugin API expectations; ESM imports may fail at runtime.

TailwindStyle

wrong

import TailwindStyle from 'stailwc'

correct

import { TailwindStyle } from 'stailwc'

Named export, not default.

tw
wrong
```
import tw from 'stailwc'
```
correct
```
import { tw } from 'stailwc'
```
Named export used for template tag and component syntax. Typically used via Babel macro-like transpilation; the import is needed for type checking but may be stripped at build time.

Quickstart

Demonstrates Next.js configuration with stailwc SWC plugin, TailwindStyle component for base styles, and tw usage via JSX attribute and template tag.

// next.config.js
const stailwc = require('stailwc/install');

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
  experimental: {
    swcPlugins: [
      stailwc({
        engine: 'emotion', // or 'styled-components'
      }),
    ],
  },
  compiler: {
    emotion: true, // or styledComponents: true
  },
};

module.exports = nextConfig;

// _document.tsx
import { TailwindStyle } from 'stailwc';

export default function Document() {
  return (
    <div>
      <TailwindStyle />
    </div>
  );
}

// pages/index.tsx
import { tw } from 'stailwc';
import { useState } from 'react';

export default function Home() {
  const [clicked, setClicked] = useState(0);
  return (
    <button
      tw="p-1 m-4 text-green bg-white hover:bg-gray"
      css={clicked % 2 === 0 ? tw`border-green` : tw`border-blue`}
      onClick={() => setClicked(clicked + 1)}
    >
      Clicked {clicked} times
    </button>
  );
}