Advanced Usage

Code Splitting

Split CSS by entry points for better caching:

export default {
  input: ['src/a.js', 'src/b.js'],
  output: { dir: 'dist', format: 'es' },
  plugins: [
    requireCSS({
      split: true,
      output: (chunk) => `${chunk.name}.css`
    })
  ]
}

This generates:

• dist/a.js + dist/a.css
• dist/b.js + dist/b.css

Inject CSS

Inject CSS directly into the JavaScript bundle instead of extracting:

requireCSS({
  inject: true
})

This is useful for small CSS files or components.

Shadow DOM Support

Import CSS as a constructable stylesheet for Shadow DOM:

import styles from './component.css' assert { type: 'css' }

class MyElement extends HTMLElement {
  constructor() {
    super()
    const shadow = this.attachShadow({ mode: 'open' })
    shadow.adoptedStyleSheets = [styles]
  }
}

customElements.define('my-element', MyElement)

Enable in config:

requireCSS({
  inject: false,
  // CSS will be exported as constructable stylesheet
})

Caching

Enable caching for faster rebuilds:

requireCSS({
  cache: {
    enabled: true,
    dir: '.cache/css',
    ttl: 3600000 // 1 hour in milliseconds
  }
})

Hot Module Replacement

Enable HMR for development:

requireCSS({
  hmr: true
})

Custom Transform

Apply custom transformations to CSS:

requireCSS({
  transform: (code, id) => {
    // Replace CSS variables
    return code.replace(/--primary-color/g, '--brand-color')
  }
})

Async transform:

requireCSS({
  transform: async (code, id) => {
    const processed = await someAsyncProcess(code)
    return processed
  }
})

Extract Callback

Hook into the CSS extraction process:

requireCSS({
  onExtract: (css, chunk) => {
    console.log(`Extracted ${css.length} bytes for ${chunk.name}`)
    // You can also modify the CSS by returning a new string
  }
})

Plugin API

Access plugin internals at runtime:

const plugin = requireCSS()

// Use in build
export default {
  plugins: [plugin]
}

// Access API after build
const styles = plugin.api.getStyles()
const modules = plugin.api.getCSSModules()
const stats = plugin.api.getStats()

See Plugin API for full documentation.

Integration with Other Tools

With Vite

// vite.config.js
import requireCSS from 'rollup-plugin-require-css'

export default {
  build: {
    rollupOptions: {
      plugins: [requireCSS()]
    }
  }
}

With TypeScript

import typescript from '@rollup/plugin-typescript'
import requireCSS from 'rollup-plugin-require-css'

export default {
  plugins: [
    typescript(),
    requireCSS()
  ]
}

With Node Resolve

import { nodeResolve } from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'
import requireCSS from 'rollup-plugin-require-css'

export default {
  plugins: [
    nodeResolve(),
    commonjs(),
    requireCSS()
  ]
}

CSS Modules Configuration

Fine-tune CSS Modules behavior:

requireCSS({
  modules: {
    enabled: true, // or 'auto'
    generateScopedName: (name, filename, css) => {
      return `_${name}_${hash(css)}`
    },
    globalModulePaths: [/global\.css$/]
  }
})

Custom Scope Name

requireCSS({
  modules: {
    generateScopedName: (localName, resourcePath) => {
      const componentName = path.basename(path.dirname(resourcePath))
      return `${componentName}__${localName}`
    }
  }
})

Global CSS Files

Exclude certain files from CSS Modules:

requireCSS({
  modules: {
    enabled: true,
    globalModulePaths: [
      /global\.css$/,
      /normalize\.css$/,
      /variables\.css$/
    ]
  }
})