# Installation

> Install via npm optional platform packages, npx, or GitHub release binaries; Rust toolchain requirements for building from source; Node engine constraints.

- Repository: pionxzh/wakaru
- GitHub: https://github.com/pionxzh/wakaru
- Human docs: https://grok-wiki.com/public/docs/pionxzh-wakaru-77a438a6cc6b
- Complete Markdown: https://grok-wiki.com/public/docs/pionxzh-wakaru-77a438a6cc6b/llms-full.txt

## Source Files

- `README.md`
- `npm/package.json`
- `npm/bin/wakaru`
- `Cargo.toml`
- `.github/workflows/rust-release.yml`

---

---
title: "Installation"
description: "Install via npm optional platform packages, npx, or GitHub release binaries; Rust toolchain requirements for building from source; Node engine constraints."
---

`@wakaru/cli` ships a Node launcher (`npm/bin/wakaru`) that resolves a prebuilt native binary from optional platform packages. End users typically install through npm or `npx`; contributors build `wakaru-cli` from the Rust workspace.

## Supported platforms

Prebuilt npm and GitHub release binaries cover four `platform-arch` pairs:

| Platform | npm optional package | GitHub release artifact |
|----------|----------------------|-------------------------|
| macOS ARM64 (`darwin-arm64`) | `@wakaru/cli-darwin-arm64` | `wakaru-darwin-arm64.tar.gz` |
| Linux x64 (`linux-x64`) | `@wakaru/cli-linux-x64` | `wakaru-linux-x64.tar.gz` |
| Linux ARM64 (`linux-arm64`) | `@wakaru/cli-linux-arm64` | `wakaru-linux-arm64.tar.gz` |
| Windows x64 (`win32-x64`) | `@wakaru/cli-win32-x64` | `wakaru-win32-x64.zip` |

<Warning>
Intel macOS (`darwin-x64`), Windows ARM64, and other unlisted combinations are not distributed on npm. The launcher exits with `Unsupported platform` when no mapping exists. Build from source on those targets, or use a supported host.
</Warning>

## Node.js requirement

<ParamField body="engines.node" type="semver" required>
Minimum Node.js version enforced by `@wakaru/cli`.
</ParamField>

```json
"engines": { "node": ">=16.0.0" }
```

Node is required for the npm entrypoint even though decompilation runs in the native Rust binary. `npx` and global installs both need a compatible Node runtime.

## Install methods

<Tabs>
<Tab title="npm (global)">

Install the launcher and let npm pull the matching optional platform binary:

```bash
npm install -g @wakaru/cli@latest
```

Pin a specific release by replacing `@latest` with a version tag (for example `@1.5.0`).

</Tab>
<Tab title="npx (one-off)">

Run without a global install:

```bash
npx @wakaru/cli input.js -o output.js
npx @wakaru/cli bundle.js --unpack -o out/
```

`npx` downloads `@wakaru/cli` and the platform package for the current host on each invocation (subject to npm cache).

</Tab>
<Tab title="GitHub releases">

