coffee-loader

5.0.0 verified Mon Apr 27 auth: no javascript

Webpack loader that compiles CoffeeScript (>=2.0.0) to JavaScript. Current stable version is 5.0.0 (January 2024). Maintained by webpack-contrib under the webpack ecosystem. Active development, follows semver with major bumps for Node.js version increases. Key differentiators: official webpack loader, seamless integration with webpack's module system, supports CoffeeScript's `transpile` option for Babel integration, and respects `compiler.devtool` for source maps.

Common errors

error Module not found: Error: Can't resolve 'coffee-script' in ... ↓

cause Missing or incorrect CoffeeScript package name; coffee-loader expects 'coffeescript' (not 'coffee-script').

fix

Run npm install --save-dev coffeescript and ensure it's in node_modules.

error Error: No valid options for coffee-loader, check 'bare', 'transpile', etc. ↓

cause Invalid options object passed to coffee-loader.

fix

Check documentation for allowed options; common mistake: using 'sourceMap' directly instead of relying on devtool.

error ValidationError: Invalid options object. Coffee Loader has been initialized using an options object that does not match the API schema. ↓

cause Misspelled option names or incorrect type.

fix

Refer to schema-utils validation messages; typical issue: 'transpile' must be an object, not a string.

error Error: You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. ↓

cause Webpack rule for .coffee files is missing or incorrect.

fix

Add { test: /\.coffee$/, use: 'coffee-loader' } to module.rules.

Warnings

breaking Node.js version <18.12.0 is no longer supported in v5.0.0 ↓

fix Upgrade Node.js to >=18.12.0.

breaking Webpack 4 and below require older versions of coffee-loader (v1.x or below). ↓

fix Use coffee-loader v1.x for webpack 4, or upgrade to webpack 5.

gotcha CoffeeScript 2+ required; v5.0.0 does not support CoffeeScript 1.x. ↓

fix Install coffeescript@^2.0.0.

gotcha Default option `bare` is `true`, which omits the top-level function wrapper. This may break variable scope if not expected. ↓

fix Set `options.bare: false` if you need the wrapper.

deprecated The `transpile` option is still supported but Babel is now the recommended transpiler. ↓

fix Use Babel presets with `transpile` option or configure Babel in webpack separately.

Install

npm install coffee-loader

yarn add coffee-loader

pnpm add coffee-loader

Imports

coffee-loader

wrong

const loader = require('coffee-loader')

correct

module.exports = { module: { rules: [ { test: /\.coffee$/, loader: 'coffee-loader' } ] } }

Used as webpack loader string, not directly imported.

import coffee from 'coffee-loader!./file.coffee'
wrong
```
import coffee from './file.coffee'
```
correct
```
import coffee from 'coffee-loader!./file.coffee'
```
Inline loader syntax for specific imports.

options

wrong

options: { sourceMap: true }

correct

options: { bare: true, transpile: { presets: ['@babel/env'] } }

sourceMap is derived from devtool; do not set explicitly unless overriding.

Quickstart

Basic webpack configuration to compile CoffeeScript files using coffee-loader.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.coffee$/,
        loader: 'coffee-loader',
        options: {
          bare: true,
        },
      },
    ],
  },
};

// file.coffee
square = (x) -> x * x

// Run: npx webpack