https://github.com/a-type/rsbuild-plugin-unocss
https://github.com/a-type/rsbuild-plugin-unocss
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/a-type/rsbuild-plugin-unocss
- Owner: a-type
- License: mit
- Created: 2025-08-21T13:17:58.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-03-26T03:11:58.000Z (3 months ago)
- Last Synced: 2026-03-26T09:36:31.047Z (3 months ago)
- Language: TypeScript
- Size: 375 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @a-type/rsbuild-plugin-unocss
A minimal but stable Rsbuild plugin for UnoCSS, handwritten for Rsbuild instead of unplugin.
## Features
This plugin doesn't support all UnoCSS features, but it does support some features not available in PostCSS and some workflows I wanted to experiment with for external libraries.
- ✅ Transforms: rewrites source files (`pre` transforms only for now)
- ✅ Filesystem watches in addition to bundled files (using `unoConfig.content.filesystem`)
- ✅ Process `// @unocss-include` comments on selected external modules, even if not matched by your `content.pipeline` rules. This one makes it easy to add this magic comment to your output files in a component library and then run Uno on its output files when it's used in your actual app!
- 🚫 Uno config watching (TODO)
- 🚫 Uno scopes (not actually sure what these are)
## Usage
Install:
```bash
npm add @a-type/rsbuild-plugin-unocss -D
```
Add plugin to your `rsbuild.config.ts`:
```ts
// rsbuild.config.ts
import { pluginUnoCss } from "@a-type/rsbuild-plugin-unocss";
export default {
plugins: [pluginUnoCss({
config: // a path or literal Uno config
})],
};
```
Import `uno.css` in your app:
```ts
import 'uno.css';
```
## Options
### config
A path to an Uno config, or a literal config object. Otherwise it should be inferred as `uno.config.ts`.
- Type: `string`
- Default: `undefined`
- Example:
```js
pluginUnoCss({
config: 'uno.branded.config.ts',
});
```
### enableIncludeCommentCheck
Pass a filter function which takes the absolute path of a bundled source file and returns `true` if you want to check it for an `@unocss-include` comment. The file does _not_ have to be in your UnoCSS `content.pipeline` matchers. You can use this to extract CSS from precompiled NPM libraries without including them in your actual UnoCSS pipeline, as long as those libraries' built sources are postprocessed to add `// @unocss-include`.
- Type: `(filePath: string) => boolean`
- Default: `undefined`
- Example:
```js
pluginUnoCss({
enableIncludeCommentCheck: (filePath) =>
// make sure your test is compatible with OS-dependent path formats
// by using path.join.
// I also recommend including the dist/output dir in your test, to avoid
// nested node_modules.
filePath.includes(path.join('@your-scope', 'component-library', 'dist')),
});
```
### enableCacheExtractedCSS
Pass a filter function to enable caching the extracted CSS classes from particular files. By default this caches any extractions from files in `node_modules` (see `enableIncludeCommentCheck` for why you might have extracted files from `node_modules`).
You may need to change this if you are in a monorepo and want to extract CSS from other projects linked via `node_modules`. Without excluding them using this filter, their initial extracted CSS will be cached and they won't be scanned for changes. Return `false` for files matching your monorepo projects to re-enable live CSS reloading on them.
- Type: `(filePath: string) => boolean`
- Default: `(filePath: string) => filePath.includes('node_modules')`
- Example:
```js
pluginUnoCss({
enableCacheExtractedCSS: (filePath) =>
filePath.includes(`@my-monorepo-scope`)
? false
: filePath.includes('node_modules'),
});
```
### disableTransform
Selectively disable applying your Uno transforms on specific files. This can speed up builds if you know certain files don't need transforms, particularly if you have included pre-transformed files in your content.pipeline configuration.
- Type: `(filePath: string) => boolean`
- Default: `(filePath: string) => filePath.includes('node_modules')`
- Example:
```js
pluginUnoCss({
disableTransform: (filePath) => filePath.includes('tests'),
});
```
## License
[MIT](./LICENSE).