ESM Compiler

0.9.2 verified Fri May 01 auth: no javascript

ESM Compiler is a Rust-based compiler for the esm.sh playground, leveraging swc for JavaScript/TypeScript/JSX transformation and lightningcss for CSS. Built as a WebAssembly module, it compiles modern frontend code into ESM-compatible output with import maps. Version 0.9.2 is the current stable release; it is actively developed as part of the esm.sh ecosystem. Key differentiators include its Wasm-first architecture, Rust performance, and tight integration with esm.sh's import map resolution, making it suitable for in-browser code transformation without a server.

Common errors

error Error: transform is not a function ↓

cause init() was not called or the Wasm module failed to load

fix

Call await init() before calling transform, and check network requests for the .wasm file.

error Uncaught (in promise) TypeError: Cannot read properties of undefined (reading '__wbg_...') ↓

cause Calling transform before init() has completed

fix

Wrap your transform calls in an async function and ensure init() is awaited.

error Module parse failed: Unexpected token (10:20) You may need an appropriate loader to handle this file type. ↓

cause Bundler (e.g., webpack) cannot handle Wasm blob URL or ES module imports from esm.sh

fix

Use a bundler like Vite or configure webpack to support WebAssembly and esm.sh imports.

Warnings

breaking init() must be called before any transform call ↓

fix Ensure init() is awaited once at the start of your application.

breaking Version 0.9.x changed import resolution to require full URL imports ↓

fix Use the full esm.sh URL (https://esm.sh/esm-compiler) instead of a local or npm import.

deprecated The previous synchronous transform API is deprecated ↓

fix Use the async transform function returned after init().

gotcha TypeScript types are only exported as type-only; cannot be used as runtime values ↓

fix Use 'import type { ... }' for type imports to avoid bundling errors.

gotcha importMap.imports must include '@jsxImportSource' for JSX to work correctly ↓

fix Always specify the JSX import source in the import map imports object.

Install

npm install esm-compiler

yarn add esm-compiler

pnpm add esm-compiler

Imports

init
wrong
```
const init = require('esm-compiler')
```
correct
```
import init, { transform } from 'https://esm.sh/esm-compiler'
```
This is an ESM package loaded via URL (esm.sh). init() must be called to load the Wasm module before using transform.
transform
wrong
```
import transform from 'esm-compiler'
```
correct
```
import { transform } from 'https://esm.sh/esm-compiler'
```
transform is a named export, not default. Must be destructured from the module.
TransformOptions
wrong
```
import { TransformOptions } from 'esm-compiler'
```
correct
```
import type { TransformOptions } from 'https://esm.sh/esm-compiler'
```
TransformOptions is a TypeScript type and should be imported using import type for runtime efficiency in bundlers.

Quickstart

Initializes the Wasm compiler, transforms a React JSX component with an import map, and logs the compiled ESM output.

import init, { transform } from 'https://esm.sh/esm-compiler@0.9.2';
await init();

const code = `
import { useState } from "react";

export default function App() {
  const [msg] = useState("world");
  return <h1>Hello {msg}!</h1>;
}
`;

const importMap = {
  imports: {
    "@jsxImportSource": "https://esm.sh/react@18",
    "react": "https://esm.sh/react@18"
  }
};

const result = transform('./App.tsx', code, { importMap });
console.log(result.code);