tessl/npm-swc--cli

This package provides a command-line interface for the SWC (Speedy Web Compiler) project, a super-fast TypeScript/JavaScript compiler and bundler written in Rust.

—

Pending

Overview

Eval results

Files

Experimental SWC CLI (swcx)

Name: tessl/npm-swc--cli
Author: tessl

Next-generation CLI interface that automatically downloads and uses pre-built SWC binaries for optimal performance. This experimental tool provides the same functionality as the main SWC CLI but with improved performance through native binary execution.

Capabilities

swcx CLI Command

The experimental SWC CLI that downloads and executes optimized pre-built binaries.

npx swcx [options] <files...>

# Supports all the same options as the main swc CLI:
-d, --out-dir [out]           # Compile to output directory
-o, --out-file [out]          # Compile to single output file  
-w, --watch                   # Watch for file changes
-s, --source-maps [type]      # Generate source maps
-q, --quiet                   # Suppress compilation output
# ... and all other swc options

Usage Examples:

# Basic compilation (same as swc)
npx swcx src/index.ts -o lib/index.js

# Directory compilation with watch mode
npx swcx src -d lib --watch

# All swc CLI options are supported
npx swcx src -d lib --source-maps --workers 4

Environment Configuration

Control swcx behavior through environment variables.

const SWC_CLI_ENV: {
  /** Override the SWC core version to use */
  SWCX_CORE_VERSION_OVERRIDE: "SWCX_CORE_VERSION_OVERRIDE";
  /** Skip automatic version checking */
  SWCX_SKIP_CORE_VERSION_CHECK: "SWCX_SKIP_CORE_VERSION_CHECK";
};

Environment Examples:

# Use specific SWC version
SWCX_CORE_VERSION_OVERRIDE=1.3.50 npx swcx src -d lib

# Skip version checking
SWCX_SKIP_CORE_VERSION_CHECK=1 npx swcx src -d lib

# Combined usage
SWCX_CORE_VERSION_OVERRIDE=1.3.50 SWCX_SKIP_CORE_VERSION_CHECK=1 npx swcx src -d lib

Core Version Detection

Automatically determine the appropriate SWC core version to use.

/**
 * Determine the SWC core version to use based on project configuration
 * 
 * Priority order:
 * 1. SWCX_CORE_VERSION_OVERRIDE environment variable
 * 2. @swc/core version from local package.json dependencies
 * 3. Latest available version at CLI publish time
 * 
 * @returns SWC core version string
 */
function getCoreVersion(): string;

Version Detection Logic:

Environment Override: Uses SWCX_CORE_VERSION_OVERRIDE if set
Project Dependencies: Reads @swc/core version from local package.json
Fallback: Uses latest version available when CLI was published (1.3.24)
Error Handling: Falls back to latest version if detection fails

Binary Management

Handle platform-specific binary downloads and execution.

/**
 * Get the platform-specific binary name for SWC
 * 
 * Supports:
 * - Windows: x64, ia32, arm64 (MSVC)
 * - macOS: x64, arm64
 * - Linux: x64, arm64, arm (GNU/musl detection)
 * 
 * @returns Platform-specific binary filename
 * @throws Error if platform/architecture is unsupported
 */
function getBinaryName(): string;

/**
 * Check if the system uses musl libc (Alpine Linux, etc.)
 * @returns True if musl libc is detected
 */
function isMusl(): boolean;

/**
 * Download SWC binary and execute with provided arguments
 * 
 * Process:
 * 1. Determine SWC version and platform binary name
 * 2. Download binary from GitHub releases if not cached
 * 3. Cache binary in node_modules/.bin/swc-cli-{version}
 * 4. Execute binary with forwarded command-line arguments
 * 
 * @returns Promise resolving to spawned child process
 */
function executeBinary(): Promise<ChildProcess>;

Binary Download Process:

Version Resolution: Determine SWC core version to use
Platform Detection: Identify OS and architecture
Binary Selection: Choose correct binary from supported platforms
Download: Fetch from https://github.com/swc-project/swc/releases/download/v{version}/{binary}
Caching: Store in node_modules/.bin/swc-cli-{version}/
Execution: Spawn binary with forwarded arguments

Platform Support

Supported platforms and architectures:

type PlatformBinaryMap = {
  win32: {
    x64: "swc-win32-x64-msvc.exe";
    ia32: "swc-win32-ia32-msvc.exe";
    arm64: "swc-win32-arm64-msvc.exe";
  };
  darwin: {
    x64: "swc-darwin-x64";
    arm64: "swc-darwin-arm64";
  };
  linux: {
    x64: "swc-linux-x64-gnu" | "swc-linux-x64-musl";
    arm64: "swc-linux-arm64-gnu" | "swc-linux-arm64-musl";
    arm: "swc-linux-arm64-gnu";
  };
};

Error Handling

Common error scenarios and handling:

// Unsupported platform error
throw new Error(
  `Unsupported platform: binary ${binaryName} for '${platform} ${arch}' is not available`
);

// Version detection warnings
console.warn(
  `Failed to determine swc core version from package.json, using latest available version ${latestVersion} instead`,
  error
);

// Binary download/execution errors are handled by bin-wrapper

Performance Benefits

swcx provides performance improvements over the main CLI:

Native Speed: Direct execution of Rust-compiled binaries
Reduced Overhead: Eliminates Node.js/JavaScript parsing overhead
Optimized Builds: Uses production-optimized SWC binaries
Version Matching: Automatically uses version matching your project
Caching: Downloads binaries once and reuses them

Migration Guide

Switching from swc to swcx:

# Before (traditional CLI)
npx swc src -d lib --watch

# After (experimental CLI)  
npx swcx src -d lib --watch

# All options remain the same
npx swcx src -d lib --source-maps --workers 4 --extensions .ts,.tsx

Package.json Integration:

{
  "scripts": {
    "build": "swcx src -d lib",
    "build:watch": "swcx src -d lib --watch",
    "build:prod": "swcx src -d lib --source-maps"
  }
}

Types

type ChildProcess = import("child_process").ChildProcess;
type StdioOptions = import("child_process").StdioOptions;

interface PlatformBinaryMap {
  [platform: string]: {
    [arch: string]: string;
  };
}

const SWC_CLI_ENV: {
  SWCX_CORE_VERSION_OVERRIDE: "SWCX_CORE_VERSION_OVERRIDE";
  SWCX_SKIP_CORE_VERSION_CHECK: "SWCX_SKIP_CORE_VERSION_CHECK";
};

Install with Tessl CLI