docs: add npm installation as recommended method with self-contained guides (#331)

Co-authored-by: Linwei Shang <linwei.shang@dfinity.org>

Author: marc0olo

README.md

@@ -4,7 +4,19 @@ A command-line tool for building and deploying applications on the [Internet Com
 
 ## Quick Start
 
-**Install:** See the [Installation Guide](docs/guides/installation.md) for your platform (macOS, Linux, Windows)
+**Prerequisites:** [Node.js](https://nodejs.org/) (LTS)
+
+**Install:**
+
+```bash
+# icp-cli and ic-wasm (required)
+npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
+
+# Motoko toolchain (for Motoko projects)
+npm install -g ic-mops && mops toolchain init
+```
+
+> **Alternative methods:** See the [Installation Guide](docs/guides/installation.md) for shell script, Homebrew, Rust setup, or platform-specific instructions.
 
 Then follow the **[Quickstart](docs/quickstart.md)** to deploy your first canister in under 5 minutes.
 

docs/guides/installation.md

@@ -2,83 +2,93 @@
 
 Set up everything you need to build and deploy canisters on the Internet Computer.
 
-This guide covers:
-- Prerequisites (Node.js)
-- Installing icp-cli (the core tool)
-- Installing language toolchains (Rust or Motoko compilers)
-- Installing ic-wasm for optimization
+**What you'll install:**
 
-## Prerequisites
+| Tool | Purpose |
+|------|---------|
+| **icp-cli** | Core CLI for building and deploying canisters |
+| **ic-wasm** | Optimizes WebAssembly for the Internet Computer |
+| **Language toolchain** | Motoko compiler (via mops) or Rust compiler |
 
-[Node.js](https://nodejs.org/) (LTS recommended) is required for:
-- Installing the Motoko toolchain
-- Building frontend canisters
+> **Windows users:** Local networks require [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/), and Motoko requires [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). For the full experience, install both and run commands inside WSL. Rust-only projects deploying to mainnet can run natively on Windows.
 
-> **Rust-only projects:** If you're only building Rust backend canisters without a frontend, you can skip Node.js.
+> **Linux users:** The pre-compiled binary requires system libraries that may be missing on minimal installs. If installation fails or `icp` won't start, install these dependencies:
+> ```bash
+> # Ubuntu/Debian
+> sudo apt-get install -y libdbus-1-3 libssl3 ca-certificates
+> # Fedora/RHEL
+> sudo dnf install -y dbus-libs openssl ca-certificates
+> ```
 
-## Install icp-cli
+## Quick Install (Recommended)
 
-**macOS / Linux / WSL:**
+**Required:** [Node.js](https://nodejs.org/) (LTS) — needed for npm and for building frontend canisters.
+
+**1. Install the core tools:**
 
 ```bash
-curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/download/v0.1.0-beta.6/icp-cli-installer.sh | sh
+npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
 ```
 
-Restart your shell or follow the instructions shown by the installer.
+**2. Install your language toolchain:**
 
-**Windows:**
+**Motoko:**
 
-```ps1
-powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/download/v0.1.0-beta.6/icp-cli-installer.ps1 | iex"
+```bash
+npm install -g ic-mops && mops toolchain init
 ```
 
-Restart your terminal after installation.
-
-> **Windows notes:**
-> - **Local networks** require [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)
-> - **Motoko canisters** require [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) — the Motoko compiler doesn't run natively on Windows. Install icp-cli inside WSL and follow the macOS/Linux instructions instead.
-> - **Rust canisters** work natively on Windows without WSL
-
-**Alternative: Homebrew (macOS only)**
+**Rust** (if not already installed):
 
 ```bash
-brew install dfinity/tap/icp-cli
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup target add wasm32-unknown-unknown
 ```
 
-To update later: `brew upgrade dfinity/tap/icp-cli`
-
-### Verify Installation
+**3. Verify installation:**
 
 ```bash
 icp --version
+ic-wasm --version
 ```
 
-## Install Language Toolchains
+---
 
-icp-cli uses your language's compiler to build canisters. Install what you need:
+## Alternative Installation Methods
 
-**Rust canisters:**
+If you prefer not to use npm, or need platform-specific options, see the sections below.
 
-If you don't have Rust installed, install it from [rustup.rs](https://rustup.rs/):
+### icp-cli
+
+**Shell Script (macOS / Linux / WSL):**
 
 ```bash
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh
 ```
 
-Then add the WebAssembly target:
+Restart your shell or follow the instructions shown by the installer.
+
+**Shell Script (Windows, for Rust-only mainnet projects):**
 
-```bash
-rustup target add wasm32-unknown-unknown
+```ps1
+powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex"
 ```
 
-**Motoko canisters:**
+Restart your terminal after installation.
+
+**Homebrew (macOS only):**
 
 ```bash
-npm install -g ic-mops
-mops toolchain init
+brew install dfinity/tap/icp-cli
 ```
 
-## Install ic-wasm (Required for templates and recipes)
+To update later: `brew upgrade dfinity/tap/icp-cli`
+
+> **Note:** Homebrew installs ic-wasm as a dependency, so you can skip the ic-wasm installation below.
+
+> **Note:** [Node.js](https://nodejs.org/) (LTS recommended) is still required for the Motoko toolchain and frontend canisters when using alternative installation methods.
+
+### ic-wasm
 
 `ic-wasm` is a WebAssembly post-processing tool that optimizes canisters for the Internet Computer. It provides:
 - **Optimization**: ~10% cycle reduction for Motoko, ~4% for Rust
@@ -87,26 +97,52 @@ mops toolchain init
 - **Shrinking**: Remove unused code and debug symbols
 
 **When is it needed?**
-- **Required** if using official templates (motoko, rust, hello-world) - all backend templates use recipes that depend on ic-wasm
-- **Required** if using official recipes (`@dfinity/motoko`, `@dfinity/rust`) - these recipes inject required metadata using ic-wasm
+- **Required** if using official templates (motoko, rust, hello-world) — all backend templates use recipes that depend on ic-wasm
+- **Required** if using official recipes (`@dfinity/motoko`, `@dfinity/rust`) — these recipes inject required metadata using ic-wasm
 - **Not required** if building canisters with custom script steps that don't invoke ic-wasm
 
 **Installation:**
 
-**Note:** If you installed icp-cli via Homebrew, ic-wasm is already installed as a dependency. Skip this section.
+> **Note:** If you installed icp-cli via Homebrew, ic-wasm is already included. Skip this section.
+
+**npm (recommended):**
+
+```bash
+npm install -g @icp-sdk/ic-wasm
+```
+
+**Shell Script (macOS/Linux):**
 
-**macOS/Linux:**
 ```bash
 curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.sh | sh
 ```
 
-**Windows:**
+**Shell Script (Windows):**
+
 ```ps1
 powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.ps1 | iex"
 ```
 
 Learn more: [ic-wasm repository](https://github.com/dfinity/ic-wasm)
 
+### Language Toolchains
+
+**Motoko:**
+
+```bash
+npm install -g ic-mops
+mops toolchain init
+```
+
+**Rust:**
+
+Install from [rustup.rs](https://rustup.rs/):
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup target add wasm32-unknown-unknown
+```
+
 
 ## Troubleshooting
 

docs/quickstart.md

@@ -2,11 +2,21 @@
 
 Deploy a full-stack app to a local network in under 5 minutes.
 
-## Prerequisites
+**Prerequisites:** [Node.js](https://nodejs.org/) (LTS) is required for the installation commands below.
 
-Complete the [Installation Guide](guides/installation.md) first.
+> **Windows users:** This quickstart requires [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (for Motoko) and [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (for local networks). Install both first, then run all commands inside WSL.
 
-> **Tip:** An npm package for even simpler installation is coming soon.
+## Install
+
+```bash
+# icp-cli and ic-wasm (required)
+npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
+
+# Motoko toolchain (for Motoko projects)
+npm install -g ic-mops && mops toolchain init
+```
+
+> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, or other options.
 
 ## Steps
 

docs/tutorial.md

@@ -14,12 +14,33 @@ In this tutorial, you'll deploy two canisters:
 
 ## Prerequisites
 
-Complete the **[Installation Guide](guides/installation.md)** first.
+**Required:** [Node.js](https://nodejs.org/) (LTS) for the installation commands below.
 
-Verify icp-cli is installed:
+> **Windows users:** This tutorial requires [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (for Motoko) and [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (for local networks). Install both first, then run all commands inside WSL.
+
+Install the required tools:
+
+```bash
+# icp-cli and ic-wasm (required)
+npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
+
+# Motoko toolchain (for Motoko projects)
+npm install -g ic-mops && mops toolchain init
+```
+
+This installs:
+- **icp-cli** — the core CLI for building and deploying canisters
+- **ic-wasm** — optimizes WebAssembly for the Internet Computer
+- **mops** — Motoko package manager, which also installs the Motoko compiler
+
+> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, Rust setup, or other options.
+
+Verify the tools are installed:
 
 ```bash
 icp --version
+ic-wasm --version
+mops --version
 ```
 
 ## Create a Project