# Installation

> Build the nstd executable from source and check that it works.

There is no download yet. No prebuilt nstd binary is published, so for now you
build it from source. (The [`nstdlib`](https://www.npmjs.com/package/nstdlib)
package on npm is the standard library on its own, not this executable.)

## What you need

- **[Zig](https://ziglang.org/) 0.16.0.** This exact version is required.
- **Node.js 26.10.0**, the version in the repository's `.nvmrc`. The build
  reads details out of the Node it runs under, so a different version produces
  a broken build without warning. If your default `node` is another version,
  install a matching one and use it for these steps.
- **[pnpm](https://pnpm.io/)**, through Corepack. Running `corepack enable` is
  enough if you don't already have it.
- **Git**, which the setup step uses to download Node's source code.

## Build from source

Clone the repository:

```sh
git clone https://github.com/unjs/nstd.git
cd nstd
```

Install dependencies and download Node's source, which the build reads from:

```sh
corepack enable
pnpm install
pnpm setup:node
```

`pnpm setup:node` fetches only the parts of Node's source the build needs
(about 136 MB) into `./node`. Running it again does nothing once it's up to
date.

Build the standard library. This produces `./dist`, which gets embedded into
the executable:

```sh
pnpm build
```

Then build the executable itself:

```sh
pnpm --filter nstdlib-native build
```

The finished binary is at `native/zig-out/bin/nstd`.

> [!TIP]
> Use the pnpm script rather than running `zig build` directly. A plain
> `zig build` produces an unoptimized debug binary, which is only useful when
> you're tracking down a crash inside the Zig host.

## Check that it works

```sh
./native/zig-out/bin/nstd -e 'console.log(1 + 1)'
./native/zig-out/bin/nstd --print-realm
```

The first command should print `2`. The second lists the Node builtin modules
(`fs`, `http`, `path` and so on) that loaded in this build. Every one of them
should be listed as available, with none missing.

Now try one of your own scripts:

```sh
./native/zig-out/bin/nstd my-script.js
```

## Build for WebAssembly (WASI)

You can also build nstd as a WebAssembly module. It boots the same standard
library as the native build:

```sh
pnpm --filter nstdlib-native build:wasm
```

This produces `native/zig-out/bin/nstd.wasm`, which runs under any
WASI-compatible runtime, such as `wasmtime`:

```sh
wasmtime native/zig-out/bin/nstd.wasm -- --print-realm
```

A few things behave differently in this build:

- **There is no outside network.** WASI has no sockets, so `net` and `http`
  run on an in-memory network inside the program instead. A server and a
  client in the same program can talk to each other, but connecting to any
  other address fails with `ECONNREFUSED`, and hostname lookups fail too.
- **`fs.watch()` doesn't work.** It needs Linux's `inotify`, so it throws.
  The error code currently reads `UNKNOWN` rather than `ENOSYS`, because
  WASI numbers its errors differently from Linux.

Everything else works the same as in the native build.

The WASI build is also a step toward running nstd in a browser, though not
the final form of it. Exiting the process, waiting for events and file access
still assume a WASI host and will need browser versions.

## Next steps

Once you have a working binary, [Running Code](/runtime/running-code) shows how to use
it, and [CLI Options](/runtime/cli) lists every flag it accepts.