# 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]
[![Discord chat][discord-badge]][discord-url]
[![Website][website-badge]][website-url]
A high-performance webpack/Rspack loader for transforming JavaScript and TypeScript using [Oxc](https://github.com/oxc-project/oxc). A drop-in replacement for `swc-loader` and `babel-loader`.
## 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 -D oxc-loader
# or
yarn add -D oxc-loader
# or
pnpm add -D oxc-loader
# or
bun add -D 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
}
}
}
}
]
}
}
```
### Target
```javascript
{
loader: 'oxc-loader',
options: {
target: 'es2015',
},
}
```
### Source Maps
```javascript
{
loader: 'oxc-loader',
options: {
sourcemap: true,
},
}
```
Source maps are also automatically enabled when webpack's `devtool` option is set.
### 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
[discord-badge]: https://img.shields.io/discord/1079625926024900739?logo=discord&label=Discord
[discord-url]: https://discord.gg/9uXCAwqQZW
[website-badge]: https://img.shields.io/badge/Website-blue
[website-url]: https://oxc.rs