CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-vitejs--plugin-react-swc

Speed up your Vite dev server with SWC for React projects with fast refresh and automatic JSX transformation

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@vitejs/plugin-react-swc

@vitejs/plugin-react-swc is a high-performance Vite plugin that integrates SWC (Speedy Web Compiler) as the JavaScript/TypeScript transformer for React applications, providing significantly faster Fast Refresh (~20x faster than Babel) and automatic JSX runtime transformation.

Package Information

  • Package Name: @vitejs/plugin-react-swc
  • Package Type: npm (Vite plugin)
  • Language: TypeScript
  • Installation: npm install -D @vitejs/plugin-react-swc

Core Imports

import react from '@vitejs/plugin-react-swc';

For CommonJS environments:

const react = require('@vitejs/plugin-react-swc');

Basic Usage

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';

export default defineConfig({
  plugins: [react()],
});

With options:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';

export default defineConfig({
  plugins: [
    react({
      jsxImportSource: '@emotion/react',
      tsDecorators: true,
      devTarget: 'es2022',
    }),
  ],
});

Architecture

The plugin returns an array of specialized Vite plugins that handle different phases of the development and build process:

  • Runtime Resolver: Resolves React refresh runtime during development for HMR functionality
  • Development Transformer: Handles SWC-based transformation during development with Fast Refresh support
  • Production Transformer: Handles optimized transformation for production builds (conditionally applied based on SWC plugin usage)

The plugin automatically configures Vite to disable esbuild transformation and uses SWC for all React-related file processing, with intelligent file type detection and parsing based on file extensions.

Capabilities

Main Plugin Function

Creates a Vite plugin configuration for React with SWC transformation.

/**
 * Creates a Vite plugin configuration for React with SWC transformation
 * @param options - Configuration options for the plugin
 * @returns Array of Vite plugins for React development
 */
declare function react(options?: Options): Plugin[];

interface Options {
  /** Control where the JSX factory is imported from (default: "react") */
  jsxImportSource?: string;
  /** Enable TypeScript decorators. Requires experimentalDecorators in tsconfig (default: false) */
  tsDecorators?: boolean;
  /** Use SWC plugins. Enable SWC at build time */
  plugins?: [string, Record<string, any>][];
  /** Set the target for SWC in dev. This can avoid to down-transpile private class method (default: "es2020") */
  devTarget?: JscTarget;
  /** Override the default include list (.ts, .tsx, .mts, .jsx, .mdx) */
  parserConfig?: (id: string) => ParserConfig | undefined;
  /** React Fast Refresh runtime URL prefix for module federation context */
  reactRefreshHost?: string;
  /** Direct SWC options mutation - use at your own risk */
  useAtYourOwnRisk_mutateSwcOptions?: (options: SWCOptions) => void;
  /** If set, disables the recommendation to use @vitejs/plugin-react */
  disableOxcRecommendation?: boolean;
}

Usage Examples:

// Basic usage with no options
export default defineConfig({
  plugins: [react()],
});

// With JSX import source for Emotion
export default defineConfig({
  plugins: [
    react({
      jsxImportSource: '@emotion/react',
    }),
  ],
});

// With TypeScript decorators support
export default defineConfig({
  plugins: [
    react({
      tsDecorators: true,
    }),
  ],
});

// With SWC plugins for styled-components
export default defineConfig({
  plugins: [
    react({
      plugins: [['@swc/plugin-styled-components', {}]],
    }),
  ],
});

// With custom development target
export default defineConfig({
  plugins: [
    react({
      devTarget: 'es2022',
    }),
  ],
});

// Module federation setup
export default defineConfig({
  plugins: [
    react({
      reactRefreshHost: 'http://localhost:3000',
    }),
  ],
});

Custom Parser Configuration

Allows overriding the default file processing rules for advanced use cases.

/**
 * Custom parser configuration function
 * @param id - File path/identifier to check
 * @returns Parser configuration for the file, or undefined to skip processing
 */
type ParserConfigFunction = (id: string) => ParserConfig | undefined;

interface ParserConfig {
  /** Parser syntax type */
  syntax: 'typescript' | 'ecmascript';
  /** Enable JSX parsing */
  jsx?: boolean;
  /** Enable TSX parsing (TypeScript + JSX) */
  tsx?: boolean;
  /** Enable decorator support */
  decorators?: boolean;
}

Usage Examples:

// Custom file extension support
export default defineConfig({
  plugins: [
    react({
      parserConfig(id) {
        // Support ReScript files compiled to JSX
        if (id.endsWith('.res')) {
          return { syntax: 'ecmascript', jsx: true };
        }
        // Custom TypeScript configuration
        if (id.endsWith('.ts')) {
          return { syntax: 'typescript', tsx: false, decorators: true };
        }
      },
    }),
  ],
});

