Skip to main content

Installation

Requirements​

Before you begin, you need to install the following tools:

Windows Compatibility

Scaffold-Stylus currently does not support Windows natively. If you're using Windows, we recommend:

  • Use WSL (Windows Subsystem for Linux) - Install WSL2 and run Scaffold-Stylus within the Linux environment
  • Switch to Linux or macOS - For the best development experience

For WSL setup, follow the Microsoft WSL installation guide.

Install Rust and the Stylus CLI tool with Cargo:​

Install Rust:​

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Check the Rust installation guide for more information.

Install the Stylus CLI tool with Cargo:​

danger

This project requires cargo-stylus version 0.10.8 and rustc version 1.91.0 (as pinned in packages/stylus/contracts/rust-toolchain.toml). Do NOT use stylusup to install Stylus tools, as it installs the latest versions which are incompatible with these pinned requirements.

cargo install --force --locked cargo-stylus@0.10.8

Prerequisite:

  • cargo-stylus version 0.10.8
  • rustc version match with packages/stylus/contracts/rust-toolchain.toml

Set default toolchain match rust-toolchain.toml and add the wasm32-unknown-unknown build target to your Rust compiler:

rustup default 1.91.0
rustup target add wasm32-unknown-unknown --toolchain 1.91.0

You should now have it available as a Cargo subcommand:

cargo stylus --help

Setup​

For a simplified setup, Scaffold-Stylus offers a npx tool that guides you interactively through the setup:

npx create-stylus@latest

You will be presented with a series of prompts:

  • Project Name: Enter a name for your project, e.g., my-dapp-example.

Once the setup is complete, navigate to the project directory:

cd project-name

If you want to use extensions, you can add the -e flag followed by the extension name:

npx create-stylus@latest -e extension-name

For more information about available extensions and how to use them, check out the Extensions section

Alternative: Start from GitHub​

If you prefer, you can start by cloning the Scaffold-Stylus repository directly and running it locally. This gives you full access to all source code and configuration.

  1. Clone the repository and install dependencies:
git clone https://github.com/Arb-Stylus/scaffold-stylus.git
cd scaffold-stylus
yarn install
# Initialize submodules (required for Nitro dev node)
git submodule update --init --recursive
note

Multi-contract support: A single Scaffold-Stylus project can hold as many Stylus contracts as you need — each is its own Rust crate under packages/stylus/contracts/<name>/, and all are built and managed together in the same workspace. Run yarn new-module <name> to scaffold a new contract; members = ["*"] in contracts/Cargo.toml auto-discovers it automatically — no manual registration required.

The workspace is self-contained in packages/stylus/contracts/ with its own Cargo.toml (with [workspace]), Cargo.lock, and rust-toolchain.toml. The included example contract is at packages/stylus/contracts/your-contract/src/lib.rs.