PureScript FFI boundary design when migrating JavaScript modules incrementally

Short answer

There is no compiler check that a foreign import signature matches its JavaScript, so the established pattern is not a versioning mechanism but a discipline: keep each FFI module a thin alias layer, co-locate the .purs and .js files so they change in the same commit, and back every import with a contract test that runs against the real JavaScript in CI. Expose Effect directly for now, and make the public API a safe PureScript wrapper module rather than the raw FFI module, so you can tighten effect rows later without breaking callers.

Validating declarations against drifting JavaScript

What is confirmed: spago and the 0.15.x compiler typecheck the .purs side only. The accompanying .js FFI file is not typechecked at all — a syntax error there surfaces at bundle time or runtime. What follows is the standard mitigation, not a built-in feature.

• Thin, boring FFI modules. Each foreign import should be a direct alias to one exported JS function, with no logic. All marshalling — converting Nullable/Undefined and raw records into ADTs — lives in a separate PureScript wrapper module. The untrustworthy surface is then one small file per JS module.
• Contract tests as drift detection. Write one test per foreign import (with spec or similar) that calls it with representative inputs and asserts on outputs, run via spago test against the real JS modules. Verify the setup works by deliberately breaking one signature and confirming the suite fails. This turns runtime drift into a CI failure.
• Social versioning. Keep Foo.purs and Foo.js in the same directory, require both to change in the same PR, and put a header comment in the JS file listing its exported signatures as the source of truth. Also lint/build the JS side in CI, since the compiler never sees it.

Effect now, or a custom effect row?

Use Effect. A bespoke effect label that nothing interprets adds noise while permitting exactly the same runtime behavior. The migration-safe move is structural, not type-level: because callers depend on your wrapper functions rather than the raw imports, you can later introduce a constrained row (e.g. a LEGACY or DOM label) behind those wrappers without changing call sites. Only invest in a custom row if you genuinely plan to interpret or restrict effects.

Dual-import pitfalls in one bundle

Importing the same JS module through the FFI and directly from legacy code is generally safe: bundlers like esbuild and webpack deduplicate ES modules resolved to the same file path, so both sides share module-level state — usually what you want mid-migration. Two real pitfalls:

• Split instances. Aliasing, symlinks, or dual CJS/ESM entry points can make the bundler emit two live copies of the module, silently splitting state. Check the bundle or bundler stats to confirm the shared module appears exactly once.
• Shared mutable references. PureScript code assumes immutability. If a wrapped function returns an object the legacy side later mutates, you get hard-to-trace bugs. Clone or freeze such values at the boundary; you can verify this by temporarily mutating inside a wrapped JS function and confirming the mutation does not leak into PureScript-held values.

One caveat to flag for review: foreign import data types carry no runtime representation guarantee, so if the JS side renames a field, PureScript record access fails only when that code path executes — another reason the contract tests should exercise real shapes, not just happy paths.