esbuild-plugin-raw-css

0.1.0 verified Fri May 01 auth: no javascript

An esbuild plugin (v0.1.0) that imports CSS files as minified raw text strings. It allows developers to embed CSS content directly into JavaScript bundles without runtime style injection. The plugin supports optional minification (default true) and works with esbuild versions ^0.14.36, ^0.15.0, or ^0.16.0. This is a niche tool for situations where CSS must be handled as strings, such as dynamic injection or custom style processing, but lacks broader support or active maintenance beyond initial release.

Common errors

error Error: Could not resolve './styles.css?raw' (did you mean './styles.css'?) ↓

cause The plugin is not configured in esbuild build options, or the path is incorrect.

fix

Ensure rawCssPlugin is included in the plugins array when calling esbuild.build().

error TypeError: rawCssPlugin is not a function ↓

cause Default import used but package is not ESM, or imported incorrectly in a CommonJS context.

fix

Use import rawCssPlugin from 'esbuild-plugin-raw-css' in ESM, or const { default: rawCssPlugin } = await import('esbuild-plugin-raw-css') in CJS.

Warnings

gotcha Importing CSS without ?raw query fails silently — esbuild treats it as a normal CSS import, potentially causing build errors or unexpected behavior. ↓

fix Always append ?raw to CSS file imports (e.g., import './styles.css?raw').

deprecated No known deprecations at version 0.1.0. However, esbuild's CSS handling evolves; check compatibility with esbuild >=0.17.0. ↓

fix Pin esbuild to ^0.14.36 || ^0.15.0 || ^0.16.0 or test with newer versions.

gotcha TypeScript declaration for *.css?raw is not automatically provided; you must add a module declaration manually. ↓

fix Add 'declare module "*.css?raw" { const src: string; export default src; }' to a .d.ts file.

gotcha The plugin only affects files ending with .css?raw. Other file extensions (e.g., .scss?raw) are not supported out of the box. ↓

fix Use esbuild's native loader for other CSS preprocessors or extend the plugin.

Install

npm install esbuild-plugin-raw-css

yarn add esbuild-plugin-raw-css

pnpm add esbuild-plugin-raw-css

Imports

default

wrong

const rawCssPlugin = require('esbuild-plugin-raw-css')

correct

import rawCssPlugin from 'esbuild-plugin-raw-css'

Package is ESM-only; require() will fail unless using a dynamic import or esbuild bundler.

RawCssPluginOptions

wrong

import { RawCssPluginOptions } from 'esbuild-plugin-raw-css'

correct

import type { RawCssPluginOptions } from 'esbuild-plugin-raw-css'

Type import for TypeScript; only available as a type since v0.1.0.

styles
wrong
```
import styles from './styles.css'
```
correct
```
import styles from './styles.css?raw'
```
The query parameter ?raw is mandatory to trigger the plugin. Without it, esbuild treats CSS as a regular CSS file.

Quickstart

Shows how to configure esbuild with the plugin and verify CSS is imported as raw text.

import esbuild from 'esbuild';
import rawCssPlugin from 'esbuild-plugin-raw-css';
const result = await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  plugins: [
    rawCssPlugin({ minify: false }),
  ],
  write: false,
});
const code = result.outputFiles[0].text;
console.log(code.includes('.one')); // true if css imported with ?raw