CoffeeScript Compiler

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax to load the `coffeescript` package in a CommonJS context (e.g., an old Node.js script without `"type": "module"` in `package.json` or an `.mjs` extension) or vice-versa.
  fix If in a CommonJS environment, use `const CoffeeScript = require('coffeescript');`. If in an ESM environment, ensure your `package.json` has `"type": "module"` or your file ends in `.mjs`, and use `import { compile } from 'coffeescript';` or `import * as CoffeeScript from 'coffeescript';`.

• Error: Cannot find module 'coffeescript'

  cause The `coffeescript` package is not installed or not resolvable in the current environment.
  fix Install the package locally with `npm install --save-dev coffeescript` for project-specific use, or globally with `npm install --global coffeescript` if using the `coffee` CLI tool system-wide. Verify the installation path and Node.js module resolution.

• TypeError: (intermediate value).compile is not a function

  cause This typically occurs when the `coffeescript` module is imported incorrectly, resulting in `undefined` or an unexpected value when attempting to access the `compile` method. This could be due to incorrect default vs. named import, or CJS/ESM interop issues.
  fix For CommonJS, use `const CoffeeScript = require('coffeescript');` and then `CoffeeScript.compile(...)`. For ESM, use `import { compile } from 'coffeescript';` if available, or `import * as CoffeeScript from 'coffeescript';` and then `CoffeeScript.compile(...)`. Verify the specific export structure of the installed version.

• CoffeeScript 1.x for...in loops iterate over values, but CoffeeScript 2.x for...in loops iterate over keys.

  cause This is a deliberate breaking change introduced in CoffeeScript 2.x to align `for...in` behavior with JavaScript. Users upgrading from 1.x might expect the old value-iteration behavior.
  fix For iterating over *values* in CoffeeScript 2.x, use `for value of array` (for arrays) or `for key, value of object` (for objects). Reserve `for key in object` for iterating over keys. Adjust existing 1.x code accordingly.

Warnings

• breaking CoffeeScript 2.x introduced significant changes in its output and some syntax semantics compared to 1.x, aiming to align with modern JavaScript (ES2015+). This includes changes to how `for...in` loops behave (now iterating keys, not values), `super` calls, implicit returns, and strict mode output. Migration from 1.x to 2.x may require adjustments.
  Fix: Review the CoffeeScript 2.x changelog and "What's New" documentation for all breaking changes. Update CoffeeScript source code to adhere to the new semantics, particularly for loops, class inheritance, and function returns. Ensure your build pipeline can handle ES2015+ output if targeting older environments.
• gotcha Despite its compiler producing modern JavaScript, integrating CoffeeScript into contemporary JavaScript build toolchains (like Webpack, Rollup, Vite, or even Babel for further transpilation) can be challenging without specific loaders or plugins. The `.coffee` extension is not natively understood by most JS tools.
  Fix: Use appropriate loaders (e.g., `coffee-loader` for Webpack) or pre-processing steps in your build configuration to compile `.coffee` files to `.js` before they are processed by other tools. If using the `--transpile` option with CoffeeScript's CLI, ensure `@babel/core` and necessary Babel presets/plugins are installed and configured.
• gotcha CoffeeScript is in maintenance mode with slower development compared to its peak popularity. While still functional, relying on it for new projects might lead to challenges in finding extensive community support, up-to-date tooling integrations, or rapid feature development that keeps pace with JavaScript.
  Fix: Evaluate the long-term implications for project maintainability and developer onboarding. Consider using TypeScript or modern JavaScript directly for new projects if strong community support and active development are critical. For existing CoffeeScript projects, ensure internal expertise is maintained.
• breaking CoffeeScript 2.3 introduced output that uses object spread syntax (`...`) in object literals, which was not universally supported in all browsers (e.g., Edge, Safari) or environments (e.g., React Native's JS engine) at the time of its release. This could lead to runtime errors if the compiled output was not further transpiled.
  Fix: If targeting environments without full object spread support, either downgrade CoffeeScript to a version prior to 2.3 or ensure the compiled JavaScript is passed through Babel with `@babel/preset-env` to transpile down to a compatible syntax. The `--transpile` option on the `coffee` CLI can help with this.

Install

• npm install coffeescript npm
• yarn add coffeescript yarn
• pnpm add coffeescript pnpm

Imports

• CoffeeScript
  wrong:

  import CoffeeScript from 'coffeescript';

  correct:

  import * as CoffeeScript from 'coffeescript';

  The `coffeescript` package is a CommonJS module that exports an object. For ESM, `import * as CoffeeScript` is the correct way to import the entire module as a namespace object. Direct `import CoffeeScript from 'coffeescript'` might result in the entire module object being assigned as the default export in some environments, but `* as` is more explicit for CJS interop.
• compile
  wrong:

  const { compile } = require('coffeescript');

  correct:

  import { compile } from 'coffeescript';

  As of CoffeeScript 2.7.0, the package officially supports named ES module exports when used in Node.js, meaning `import { compile } from 'coffeescript'` now works. Prior to this, programmatic access was typically via `CoffeeScript.compile` from a default import or CommonJS `require`.
• CompileOptions

  import type { CompileOptions } from 'coffeescript';

  For TypeScript users, type definitions are available via `@types/coffeescript` which needs to be installed separately. The `CompileOptions` interface defines parameters for the `compile` function.
• CoffeeScript (CJS)
  wrong:

  import CoffeeScript from 'coffeescript';

  correct:

  const CoffeeScript = require('coffeescript');

  This is the standard CommonJS import pattern for Node.js environments. The package is primarily a CJS module. Trying to use `import` syntax without a transpiler or Node.js ESM configuration will lead to errors.

Quickstart

Demonstrates programmatic compilation of a CoffeeScript string into JavaScript using the `compile` function, including a class definition and a loop.

import { compile } from 'coffeescript';

const coffeeCode = `
# A simple CoffeeScript example
square = (x) -> x * x

numbers = [1, 2, 3]

for num in numbers
  console.log "The square of #{num} is #{square num}"

class Animal
  constructor: (@name) ->
  move: (meters) ->
    console.log @name, "moved #{meters}m."

cat = new Animal "Cat"
cat.move 5
`;

try {
  const jsCode = compile(coffeeCode, { bare: true });
  console.log('--- CoffeeScript Input ---');
  console.log(coffeeCode);
  console.log('\n--- Compiled JavaScript Output ---');
  console.log(jsCode);
} catch (error) {
  console.error('Compilation Error:', error.message);
}