SWC Integration Options

Advanced SWC configuration for specialized build requirements.

/**
 * SWC target compilation options
 */
type JscTarget = 
  | 'es3' | 'es5' | 'es2015' | 'es2016' | 'es2017' | 'es2018' 
  | 'es2019' | 'es2020' | 'es2021' | 'es2022' | 'es2023' | 'es2024' | 'esnext';

/**
 * SWC plugin configuration tuple
 */
type SWCPlugin = [string, Record<string, any>];

/**
 * Complete SWC options interface (for advanced mutation)
 */
interface SWCOptions {
  /** The filename associated with the code being compiled */
  filename?: string;
  /** Enable searching for .swcrc configuration files */
  swcrc?: boolean;
  /** Enable searching for configuration files */
  configFile?: boolean;
  /** Enable source map generation */
  sourceMaps?: boolean;
  /** The working directory for resolving paths */
  cwd?: string;
  /** Module specifier for input source map */
  inputSourceMap?: boolean | string;
  /** JavaScript Compiler (JSC) configuration */
  jsc?: {
    /** Compilation target */
    target?: JscTarget;
    /** Parser configuration */
    parser?: ParserConfig;
    /** Experimental features */
    experimental?: {
      /** SWC plugins to apply */
      plugins?: SWCPlugin[];
    };
    /** Transform configuration */
    transform?: {
      /** Enable useDefineForClassFields */
      useDefineForClassFields?: boolean;
      /** React-specific transformations */
      react?: ReactConfig;
    };
  };
}

Usage Examples:

// Advanced SWC options mutation
export default defineConfig({
  plugins: [
    react({
      useAtYourOwnRisk_mutateSwcOptions(options) {
        // Enable experimental decorator version
        options.jsc.parser.decorators = true;
        options.jsc.transform.decoratorVersion = '2022-03';
        
        // Custom experimental features
        options.jsc.experimental = {
          ...options.jsc.experimental,
          plugins: [
            ['@swc/plugin-emotion', { autoLabel: true }],
          ],
        };
      },
    }),
  ],
});

Types

Core Plugin Types

/** Vite plugin interface from 'vite' package */
interface Plugin {
  name: string;
  apply?: 'build' | 'serve' | ((config: UserConfig, env: ConfigEnv) => boolean);
  enforce?: 'pre' | 'post';
  // ... additional Vite plugin properties
}

/** React configuration for SWC transformation */
interface ReactConfig {
  /** JSX runtime mode */
  runtime?: 'automatic' | 'classic' | 'preserve';
  /** Enable development mode features */
  development?: boolean;
  /** Enable React Fast Refresh */
  refresh?: boolean | {
    refreshReg?: string;
    refreshSig?: string;
    emitFullSignatures?: boolean;
  };
  /** Module specifier for importing jsx/jsxs factory functions */
  importSource?: string;
  /** Replace the function used when compiling JSX expressions */
  pragma?: string;
  /** Replace the component used when compiling JSX fragments */
  pragmaFrag?: string;
  /** Throw error if XML namespaced tag name is used */
  throwIfNamespace?: boolean;
}

File Processing Types

/** SWC transformation output */
interface Output {
  /** Transformed code */
  code: string;
  /** Source map (not base64 encoded) */
  map?: string;
}

Error Handling

The plugin includes enhanced error handling that:

  • Catches SWC transformation errors and extracts precise line/column information
  • Provides detailed error messages with file locations for debugging
  • Maintains source map accuracy for proper error reporting in development tools

Common error scenarios:

  • Syntax Errors: Invalid TypeScript/JSX syntax in source files
  • Decorator Errors: Using decorators without proper TypeScript configuration
  • Plugin Errors: Issues with SWC plugins or incompatible plugin configurations
  • Target Compatibility: Using language features not supported by the specified devTarget

Platform Requirements

  • Node.js: ^20.19.0 || >=22.12.0
  • Vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
  • Dependencies: @swc/core ^1.13.2, @rolldown/pluginutils 1.0.0-beta.32

Performance Characteristics

  • Fast Refresh: ~20x faster than Babel-based alternatives
  • File Processing: Supports .tsx, .ts, .mts, .jsx, .mdx files by default
  • Build Optimization: Conditional SWC usage in production based on plugin configuration
  • Memory Efficiency: Lazy evaluation and efficient transformation pipelines
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vitejs/plugin-react-swc@4.0.x
Publish Source
CLI
Badge
tessl/npm-vitejs--plugin-react-swc badge