Download a prebuilt binary from [GitHub Releases](https://github.com/pionxzh/wakaru/releases). Release tags (`v*`) publish the four archives listed in the platform table.

<Steps>
<Step title="Download the archive for your platform">

Pick `wakaru-darwin-arm64.tar.gz`, `wakaru-linux-x64.tar.gz`, `wakaru-linux-arm64.tar.gz`, or `wakaru-win32-x64.zip`.

</Step>
<Step title="Extract and place on PATH">

<CodeGroup>
```bash title="macOS / Linux"
tar xzf wakaru-<platform>.tar.gz
chmod +x wakaru
sudo mv wakaru /usr/local/bin/   # or another directory on PATH
```

```powershell title="Windows"
Expand-Archive wakaru-win32-x64.zip -DestinationPath .
# Add the folder containing wakaru.exe to PATH
```
</CodeGroup>

</Step>
<Step title="Verify">

```bash
wakaru --help
```

</Step>
</Steps>

</Tab>
</Tabs>

## How npm optional platform packages work

`@wakaru/cli` declares four `optionalDependencies`, one per published triple. npm installs only the package whose `os` and `cpu` fields match the host.

```text
@wakaru/cli
├── bin/wakaru          # Node shim (require.resolve + spawn)
└── optionalDependencies
    ├── @wakaru/cli-darwin-arm64   → wakaru
    ├── @wakaru/cli-linux-x64      → wakaru
    ├── @wakaru/cli-linux-arm64    → wakaru
    └── @wakaru/cli-win32-x64      → wakaru.exe
```

At runtime the shim:

1. Reads `process.platform` and `process.arch`.
2. Resolves the platform package binary with `require.resolve`.
3. Spawns it with `stdio: "inherit"` and forwards `process.argv.slice(2)`.

If resolution fails (optional install skipped or corrupted `node_modules`), stderr suggests:

```text
Try reinstalling: npm install @wakaru/cli@next
```

<Tip>
In monorepos, ensure `@wakaru/cli` is a direct dependency (or devDependency) so the optional platform package installs for the machine running the command. Hoisting alone does not guarantee the platform tarball is present.
</Tip>

## Build from source

Building compiles `wakaru-cli` from the workspace root. CI and releases use the **stable** Rust toolchain via `dtolnay/rust-toolchain@stable`; the workspace targets **edition 2021**.

<Steps>
<Step title="Install Rust">

Install [rustup](https://rustup.rs/) and select the stable channel:

```bash
rustup default stable
```

</Step>
<Step title="Clone and build">

```bash
git clone https://github.com/pionxzh/wakaru.git
cd wakaru
cargo build --release -p wakaru-cli
```

The binary lands at `target/release/wakaru` (or `target/release/wakaru.exe` on Windows).

</Step>
<Step title="Run without installing">

```bash
cargo run -p wakaru-cli -- input.js -o output.js
cargo run -p wakaru-cli -- --unpack bundle.js -o out/
```

</Step>
<Step title="Optional: faster test iteration">

For development, `docs/testing.md` documents a `dev-release` profile:

```bash
cargo build --profile dev-release -p wakaru-cli
```

</Step>
</Steps>

### Cross-compilation targets

Release automation builds these Rust triples (matching the npm platform matrix):

| Rust target | npm / release label |
|-------------|---------------------|
| `aarch64-apple-darwin` | `darwin-arm64` |
| `x86_64-unknown-linux-gnu` | `linux-x64` |
| `aarch64-unknown-linux-gnu` | `linux-arm64` |
| `x86_64-pc-windows-msvc` | `win32-x64` |

Example cross-build:

```bash
rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu -p wakaru-cli
```

Linux release binaries link against **glibc** (`*-unknown-linux-gnu`). Minimal musl-based images may need a local build rather than the published tarball.

### Development dependencies

Not required to run `wakaru`, but common when hacking on the repo:

| Tool | Purpose |
|------|---------|
| `cargo-nextest` | Faster parallel test runs (`cargo nextest run --workspace`) |
| `cargo-insta` | Review and accept snapshot diffs |
| `wasm-pack` + `wasm32-unknown-unknown` | Build `wakaru-wasm` for the browser playground |

See <Card title="Contributing" href="/contributing">Contributing</Card> and <Card title="Testing and snapshots" href="/testing-and-snapshots">Testing and snapshots</Card> for the full verification matrix.

<Note>
The workspace is not set up for `cargo install wakaru-cli` from crates.io. Use `cargo build -p wakaru-cli`, npm, or GitHub release binaries.
</Note>

## Verify installation

<RequestExample>
```bash
wakaru --help
echo 'var a=1;' | wakaru
```
</RequestExample>

<Check>
A successful install prints CLI help and decompiled output on stdout. Version alignment: the workspace `Cargo.toml`, `npm/package.json`, and platform packages share the same semver (currently `1.5.0` at time of writing).
</Check>

## Troubleshooting

| Symptom | Likely cause | Action |
|---------|--------------|--------|
| `Unsupported platform: …` | Host not in the four supported pairs | Build from source or use GitHub releases on a supported machine |
| `Could not find the wakaru binary for …` | Optional platform package missing | Reinstall: `npm install @wakaru/cli@latest` (or `@next` per launcher hint) |
| `engine` warnings from npm | Node &lt; 16 | Upgrade Node to `>=16.0.0` |
| Binary runs but `command not found` after GitHub install | Not on PATH | Move `wakaru` / `wakaru.exe` into a PATH directory |

For overwrite protection, unpack skips, and warning codes after install, see <Card title="Troubleshooting" href="/troubleshooting">Troubleshooting</Card>.

## Related pages

<CardGroup>
<Card title="Quickstart" href="/quickstart">
First decompile and unpack commands, stdout vs `-o`, and success signals.
</Card>
<Card title="CLI reference" href="/cli-reference">
Full flag surface, subcommands, and stdin/stdout behavior.
</Card>
<Card title="WASM and playground" href="/wasm-and-playground">
Build `wakaru-wasm` and run the browser demo locally.
</Card>
<Card title="Contributing" href="/contributing">
Fork workflow, `cargo fmt` / clippy / test gates, and where to send PRs.
</Card>
</CardGroup>