package js_of_ocaml

You can search for identifiers within the package.

in-package search v0.2.0

On This Page

General options
Debugging
Target environment
Effect handlers
Source maps
Pseudo filesystem
Environment variables
1. Resolution order
2. Browser example
Toplevel and dynamic linking
Compilation modes
Optimizations
1. Optimization profiles
2. Recommended settings
Enable/Disable options
Compiler parameters
Warnings
Debug output
Subcommands

Js_of_ocaml

Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Command-line options

This page documents the command-line options for the js_of_ocaml compiler. Most of these options also apply to wasm_of_ocaml. Differences are noted where applicable.

General options

Option	Description
`--version`	Display the compiler version
`-o <file>`	Set output filename
`--opt {1,2,3}`	Set optimization profile (default: 1). See Optimizations
`--enable <opt>`	Enable option. See Enable/Disable options
`--disable <opt>`	Disable option. See Enable/Disable options
`-I <dir>`	Add directory to the list of include directories

Debugging

Option	Description
`--pretty`	Pretty print JavaScript output, preserve OCaml variable names
`--no-inline`	Disable code inlining
`--debug-info`	Output debug information (source locations)
`--source-map`	Generate source map. See Source maps

Target environment

Option	Description
`--target-env <env>`	Build for target environment (default: `isomorphic`)

Possible values:

isomorphic - Runs in both browser and Node.js (default)
browser - Browser-specific, smaller output
nodejs - Node.js-specific, smaller output

Effect handlers

Option	Description
`--effects <mode>`	Select effect handler implementation

For js_of_ocaml (default: disabled):

disabled - No effect handler support (default)
cps - CPS transformation for effect support
double-translation - Keep both direct and CPS versions; choose at runtime

For wasm_of_ocaml (default: jspi):

jspi - JavaScript-Promise Integration (default). Available in Chrome 137, Node.js 25, and higher. Use cps for other browsers. Performing effects is slower than with cps.
cps - CPS transformation for effect support
native - WebAssembly stack switching (wasm_of_ocaml only). Available, behind the --experimental-wasm-wasmfx flag, in Chrome 148 or higher, or in a recent Node.js canary release (V8 version 14.7.100 or higher).
disabled - No effect handler support

See Effect handlers for details.

Source maps

Option	Description
`--source-map`	Generate source map (separate file)
`--no-source-map`	Don't generate source map
`--source-map-inline`	Inline source map in the JavaScript output
`--source-map-no-source`	Don't embed source code in source map
`--source-map-root <dir>`	Set root directory for source map paths

Pseudo filesystem

Js_of_ocaml provides a pseudo filesystem for programs that read files at runtime. The --file flag is also supported by wasm_of_ocaml.

Option	Description
`--file <file>[:<target>]`	Register file to pseudo filesystem (default target: `/static/`)
`--ofs <file>`	Write filesystem data to separate file (js_of_ocaml only)
`--extern-fs`	Allow registering files from outside at runtime (default, js_of_ocaml only)
`--no-extern-fs`	Only allow files embedded at compile time (js_of_ocaml only)

Environment variables

Option	Description
`--setenv <VAR>=<value>`	Set environment variable at compile time

Resolution order

When OCaml code calls Sys.getenv, js_of_ocaml resolves variables in this order:

If the variable was set at compile time with --setenv VAR=value, return it
If running in Node.js, check process.env
Check globalThis.jsoo_env (useful for setting variables in browsers)
Raise Not_found

Browser example

// Set environment variables before loading the OCaml program
globalThis.jsoo_env = {
  DEBUG: "true",
  API_URL: "https://api.example.com"
};

Toplevel and dynamic linking

Option	Description
`--toplevel`	Compile an OCaml toplevel (embeds necessary .cmi files)
`--no-cmis`	Don't include .cmi files in toplevel
`--dynlink`	Enable dynamic linking of bytecode
`--export <file>`	File listing units to export for toplevel/dynlink
`--linkall`	Link all compilation units and primitives

See Building a toplevel for details.

Compilation modes

Option	Description
`--noruntime`	Don't include the standard runtime
`--include-runtime`	Include partial runtime when compiling .cmo/.cma
`--keep-unit-names`	Preserve unit names (for separate compilation)
`--wrap-with-fun[=<name>]`	Wrap output in a function (default: IIFE)
`--custom-header <text>`	Add custom header (e.g., `#!/usr/bin/env node`)

