{"id":12712,"library":"coffeescript","title":"CoffeeScript Compiler","description":"CoffeeScript is a 'little language' that transpiles into JavaScript, aiming to provide a more concise and readable syntax inspired by Ruby. Its current stable version is 2.7.0. While once very popular, it has seen reduced adoption since the widespread introduction of ES6+ features, which brought much of CoffeeScript's syntactic sugar directly into JavaScript. The project is primarily in maintenance mode with infrequent but significant updates, targeting modern JavaScript. Key differentiators include its significant whitespace, implicit returns, and a streamlined object/array literal syntax compared to direct JavaScript. CoffeeScript maintains backward compatibility where possible while progressively aligning its output with modern JavaScript standards and targeting ES2015+. It is mainly used as a development dependency for projects that chose CoffeeScript for their source code.","status":"maintenance","version":"2.7.0","language":"javascript","source_language":"en","source_url":"git://github.com/jashkenas/coffeescript","tags":["javascript","language","coffeescript","compiler"],"install":[{"cmd":"npm install coffeescript","lang":"bash","label":"npm"},{"cmd":"yarn add coffeescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add coffeescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import CoffeeScript from 'coffeescript';","symbol":"CoffeeScript","correct":"import * as CoffeeScript from 'coffeescript';"},{"note":"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`.","wrong":"const { compile } = require('coffeescript');","symbol":"compile","correct":"import { compile } from 'coffeescript';"},{"note":"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.","symbol":"CompileOptions","correct":"import type { CompileOptions } from 'coffeescript';"},{"note":"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.","wrong":"import CoffeeScript from 'coffeescript';","symbol":"CoffeeScript (CJS)","correct":"const CoffeeScript = require('coffeescript');"}],"quickstart":{"code":"import { compile } from 'coffeescript';\n\nconst coffeeCode = `\n# A simple CoffeeScript example\nsquare = (x) -> x * x\n\nnumbers = [1, 2, 3]\n\nfor num in numbers\n  console.log \"The square of #{num} is #{square num}\"\n\nclass Animal\n  constructor: (@name) ->\n  move: (meters) ->\n    console.log @name, \"moved #{meters}m.\"\n\ncat = new Animal \"Cat\"\ncat.move 5\n`;\n\ntry {\n  const jsCode = compile(coffeeCode, { bare: true });\n  console.log('--- CoffeeScript Input ---');\n  console.log(coffeeCode);\n  console.log('\\n--- Compiled JavaScript Output ---');\n  console.log(jsCode);\n} catch (error) {\n  console.error('Compilation Error:', error.message);\n}\n","lang":"typescript","description":"Demonstrates programmatic compilation of a CoffeeScript string into JavaScript using the `compile` function, including a class definition and a loop."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.3.0 <2.7.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"The `coffeescript` package is not installed or not resolvable in the current environment.","error":"Error: Cannot find module 'coffeescript'"},{"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.","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.","error":"TypeError: (intermediate value).compile is not a function"},{"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.","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.","error":"CoffeeScript 1.x for...in loops iterate over values, but CoffeeScript 2.x for...in loops iterate over keys."}],"ecosystem":"npm"}