https://github.com/sunny-117/oxc-loader
webpack/Rspack loader for Oxc
https://github.com/sunny-117/oxc-loader
bundler loader loaders oxc oxc-loader oxc-parser oxc-resolver oxc-transform plugin rspack swc-loader typescript webpack webpack-loader
Last synced: 5 months ago
JSON representation
webpack/Rspack loader for Oxc
- Host: GitHub
- URL: https://github.com/sunny-117/oxc-loader
- Owner: Sunny-117
- License: mit
- Created: 2025-01-06T06:05:29.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-17T07:02:31.000Z (5 months ago)
- Last Synced: 2026-01-17T18:13:18.869Z (5 months ago)
- Topics: bundler, loader, loaders, oxc, oxc-loader, oxc-parser, oxc-resolver, oxc-transform, plugin, rspack, swc-loader, typescript, webpack, webpack-loader
- Language: TypeScript
- Homepage: https://deepwiki.com/Sunny-117/oxc-loader
- Size: 312 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# oxc-loader
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]
A high-performance webpack/Rspack loader for transforming JavaScript and TypeScript using [Oxc](https://github.com/oxc-project/oxc).
## Features
- ⚡ **Ultra Fast**: 3-5x faster than SWC, 20-50x faster than Babel
- 🔧 **TypeScript Support**: Transform TypeScript to JavaScript with type stripping
- ⚛️ **JSX/TSX Support**: Transform React JSX with automatic runtime detection
- 🔄 **React Fast Refresh**: Built-in support for React development
- 📦 **Small Bundle**: Only 2MB vs SWC's 37MB
- 🛠️ **Webpack & Rspack**: Compatible with both bundlers
- 🗺️ **Source Maps**: Full source map support
- ⚙️ **Configurable**: Extensive configuration options
- 📋 **tsconfig.json Support**: Automatic detection and configuration from TypeScript config
## Node.js Compatibility
- Node.js 20.19 or higher
## Installation
```bash
npm install oxc-loader
# or
yarn add oxc-loader
# or
pnpm add oxc-loader
# or
bun add oxc-loader
```
## Usage
### Basic Webpack Configuration
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(js|jsx|ts|tsx)$/,
exclude: /node_modules/,
use: {
loader: 'oxc-loader',
options: {
// Options here
}
}
}
]
}
}
```
### Basic Rspack Configuration
```javascript
// rspack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(js|jsx|ts|tsx)$/,
exclude: /node_modules/,
use: {
loader: 'oxc-loader',
options: {
// Options here
}
}
}
]
}
}
```
## Configuration Options
### Basic Options
```typescript
interface OxcLoaderOptions {
// Enable source map generation (default: true)
sourcemap?: boolean
// Enable React Fast Refresh for development (default: false)
refresh?: boolean
// Automatically detect and configure JSX based on file extension (default: true)
autoDetectJsx?: boolean
// All oxc-transform options are also supported
typescript?: TypeScriptOptions
jsx?: JsxOptions
target?: string | string[]
// ... and more
}
```
### TypeScript Configuration
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.tsx?$/,
use: {
loader: 'oxc-loader',
options: {
typescript: {
onlyRemoveTypeImports: true,
declaration: {
stripInternal: true
}
}
}
}
}
]
}
}
```
### JSX Configuration
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.jsx?$/,
use: {
loader: 'oxc-loader',
options: {
jsx: {
runtime: 'automatic', // or 'classic'
development: process.env.NODE_ENV === 'development',
importSource: 'react'
}
}
}
}
]
}
}
```
### React Fast Refresh
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(jsx|tsx)$/,
use: {
loader: 'oxc-loader',
options: {
refresh: process.env.NODE_ENV === 'development',
jsx: {
runtime: 'automatic',
development: true
}
}
}
}
]
}
}
```
### tsconfig.json Support
oxc-loader automatically reads and applies relevant settings from your `tsconfig.json` file. This feature is enabled by default and helps ensure consistency between your TypeScript configuration and the transformation process.
#### Supported tsconfig.json Options
The following TypeScript compiler options are automatically mapped to oxc-transform settings:
- **`target`**: Maps to oxc-transform's `target` option
- **`jsx`**: Configures JSX transformation mode
- **`jsxFactory`**: Sets custom JSX pragma
- **`jsxFragmentFactory`**: Sets custom JSX fragment pragma
- **`jsxImportSource`**: Sets JSX import source for automatic runtime
- **`allowImportingTsExtensions`**: Enables import extension rewriting
- **`verbatimModuleSyntax`**: Enables type-only import removal
## Examples
### Complete Webpack Configuration
```javascript
// webpack.config.js
const path = require('node:path')
module.exports = {
entry: './src/index.tsx',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js'
},
module: {
rules: [
{
test: /\.(js|jsx|ts|tsx)$/,
exclude: /node_modules/,
use: {
loader: 'oxc-loader',
options: {
// Enable source maps
sourcemap: true,
// Enable React Fast Refresh in development
refresh: process.env.NODE_ENV === 'development',
// TypeScript configuration
typescript: {
onlyRemoveTypeImports: true
},
// JSX configuration (auto-detected for .jsx/.tsx files)
jsx: {
runtime: 'automatic',
development: process.env.NODE_ENV === 'development'
},
// Target modern browsers
target: ['es2020', 'chrome80', 'firefox80', 'safari14']
}
}
}
]
},
resolve: {
extensions: ['.ts', '.tsx', '.js', '.jsx']
}
}
```
### Rspack Configuration
```javascript
// rspack.config.js
const path = require('node:path')
module.exports = {
entry: './src/index.tsx',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js'
},
module: {
rules: [
{
test: /\.(js|jsx|ts|tsx)$/,
exclude: /node_modules/,
use: {
loader: 'oxc-loader',
options: {
refresh: true, // Enable React Fast Refresh
typescript: {
onlyRemoveTypeImports: true
}
}
}
}
]
},
resolve: {
extensions: ['.ts', '.tsx', '.js', '.jsx']
}
}
```
## Performance Comparison
| Tool | Transform Speed | Memory Usage | Bundle Size | Packages |
|------|----------------|--------------|-------------|----------|
| **oxc-loader** | **Baseline** | **51 MB** | **2 MB** | **2** |
| swc-loader | 3-5x slower | 67 MB | 37 MB | Multiple |
| babel-loader | 20-50x slower | 172 MB | 21 MB | 170+ |
*Benchmarks based on oxc-project/bench-transformer*
## Migration Guide
### From babel-loader
```diff
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(js|jsx|ts|tsx)$/,
exclude: /node_modules/,
use: {
- loader: 'babel-loader',
+ loader: 'oxc-loader',
options: {
- presets: [
- '@babel/preset-env',
- '@babel/preset-react',
- '@babel/preset-typescript'
- ]
+ jsx: {
+ runtime: 'automatic'
+ },
+ typescript: {
+ onlyRemoveTypeImports: true
+ }
}
}
}
]
}
}
```
### From swc-loader
```diff
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(js|jsx|ts|tsx)$/,
exclude: /node_modules/,
use: {
- loader: 'swc-loader',
+ loader: 'oxc-loader',
options: {
- jsc: {
- parser: {
- syntax: 'typescript',
- tsx: true
- },
- transform: {
- react: {
- runtime: 'automatic'
- }
- }
- }
+ jsx: {
+ runtime: 'automatic'
+ },
+ typescript: {
+ onlyRemoveTypeImports: true
+ }
}
}
}
]
}
}
```
## Troubleshooting
### Native Binding Issues
If you encounter native binding errors, try:
```bash
# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
# Or with pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install
```
### TypeScript Errors
Make sure your `tsconfig.json` includes the necessary compiler options:
```json
{
"compilerOptions": {
"jsx": "react-jsx",
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler"
}
}
```
## Contributing
Contributions are welcome! Please read our [contributing guide](CONTRIBUTING.md) for details.
## License
[MIT](./LICENSE) License © 2024-PRESENT [Sunny-117](https://github.com/Sunny-117)
## Related Projects
- [oxc](https://github.com/oxc-project/oxc) - The JavaScript Oxidation Compiler
- [oxc-transform](https://www.npmjs.com/package/oxc-transform) - Standalone transform package
- [unplugin-oxc](https://github.com/unplugin/unplugin-oxc) - Oxc integration for unplugin
- [webpack](https://webpack.js.org/) - Module bundler
- [rspack](https://rspack.dev/) - Fast Rust-based bundler
[npm-version-src]: https://img.shields.io/npm/v/oxc-loader?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/oxc-loader
[npm-downloads-src]: https://img.shields.io/npm/dm/oxc-loader?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/oxc-loader
[bundle-src]: https://img.shields.io/bundlephobia/minzip/oxc-loader?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=oxc-loader
[license-src]: https://img.shields.io/github/license/Sunny-117/oxc-loader.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/Sunny-117/oxc-loader/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/oxc-loader