esbuild-plugin-purescript

1.1.1 verified Fri May 01 auth: no javascript

An esbuild plugin that allows importing PureScript (.purs) files directly in JavaScript/TypeScript bundles. Version 1.1.1. It resolves PureScript modules by pointing esbuild to the compiled output directory (default: './output'). Does not run 'spago build' or tree-shake with zephyr; users must precompile PureScript separately. Minimal zero-config setup with source globs.

Common errors

error Error: Cannot find module 'esbuild-plugin-purescript' ↓

cause Package not installed or missing from node_modules.

fix

Run 'npm install esbuild-plugin-purescript'.

error TypeError: PurescriptPlugin is not a function ↓

cause Incorrect import style (e.g., named import instead of default).

fix

Use 'import PurescriptPlugin from 'esbuild-plugin-purescript'' or '{ default: PurescriptPlugin }'.

error ENOENT: no such file or directory, open '.../output/...' ↓

cause PureScript output directory missing or incorrect path.

fix

Run 'spago build' first and verify output paths.

Warnings

gotcha Plugin does not compile PureScript; expects pre-compiled output directory. Missing build step causes runtime errors. ↓

fix Run 'spago build' or 'purs compile' before esbuild.

gotcha Default 'sources' glob uses 'spago sources' which may include dist or test files incorrectly. ↓

fix Explicitly set 'sources' to a narrow glob matching your source files.

gotcha Plugin does not tree-shake PureScript output; bundles all modules from output directory. ↓

fix Use zephyr for tree-shaking or manually trim output.

gotcha Plugin uses dynamic require() internally; may fail in ESM-only esbuild environments. ↓

fix Ensure esbuild is in CommonJS mode or use 'await import()' workaround.

Install

npm install esbuild-plugin-purescript

yarn add esbuild-plugin-purescript

pnpm add esbuild-plugin-purescript

Imports

default

wrong

const PurescriptPlugin = require('esbuild-plugin-purescript')

correct

import PurescriptPlugin from 'esbuild-plugin-purescript'

Package is ESM-only; CommonJS require will fail.

PurescriptPlugin (named)

wrong

import { purescriptPlugin } from 'esbuild-plugin-purescript'

correct

import { PurescriptPlugin } from 'esbuild-plugin-purescript'

Named export is PascalCase; wrong casing (camelCase or lowercase) leads to undefined.

PurescriptPlugin (CommonJS)

wrong

const PurescriptPlugin = require('esbuild-plugin-purescript')

correct

const PurescriptPlugin = (await import('esbuild-plugin-purescript')).default

Use dynamic import in CommonJS to access default export.

Quickstart

Registers the plugin with esbuild, specifying PureScript output directory and source globs.

import esbuild from 'esbuild';
import PurescriptPlugin from 'esbuild-plugin-purescript';
import { resolve } from 'path';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    PurescriptPlugin({
      output: resolve(process.cwd(), 'output'),
      sources: ['src/**/*.purs'],
    }),
  ],
}).catch(() => process.exit(1));