# Elide for Node users

> What works unchanged, which commands change, and how Elide compares with Node.js.

Elide runs Node programs, `node:*` modules and npm packages; this page lists what changes when you switch.

## Run the same code

```bash
elide app.js                    # or: elide run app.js
elide app.ts                    # no compile step, no tsconfig.json
elide install --ecosystems=npm  # dependencies from package.json
elide test                      # node:test files
```

- `node:fs`, `node:http`, `node:worker_threads` and most other built-ins load with or without the `node:` prefix.
- CommonJS and ES modules both work.
- Tests written with `node:test` and `node:assert` run under `elide test`.
- `http.createServer` serves as in Node. A module that default-exports a `fetch` handler, or calls
  `Elide.serve({ fetch })`, also serves.

Start with [JavaScript and TypeScript](https://elide.help/docs/web). Module status is in the [API Overview](https://elide.help/docs/api-overview); suite
results are in the [Compatibility Matrix](https://elide.help/docs/compatibility).

## What changes

| Node | Elide |
| --- | --- |
| `node app.js` | `elide app.js` |
| `npm install` | `elide install --ecosystems=npm`; plain `elide install` skips npm |
| `package-lock.json` | `aube-lock.yaml` |
| `npm run build` | `elide run build` |
| `npx tool` | `elide run tool` for a tool in `node_modules/.bin`; no download-and-run |
| `node --test` | `elide test` |
| `node --inspect app.js` | `elide run --debugger=cdp app.js` |
| `node --watch app.js` | No equivalent |
| `node --env-file=.env app.js` | Call `process.loadEnvFile()` in code |
| `node --permission --allow-fs-read=.` | `elide --allow-read=. app.js`; see [Sandbox and Limits](https://elide.help/docs/sandbox) |
| `node:worker_threads` | Same module; `new Worker` honors only `workerData`, `eval`, `transferList` and `env` |
| `node:sqlite` `DatabaseSync` | `Database` from `elide:sqlite`; see [Database modules](https://elide.help/docs/api-database) |

Elide does not set `NODE_ENV`.

## Benchmarks

Startup: `hyperfine -N -w 10` on a 24-core Linux workstation, running a hello-world script.

| Runtime | Command | Mean |
| --- | --- | --- |
| Node | `node hello.js` | 11.4 ± 0.8 ms |
| Elide | `elide run hello.js` | 2.1 ± 0.1 ms |
| Bun | `bun hello.js` | 1.8 ± 0.2 ms |
| Deno | `deno run hello.js` | 6.1 ± 0.3 ms |

Bun starts faster than Elide.

Serving: `wrk -t12 -c256 -d10s` against a hello-world server. Each server ran on the same 24 CPUs and `wrk` on 24
others.

| Runtime | Requests/s | Mean latency |
| --- | --- | --- |
| Node | 91,464 | 3.22 ms |
| Elide | 600,352 | 419 µs |
| Bun | 147,742 | 1.70 ms |
| Deno | 280,666 | 0.89 ms |

Every server ran with its defaults: Node, Bun and Deno serve on one thread, Elide on several. This compares
defaults, not tuned deployments.

## Strengths

- Starts a hello-world script in 2.1 ms against Node's 11.4 ms.
- Runs `.ts`, `.mts` and `.cts` files directly, with no build step or `tsconfig.json`.
- Served 600,352 requests per second against Node's 91,464, both with default settings.
- Scopes network access by host and subprocesses by command: `--allow-net=api.example.com`, `--allow-run=git`.
- Limits workers, open files, heap and run time: `--limit=workers=4`, `--limit=fds=128`, `--max-mem=512m`,
  `--timeout=30s`.
- Includes SQLite, PostgreSQL and MySQL drivers as `elide:sqlite`, `elide:postgres` and `elide:mysql`.

## Weaknesses

- Node-API compatibility is 86.8% and WinterTC 95.9% on their test suites.
- `node:http2`, `node:cluster`, `node:inspector` and `node:wasi` throw `ERR_UNKNOWN_BUILTIN_MODULE`.
- `https.createServer` throws `ERR_HTTPS_SERVER_UNSUPPORTED`; terminate TLS in front of `http.createServer`.
- No download-and-run like `npx`, no `--watch` or `--env-file`, and no `WebSocket` global.
- No bundler: `elide web build` transforms each file and keeps its imports.
- No macOS Intel build; macOS releases are Apple Silicon only.

## Next steps

- [Installation](https://elide.help/docs/installation)
- [JavaScript and TypeScript](https://elide.help/docs/web)
- [Sandbox and Limits](https://elide.help/docs/sandbox)