gulp-swc

2.2.0 verified Fri May 01 auth: no javascript

Gulp plugin for integrating the SWC (rust-based JavaScript/TypeScript compiler) into Gulp pipelines. Current stable version is 2.2.0 (released 2024-07-23), with a bus factor of less than 10 contributors and monthly releases. It provides fast transpilation via SWC, supports both CommonJS and ESM, and requires peer dependencies `@swc/core` (^1.7.20) and `gulp` (3.x, 4.x, or 5.x). Compared to gulp-babel or gulp-typescript, it offers significantly faster compilation and native TypeScript support without separate type checking. Node.js >=18 required.

Common errors

error Error: Module "@swc/core" has been externalized for browser compatibility and cannot be accessed in client code. ↓

cause Trying to use gulp-swc in a browser/Node vs ESM context where @swc/core is not natively available.

fix

Ensure gulp-swc runs in a Node.js environment (not bundled for browser). In tooling scripts, use CommonJS require with Node >=18.

error TypeError: swc is not a function ↓

cause Using an incorrect import style (e.g., named import instead of default).

fix

Use const swc = require('gulp-swc'); or import swc from 'gulp-swc';

error gulp-swc: options must be an object ↓

cause Calling swc() without any arguments or passing a non-object (e.g., a string).

fix

Always pass an object: swc({...}) or at least swc({}).

error Error: Received null/undefined for source map chain. Ensure sourcemaps are created before swc. ↓

cause gulp-sourcemaps .init() is placed after .pipe(swc()) instead of before.

fix

Reorder: .pipe(sourcemaps.init()).pipe(swc()).pipe(sourcemaps.write()).

Warnings

breaking gulp-swc dropped support for Node.js <18 in v2.0.0. Older versions (1.x) are no longer maintained. ↓

fix Upgrade Node.js to >=18 or pin gulp-swc to v1.x.

deprecated The swc() function called without options (i.e., no configuration argument) is deprecated since v2.1.0. Future versions will require at least an empty object. ↓

fix Always pass an options object: swc({}).

gotcha When using gulp-sourcemaps, you must call swc() after sourcemaps.init() and before sourcemaps.write(). An incorrect order causes source map corruption. ↓

fix Order: .pipe(sourcemaps.init()).pipe(swc()).pipe(sourcemaps.write()).

breaking Peer dependency @swc/core was updated from ^1.3.46 to ^1.7.20 in v2.0.0. Incompatible options (e.g., 'target' field renamed) may cause runtime errors. ↓

fix Update @swc/core and adjust SWC options according to SWC changelog.

gotcha The plugin expects the SWC configuration object to be a plain object; passing a function or promise causes unexpected behavior. ↓

fix Always provide a static configuration object or call a synchronous function that returns an object.

deprecated Support for Gulp v3 (gulp@~3.9.0) is deprecated since v2.0.0 and will be removed in v3.0.0. ↓

fix Upgrade to Gulp v4 or v5.

Install

npm install gulp-swc

yarn add gulp-swc

pnpm add gulp-swc

Imports

gulpSwc
wrong
```
import swc from 'gulp-swc';
```
correct
```
const swc = require('gulp-swc');
```
CommonJS require is the standard pattern for Gulp plugins; ESM import may be unavailable or experimental.
default
wrong
```
import { default as swc } from 'gulp-swc';
```
correct
```
import swc from 'gulp-swc';
```
If using ESM (with 'type': 'module' in package.json or .mjs extension), default import works correctly.
gulpSwc
```
export function gulpSwc() { ... }
```
No common mistakes with this symbol; it's a default export function.

Quickstart

Demonstrates a basic Gulp task that compiles TypeScript files using SWC with a custom configuration for parser, target, minification, and module type.

const gulp = require('gulp');
const swc = require('gulp-swc');

gulp.task('build', function () {
  return gulp
    .src('src/**/*.ts')
    .pipe(swc({
      jsc: {
        parser: {
          syntax: 'typescript'
        },
        target: 'es2020',
        minify: {
          compress: true,
          mangle: true
        }
      },
      module: {
        type: 'commonjs'
      }
    }))
    .pipe(gulp.dest('dist'));
});