See Compilation modes for details.

Optimizations

Optimization profiles

Use --opt <level> to select a profile:

--opt 1 - Basic optimizations (default)
--opt 2 - Standard optimizations
--opt 3 - Maximum optimizations (iterates until fix-point)

Recommended settings

For debugging:

js_of_ocaml --pretty --no-inline program.byte

For production:

js_of_ocaml --opt 3 program.byte

Enable/Disable options

Use --enable <opt> or --disable <opt> to control these flags:

Output formatting

Option	Default	Description
`pretty`	false	Pretty print JavaScript output
`shortvar`	true	Use short variable names
`strict`	true	Generate "use strict"
`header`	true	Include compiler version header
`es6`	false	Generate ES6 syntax

Optimizations

Option	Default	Description
`deadcode`	true	Dead code elimination
`globaldeadcode`	true	Global dead code elimination
`inline`	true	Function inlining
`staticeval`	true	Static evaluation of constants
`share`	true	Share string and number constants
`optcall`	true	JavaScript call optimizations
`constant-sinking`	true	Move constant declarations closer to usage sites
`var-coalescing`	true	Coalesce JavaScript variables with disjoint lifespans

Runtime behavior

Option	Default	Description
`effects`	false	Enable effect handlers
`excwrap`	true	Wrap JavaScript exceptions in OCaml exceptions
`with-js-error`	false	Attach JavaScript stack traces to OCaml exceptions
`debugger`	true	Keep `debugger` statements (stripped if false)
`genprim`	true	Generate dummy primitives when missing
`use-js-string`	true	Use JavaScript strings internally

Internal debugging

Option	Default	Description
`debuginfo`	false	Include source location comments
`stable_var`	false	Use stable (predictable) variable names
`auto-link`	true	link required compilation units only

Compiler parameters

Use --set <param>=<value> to tune compiler behavior:

Parameter	Default	Description
`switch_size`	60	Max cases before switch becomes if-else chain
`inlining-limit`	150	Size threshold for function inlining
`tc_depth`	50	Max tail-call depth before trampoline
`tc`	trampoline	Tail-call mode: `trampoline` or `none`

Warnings

Option	Description
`--quiet` / `-q`	Suppress non-error messages
`--Werror`	Treat warnings as errors
`-w <warning>`	Enable warning
`-w no-<warning>`	Disable warning

Available warnings:

Warning	Default	Description
`missing-primitive`	on	Missing JavaScript primitive implementation
`missing-cmi`	on	Missing .cmi file
`missing-deps`	on	Missing dependencies
`missing-effects-backend`	on	Using effects, but not backend was selected
`integer-overflow`	on	Integer overflow in constant
`overriding-primitive`	on	Overriding an existing primitive
`deprecated-primitive`	on	Using deprecated primitive
`free-variables`	on	Free variables in primitive code

Debug output

Use --debug <section> to enable debug output for compiler internals:

times, stats, deadcode, globaldeadcode, inlining, constant-sinking, gen, linker, sourcemap, flow, parser, var-coalescing

Subcommands

The js_of_ocaml command has several subcommands:

Command	Description
`js_of_ocaml compile`	Compile bytecode to JavaScript (default)
`js_of_ocaml link`	Link JavaScript files together
`js_of_ocaml build-runtime`	Build standalone runtime
`js_of_ocaml build-fs`	Build pseudo filesystem

The wasm_of_ocaml command has similar subcommands:

Command	Description
`wasm_of_ocaml compile`	Compile bytecode to WebAssembly (default)
`wasm_of_ocaml link`	Link files together
`wasm_of_ocaml build-runtime`	Build standalone runtime

Link command

js_of_ocaml link -o output.js runtime.js lib1.js lib2.js main.js

Additional options:

Option	Description
`-a`	Build a library (.cma.js)
`--resolve-sourcemap-url`	Resolve source map URLs

Build-runtime command

js_of_ocaml build-runtime -o runtime.js

Accepts the same --enable/--disable options as the main command.

Build-fs command

js_of_ocaml build-fs -o fs.js file1.txt file2.dat

Builds a JavaScript file containing filesystem data.