Compatibility

What works in the Flux runtime, and how to check your code before running.

The runtime model

Flux runs your TypeScript and JavaScript in a Deno V8 isolate. It intercepts all external IO (Postgres, HTTP, TCP, Redis, timers) so it can record and replay them deterministically.

This means:

• Standard Web APIs (fetch, URL, crypto, TextEncoder etc.) — ✓ supported
• TypeScript/ESM imports — ✓ supported
• npm packages (via npm: specifiers) — ✓ supported with caveats
• Node.js built-ins (node:fs, node:http, etc.) — ✗ not supported
• Browser-only globals (window, document, localStorage) — ✗ not available

flux check

Run flux check to scan your project for compatibility issues before deploying.

$ flux check index.ts

  checked   /Users/me/my-app/index.ts
  modules   12
  artifact  a3f9c8...

# With an error:
  error [node_import] index.ts: node: imports are not supported: node:crypto

# Clean:
  checked   /Users/me/my-app/index.ts
  modules   8
  artifact  b7d12e...

Flag	Description
[ENTRY]	Entry file to check (auto-detected if omitted)

Diagnostic codes

Errors block the dev/run/replay commands. Warnings are informational.

Errors

Code	Cause	Fix
node_import	Your code imports a node: built-in (node:fs, node:crypto, etc.)	Use the Web API equivalent: crypto.subtle instead of node:crypto, fetch instead of node:http
unsupported_import	An import specifier couldn't be resolved	Check the import path is valid; use npm: prefix for npm packages
load_failed	A module file couldn't be read or fetched	Check the file exists and the path is correct
parse_failed	Syntax error or unsupported JS/TS syntax	Fix the syntax error in the indicated file

Warnings

Warnings don't block execution but indicate patterns that may behave unexpectedly.

Code	Globals detected	Note
unsupported_global	Buffer, process, __dirname, __filename, global	Node.js globals — not available in Deno V8. Use Web API equivalents or avoid them.
unsupported_web_api	window, document, navigator, localStorage, sessionStorage, Worker	Browser-only APIs — not available in the server runtime.

npm packages

Use npm: prefix in imports or add packages via flux add:

# Add packages to deno.json
$ flux add hono zod

  adding   hono as npm:hono
  adding   zod as npm:zod
  updated  /Users/me/my-app/deno.json

# Or import directly
$ cat index.ts
import { Hono } from 'npm:hono'
import { z } from 'npm:zod'

flux check analyses every npm package in your dependency tree and reports:

• Compatible — no problematic patterns found
• Warning — uses Node.js globals or browser APIs (detected via source scan)
• Incompatible — uses node: imports internally

Known compatible packages

Package	Use case
hono	HTTP routing — the recommended framework
zod	Input validation and schema parsing
flux:pg	Built-in Postgres client (no npm needed)

flux:pg — built-in Postgres

Use flux:pg to connect to Postgres. It's built into the runtime — no npm package required, and all queries are recorded as checkpoints for replay.

import { connect } from 'flux:pg'

const db = await connect(Deno.env.get('DATABASE_URL')!)

const rows = await db.query('SELECT * FROM orders WHERE id = $1', [id])

Supported Web APIs

The Flux runtime is based on Deno, which supports the Deno Web API surface. Key APIs that work:

API	Notes
fetch	Recorded as an HTTP checkpoint — works and replays
crypto.subtle	Web Crypto — use instead of node:crypto
TextEncoder / TextDecoder	Fully supported
URL / URLSearchParams	Fully supported
ReadableStream / WritableStream	Supported
setTimeout / setInterval	Recorded as TIMER checkpoints — replays use recorded delay
Deno.env.get()	Read environment variables

Example: replacing Node.js patterns

// ✗ Node.js — won't work
import crypto from 'node:crypto'
const id = crypto.randomUUID()

// ✓ Web API — works in Flux
const id = crypto.randomUUID()


// ✗ Node.js — won't work
import { readFileSync } from 'node:fs'
const data = readFileSync('./file.txt', 'utf8')

// ✓ Deno — works in Flux
const data = await Deno.readTextFile('./file.txt')


// ✗ Node.js — won't work
import http from 'node:http'

// ✓ Hono + Flux — works
import { Hono } from 'npm:hono'
const app = new Hono()
app.get('/health', (c) => c.json({ ok: true }))
export default app