# Install nanoraster

Add the package, understand the native and wasm artifacts, and confirm your host is supported.

Canonical page: https://www.nanoraster.xyz/docs/install

nanoraster is one JavaScript package. It loads a different render artifact
per host: Node.js 22.13 or newer, or a browser with WebGPU enabled.

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install nanoraster
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add nanoraster
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add nanoraster
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## What gets installed [#what-gets-installed]

The package selects its render artifact at runtime; nothing needs
configuring.

| Host    | Artifact loaded                | Delivered by                    |
| ------- | ------------------------------ | ------------------------------- |
| Node.js | Native N-API binary            | Platform `optionalDependencies` |
| Browser | WebAssembly module plus WebGPU | The `nanoraster/wasm` subpath   |

The package declares sixteen platform packages as optional dependencies. Each
platform package declares the `os`, `cpu`, and (except on armv7) `libc` it
serves. Your package manager installs the single package that matches your
machine.

| Package                           | Platform                       |
| --------------------------------- | ------------------------------ |
| `nanoraster-darwin-arm64`         | macOS on Apple Silicon         |
| `nanoraster-darwin-x64`           | macOS on Intel                 |
| `nanoraster-linux-x64-gnu`        | Linux on x64 with glibc        |
| `nanoraster-linux-x64-musl`       | Linux on x64 with musl         |
| `nanoraster-linux-arm64-gnu`      | Linux on arm64 with glibc      |
| `nanoraster-linux-arm64-musl`     | Linux on arm64 with musl       |
| `nanoraster-linux-arm-gnueabihf`  | Linux on armv7 with glibc      |
| `nanoraster-linux-arm-musleabihf` | Linux on armv7 with musl       |
| `nanoraster-linux-ppc64-gnu`      | Linux on ppc64le with glibc    |
| `nanoraster-linux-s390x-gnu`      | Linux on s390x with glibc      |
| `nanoraster-win32-x64-msvc`       | Windows on x64                 |
| `nanoraster-win32-arm64-msvc`     | Windows on arm64               |
| `nanoraster-win32-ia32-msvc`      | Windows on x86                 |
| `nanoraster-freebsd-x64`          | FreeBSD on x64                 |
| `nanoraster-android-arm64`        | Android on arm64, experimental |
| `nanoraster-android-arm-eabi`     | Android on armv7, experimental |

The Android packages are experimental: their binaries are built and inspected,
and no job renders on an Android device. The armv7 and Windows x86 packages run
on the Node.js 22 line. Node.js 24 and 26 do not publish binaries for those
platforms. Platform packages are optional, so an install on an unlisted platform
succeeds and then fails at render time. Check your host against the
[compatibility
matrix](https://github.com/taucad/nanoraster/blob/main/compatibility.md) before
deploying.

## Node.js, browsers and bundlers [#nodejs-browsers-and-bundlers]

The package exports a `node` condition. Node.js, Bun, a Vite SSR build, and a
Next.js server build resolve it and reach the native binary. Everything else (a
browser bundle from Vite, webpack 5, Rspack, or Next.js) resolves the default
entry. It imports no Node.js builtin and never references the
native loader, so no bundler needs a `fs` or `module` fallback.

Keep nanoraster external in a server bundle, so the native binary loads
from disk and the bundler does not inline it:

```js title="next.config.js"
export default { serverExternalPackages: ['nanoraster'] };
```

```js title="vite.config.js"
export default { ssr: { external: ['nanoraster'] } };
```

## Installing for another platform [#installing-for-another-platform]

An image for a platform other than the install host needs that platform's
package instead of the host's. Examples: a Linux container assembled on macOS,
or an arm64 image built on x64. pnpm and Yarn Berry accept the set to install:

```yaml title="pnpm-workspace.yaml"
supportedArchitectures:
  os: [linux]
  cpu: [x64, arm64]
  libc: [glibc, musl]
```

Yarn classic has no `libc` selector, and it installs both Linux packages for an
architecture. The loader probes the host at runtime and loads the matching
binary either way, so the cost is disk space.

## Verify the install [#verify-the-install]

Any static glTF 2.0 binary works as `model.glb`. The examples in these docs use
a 12-tooth spur gear.

```typescript
import { renderImage } from 'nanoraster';

import { readFile } from 'node:fs/promises';

const glb = Uint8Array.from(await readFile('model.glb'));
const image = await renderImage(glb, { format: 'webp' });

console.log(image.name, image.bytes.length, image.mimeType);
```

### Expected output [#expected-output]

```console
render.webp 21208 image/webp
```

The exact byte count depends on your model. Confirm that a name, a non-zero
length, and a MIME type print instead of an error.

## Bundling for the browser [#bundling-for-the-browser]

Browser builds need the WebAssembly binary to be reachable at runtime. The
package publishes it on a dedicated subpath, so that bundlers can emit it as an
asset:

```js
import wasmUrl from 'nanoraster/wasm?url';
```

The `?url` import is tested with Vite, webpack 5, and Rspack. In TypeScript it
needs the bundler's ambient types (Vite's `vite/client`) or a
`declare module '*?url'` declaration.
[Render in the browser](https://www.nanoraster.xyz/docs/guides/render-in-the-browser.mdx) covers the rest,
including the WebGPU adapter check.