Skip to main content

​
Prerequisites

Before installing styled-static, ensure you have:

React 19+

styled-static requires React 19 or later for automatic ref forwarding

Vite

Vite 5.0+ is required for the build-time transformation
styled-static is designed specifically for Vite and React 19+. It won’t work with Webpack, Rollup, or earlier React versions.

​
Install the Package

Choose your preferred package manager and run the installation command: 
npm install @alex.radulescu/styled-static

​
Configure the Vite Plugin

Add the styled-static plugin to your vite.config.ts file. The plugin must be placed before the React plugin in the plugins array. 
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { styledStatic } from '@alex.radulescu/styled-static/vite';

export default defineConfig({
  plugins: [
    styledStatic(), // Must be before react()
    react(),
  ],
});
Plugin Order Matters — The styled-static plugin must come before the React plugin. This ensures proper transformation of styled components.

​
Optional: Lightning CSS

For better performance and automatic vendor prefixes, install Lightning CSS:
1

Install Lightning CSS

Add Lightning CSS to your project:
npm install lightningcss
2

Enable in Vite config

Update your vite.config.ts to use Lightning CSS:
vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { styledStatic } from '@alex.radulescu/styled-static/vite';

export default defineConfig({
  css: {
    transformer: 'lightningcss', // Enable Lightning CSS
  },
  plugins: [
    styledStatic(),
    react(),
  ],
});
Lightning CSS Benefits:
  • Automatic vendor prefixes for better browser compatibility
  • Faster CSS processing than PostCSS
  • Better minification and smaller bundle sizes

​
Configuration Options

The styled-static plugin accepts the following options:
​
classPrefix
string
default:"'ss'"
Prefix for generated class names. Useful for avoiding conflicts in microfrontends or component libraries.
styledStatic({ classPrefix: 'my-app' })
// Generates: .my-app-abc123
​
cssOutput
'auto' | 'virtual' | 'file'
default:"'auto'"
Controls how CSS is output:
  • 'auto' — Uses 'file' for library builds (build.lib set), 'virtual' for apps
  • 'virtual' — CSS as virtual modules (Vite bundles into single file)
  • 'file' — CSS as separate files co-located with JS (enables tree-shaking for libraries)
styledStatic({ cssOutput: 'file' }) // For library builds
​
debug
boolean
default:"false"
Enable debug logging. Set to true or use DEBUG_STYLED_STATIC=true env var.
Debug logs expose file paths and internal state. Disable in production.

​
Verify Installation

Create a simple test component to verify everything is working:
1

Create a test component

Create a new file src/Test.tsx:
src/Test.tsx
import { styled } from '@alex.radulescu/styled-static';

const TestButton = styled.button`
  padding: 0.5rem 1rem;
  background: #3b82f6;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;

  &:hover {
    background: #2563eb;
  }
`;

export function Test() {
  return <TestButton>Hello styled-static!</TestButton>;
}
2

Import and render

Import the test component in your app:
App.tsx
import { Test } from './Test';

function App() {
  return (
    <div>
      <Test />
    </div>
  );
}

export default App;
3

Start the dev server

Run your Vite dev server:
npm run dev
You should see a blue button with hover effects. If you inspect the element, you’ll see a scoped class like ss-abc123.
Installation complete! You’re ready to start using styled-static. Continue to the Quick Start guide to learn more.

​
Troubleshooting

This error means the Vite plugin isn’t configured correctly. Check that:
  1. The styled-static plugin is in your vite.config.ts
  2. It’s placed before the React plugin
  3. You’re importing from the correct package: @alex.radulescu/styled-static
If using styled-static with Storybook, add it to optimizeDeps.include:
.storybook/main.ts
export default {
  viteFinal: async (config) => {
    config.optimizeDeps = config.optimizeDeps || {};
    config.optimizeDeps.include = [
      ...(config.optimizeDeps.include || []),
      '@alex.radulescu/styled-static',
    ];
    return config;
  },
};
Ensure you have React 19+ installed:
npm install react@^19.0.0 react-dom@^19.0.0
npm install -D @types/react@^19.0.0 @types/react-dom@^19.0.0

​
Next Steps

Quick Start

Build your first styled component with a complete example

Core API

Learn about the styled API and all its features

TypeScript Support

Explore TypeScript features and type inference

Configuration

Deep dive into plugin configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us