node-elm-compiler

5.0.6 verified Fri May 01 auth: no javascript

Node.js interface to compile Elm 0.19 sources using the official Elm compiler binaries. Current stable version 5.0.6. Provides a programmatic API for compiling Elm files to JavaScript or HTML, finding module dependencies, and reporting compile errors. Key differentiators: wraps the Elm binary, supports sync and async compilation, debug and optimize modes, and respects the elm.json configuration. Notably, requires Elm itself to be installed separately and handles version-specific flags for Elm 0.19.

Common errors

error Cannot find module 'node-elm-compiler' ↓

cause Package not installed or version incompatible

fix

Run 'npm install node-elm-compiler' and ensure your package.json includes it.

error ERR_REQUIRE_ESM: require() of ES Module not supported ↓

cause Using require() with ESM-only version 5.x

fix

Switch to import syntax, or update to a legacy version (4.x) if you must use require.

error Error: Compilation failed: The file MyFile.elm does not exist. ↓

cause The provided path to the Elm source file is incorrect

fix

Verify the file path; use absolute paths or ensure relative paths are resolved correctly.

error Command failed: elm make ... No such file or directory ↓

cause Elm binary not found or not installed

fix

Install Elm globally or specify correct 'pathToMake' option.

Warnings

breaking v5.0.0 removed the 'yes' option and changed error handling to throw exceptions instead of emitting warnings or using process.exit. ↓

fix Remove 'yes' from options and adapt error handling to use try/catch.

deprecated The 'warn' and 'pathToMake' flags are obsolete and will result in helpful errors. ↓

fix Instead of using 'warn', rely on compiler output; for 'pathToMake', ensure elm binary is on PATH or use the correct path.

gotcha Requires Elm compiler (elm binary) to be installed separately; this package only wraps it. ↓

fix Install Elm e.g. via npm: 'npm install -g elm' or have elm on your PATH.

gotcha ESM-only from v5.0.0; CommonJS require will fail with 'ERR_REQUIRE_ESM'. ↓

fix Use import syntax or set "type": "module" in package.json. Consider using dynamic import() as fallback.

Install

npm install node-elm-compiler

yarn add node-elm-compiler

pnpm add node-elm-compiler

Imports

compile

wrong

const nodeElmCompiler = require('node-elm-compiler'); nodeElmCompiler.compile()

correct

import { compile } from 'node-elm-compiler'

ESM since v5. Named export.

compileToString

wrong

import nodeElmCompiler from 'node-elm-compiler'; nodeElmCompiler.compileToString()

correct

import { compileToString } from 'node-elm-compiler'

ESM named export. Returns compiled JavaScript as string.

findAllDependencies

wrong

const findAllDependencies = require('node-elm-compiler').findAllDependencies

correct

import { findAllDependencies } from 'node-elm-compiler'

ESM named export. Accepts array of module names.

compileSync

wrong

import { compile } from 'node-elm-compiler'; compile.sync()

correct

import { compileSync } from 'node-elm-compiler'

ESM named export. Synchronous version added in v4.3.0.

Quickstart

Demonstrates async compilation of an Elm source file to a JavaScript string using named import and options object.

import { compileToString } from 'node-elm-compiler';
import path from 'path';

const elmSource = path.resolve('src/Main.elm');

async function build() {
  try {
    const jsString = await compileToString([elmSource], {
      optimize: false,
      debug: false,
      cwd: process.cwd(),
      pathToMake: '' // uses system PATH
    });
    console.log('Compiled output length:', jsString.length);
    // write to file etc.
  } catch (err) {
    console.error('Compilation failed:', err.message);
  }
}

build();