fable-splitter

2.2.1 verified Fri May 01 auth: no javascript

File splitter for Fable, the F# to JavaScript compiler. This package provides a CLI and JS API to compile F# files into individual JavaScript modules. Current stable version is 2.2.1 (with Fable 5.x in release candidate). It relies on fable-compiler (peer dependency ^2.5.1) for actual compilation. Key differentiators: supports Fable 2.1+ direct invocation (no need for dotnet-fable), offers watch mode, Babel integration, and path resolution macros. Not to be confused with fable-compiler itself; fable-splitter handles file splitting and output management.

Common errors

error Cannot find module 'fable-compiler' ↓

cause fable-compiler is a peer dependency and must be installed separately.

fix

Run npm install fable-compiler alongside fable-splitter.

error TypeError: run is not a function ↓

cause Importing using ESM syntax (import) instead of CommonJS require.

fix

Use const { run } = require('fable-splitter') instead of import { run } from 'fable-splitter'.

error Error: Unknown command: fable-splitter ↓

cause Attempting to run `dotnet fable fable-splitter` with Fable 2.1+.

fix

Call npx fable-splitter directly; the dotnet-fable CLI is no longer needed.

error SyntaxError: Unexpected token 'export' ↓

cause Running a Fable-compiled file that uses ES module syntax in a Node.js environment without CommonJS.

fix

Add --commonjs flag or configure Babel to transform modules to CommonJS.

Warnings

breaking In Fable 2.0, fable-splitter was called via dotnet-fable (e.g. `dotnet fable fable-splitter`). Starting from Fable 2.1, call fable-splitter directly (e.g. `npx fable-splitter`). ↓

fix Upgrade fable-compiler to >=2.1.0 and call `npx fable-splitter` directly.

deprecated Fable 5.x is in release candidate; fable-splitter may be replaced or significantly changed. Check Fable 5 migration guide. ↓

fix Stay on fable-splitter 2.x for stable releases, or migrate to Fable 5's built-in CLI when stable.

gotcha The `--commonjs` flag is required if you want CommonJS module output; otherwise, Fable outputs ES modules by default. ↓

fix Add `--commonjs` to CLI or set `modules: 'commonjs'` in Babel config.

gotcha Path resolution macros `${entryDir}` and `${outDir}` are only replaced in string literals, not in variables or interpolated strings. ↓

fix Use `${entryDir}` directly in F# string literals, not in runtime string concatenation.

Install

npm install fable-splitter

yarn add fable-splitter

pnpm add fable-splitter

Imports

default

wrong

import splitter from 'fable-splitter'

correct

const splitter = require('fable-splitter')

fable-splitter is CommonJS only; ESM import not supported.

run

wrong

import { run } from 'fable-splitter'

correct

const { run } = require('fable-splitter')

run is a named export in CommonJS; ESM import will fail.

getConfig

wrong

import { getConfig } from 'fable-splitter'

correct

const { getConfig } = require('fable-splitter')

getConfig is another named export; use destructuring require.

Quickstart

Shows how to programmatically compile an F# project using fable-splitter's JS API with Babel configuration.

const { run } = require('fable-splitter');

const config = {
  entry: 'src/App.fsproj',
  outDir: 'out',
  babel: {
    presets: [['@babel/preset-env', { modules: 'commonjs' }]]
  },
  allFiles: false,
  fable: {
    define: ['DEBUG'],
    typedArrays: true,
    clampByteArrays: false
  },
  onCompiled: () => console.log('Done!')
};

run(config).catch(err => console.error(err));