#Installation

#Install the Package

npm install cssxjs

yarn add cssxjs

pnpm add cssxjs

bun add cssxjs

deno add npm:cssxjs

#Configure Babel

Add the CSSX preset to your babel.config.js:

// babel.config.js
module.exports = function (api) {
  api.cache(true)
  return {
    presets: [
      'babel-preset-expo', // or your existing preset
      'cssxjs/babel'
    ]
  }
}

The default options work for most projects. See Babel Options for advanced configuration.

#Configure ESLint

If your project uses Pug templates, install ESLint v9 and the CSSX ESLint plugin:

npm install -D eslint@^9 eslint-plugin-cssxjs
# or
yarn add -D eslint@^9 eslint-plugin-cssxjs
# or
pnpm add -D eslint@^9 eslint-plugin-cssxjs

Use ESLint v9 with the flat config format. Do not use eslint@latest if it resolves to ESLint v10.

// eslint.config.mjs
import { defineConfig } from 'eslint/config'
import cssxjs from 'eslint-plugin-cssxjs'

export default defineConfig([
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: {
      cssxjs
    },
    processor: 'cssxjs/react-pug'
  }
])

With neostandard:

// eslint.config.mjs
import { defineConfig } from 'eslint/config'
import neostandard, { resolveIgnoresFromGitignore } from 'neostandard'
import cssxjs from 'eslint-plugin-cssxjs'

export default defineConfig([
  ...neostandard({
    ignores: resolveIgnoresFromGitignore(),
    ts: true
  }),
  {
    plugins: {
      cssxjs
    },
    processor: 'cssxjs/react-pug'
  }
])

#Verify Installation

Create a simple component to verify everything works:

// App.jsx
import { styl } from 'cssxjs'
import { View, Text } from 'react-native'

export default function App() {
  return (
    <View styleName="container">
      <Text styleName="title">CSSX is working!</Text>
    </View>
  )

  styl`
    .container
      flex 1
      justify-content center
      align-items center
      background-color #f5f5f5
    .title
      font-size 24px
      color #333
  `
}

Run your app and you should see the styled component.

#Separate Style Files (Optional)

While inline styl blocks are recommended (easier composition, colocation with components), you can also use separate style files.

Files must be named with the .cssx.styl extension:

components/
  Button.jsx
  Button.cssx.styl    ← Will be processed by CSSX
  Card.styl           ← NOT processed (missing .cssx prefix)

Import styles in your component:

import './Button.cssx.styl'
import { Pressable, Text } from 'react-native'

function Button({ children }) {
  return (
    <Pressable styleName="button">
      <Text styleName="text">{children}</Text>
    </Pressable>
  )
}

#Metro Config for Hot Reloading (Optional)

If you want .cssx.styl files to hot-reload during development, add the Metro config:

// metro.config.js
const { getDefaultConfig } = require('cssxjs/metro-config')

module.exports = getDefaultConfig(__dirname)

With an existing Metro config:

// metro.config.js
const { getDefaultConfig: getExpoConfig } = require('expo/metro-config')
const { getDefaultConfig } = require('cssxjs/metro-config')

const upstreamConfig = getExpoConfig(__dirname)

module.exports = getDefaultConfig(__dirname, { upstreamConfig })

Note: Metro config is only needed for hot-reloading separate .cssx.styl files. Inline styl blocks work without it.

#Web Support

CSSX is designed primarily for React Native and Expo projects. On web, it works seamlessly through react-native-web — if you're using Expo, web support is included automatically.

#Pure React Web Projects

You can also use CSSX in pure React web projects (without React Native). Just add the Babel preset as shown above. If you use separate .cssx.styl files, configure your bundler (webpack, Vite, etc.) to watch for changes in those files for hot reloading.

#TypeScript Support

CSSX works with TypeScript. If your project uses Pug templates, run Pug-aware type checks with npx cssxjs check instead of relying on tsc --noEmit alone.

See TypeScript Support for details.

#VS Code Extension

Install the following extension for full CSSX support with Pug and CSS/Stylus in style or style(lang='styl') tags:

vscode-react-pug-tsx

For support of the Stylus syntax itself, install the Stylus language extension.

#Next Steps

• Basic Usage - Learn how to use styl and styleName
• TypeScript Support - Type-check Pug templates
• Component Parts - Style child component parts
• CSS Variables - Dynamic theming support