esbuild-coffeescript

3.1.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin that enables importing and bundling CoffeeScript (.coffee, .litcoffee) files directly within esbuild builds. Current stable version is 3.1.0, updated regularly (multiple releases per year), peer dependency on esbuild >=0.25.9. Key differentiators: integrates CoffeeScript compilation directly into esbuild's pipeline, supports both regular and literate CoffeeScript, offers configurable options (bare, inlineMap), and is designed for Node.js environments. Ships TypeScript type definitions for a better development experience.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/esbuild-coffeescript/index.js from /path/to/project/build.js not supported. ↓

cause Using require() to import an ESM-only package in a CJS context.

fix

Convert your project to ESM (set type: 'module' in package.json) or use dynamic import: import('esbuild-coffeescript').then(m => m.default()).

error TypeError: coffeeScriptPlugin is not a function ↓

cause Incorrect import of the default export, e.g., using named import when default import is required.

fix

Use import coffeeScriptPlugin from 'esbuild-coffeescript' (default import) instead of import { coffeeScriptPlugin } from 'esbuild-coffeescript'.

error Plugin 'esbuild-coffeescript' encountered an error: CoffeeScript version mismatch. Expected >=2.0.0, got 1.12.7 ↓

cause The plugin requires CoffeeScript 2.x or higher, but an older version is installed.

fix

Run npm install coffeescript@latest to upgrade CoffeeScript to version 2 or later.

Warnings

breaking v3.0.0 drops Node.js <20 support and removes the CommonJS entry point; the package is now ESM-only. ↓

fix Upgrade to Node.js >=20 and use import syntax instead of require().

breaking The bare option default changed from false to true in v2.0.0, potentially breaking builds that relied on the IIFE wrapper. ↓

fix Set bare: false explicitly if you need the IIFE wrapper, or adjust your code to expect bare compilation.

deprecated Passing options via second argument (coffeeScriptPlugin({}, options)) was deprecated in v2.1.0 and removed in v3.0.0. ↓

fix Pass all options as the first argument: coffeeScriptPlugin({ bare: true, inlineMap: true }).

gotcha Source maps from CoffeeScript may not align perfectly with transformed JavaScript; disable inlineMap if you experience mapping issues. ↓

fix Set inlineMap: false and rely on esbuild's source map generation instead.

gotcha The plugin only handles .coffee and .litcoffee files; other CoffeeScript-like extensions (e.g., .coffee.md) are not recognized. ↓

fix Rename files to .litcoffee or manually configure additional extensions via CoffeeScript's register() function.

Install

npm install esbuild-coffeescript

yarn add esbuild-coffeescript

pnpm add esbuild-coffeescript

Imports

default

wrong

const coffeeScriptPlugin = require('esbuild-coffeescript')

correct

import coffeeScriptPlugin from 'esbuild-coffeescript'

The package is ESM-only since v3; CommonJS require() will fail.

coffeeScriptPlugin (named export)
```
import { coffeeScriptPlugin } from 'esbuild-coffeescript'
```
Also available as a named export for consistency with esbuild plugin conventions.

CoffeeScriptOptions (type)

wrong

import { CoffeeScriptOptions } from 'esbuild-coffeescript' (value import will cause runtime error)

correct

import type { CoffeeScriptOptions } from 'esbuild-coffeescript'

TypeScript users should use type-only imports to avoid bundling runtime code.

Quickstart

Shows basic usage: import the plugin, pass it as an esbuild plugin, and bundle a CoffeeScript entry point.

import coffeeScriptPlugin from 'esbuild-coffeescript';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/main.coffee'],
  bundle: true,
  plugins: [coffeeScriptPlugin()],
  outfile: 'dist/bundle.js',
});

// main.coffee content:
// answer = 42
// console.log("the answer is #{answer}")