Skip to main content

​
Installation

This guide covers everything you need to install and run create-nextjs-dapp on your system.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Node.js

create-nextjs-dapp requires Node.js 18 or higher. 
node --version
Recommended: Use Node.js 20.x or 22.x for the best performance and latest features.

​
Installing Node.js

If you don’t have Node.js installed or need to upgrade:
Download and install from nodejs.org:
  • LTS version (Recommended): Stable, production-ready
  • Current version: Latest features

​
Package Manager

You’ll need at least one package manager. create-nextjs-dapp works with:
  • npm (comes with Node.js) - Default
  • yarn - Fast, reliable package manager
  • pnpm - Efficient disk space usage
  • bun - Fast all-in-one JavaScript runtime
The CLI will automatically detect which package manager you’re using.

​
Installation Methods

create-nextjs-dapp is designed to be run directly with npx without global installation. Choose your preferred package manager: 
npx create-nextjs-dapp
The CLI automatically detects which package manager you used to run it and will use the same one for installing dependencies in your project.

​
Global Installation (Optional)

While not recommended, you can install globally if preferred: 
npm install -g create-nextjs-dapp
create-nextjs-dapp
Not recommended: Global installation means you won’t automatically get updates. Using npx ensures you always run the latest version.

​
Verification

Verify that create-nextjs-dapp is working correctly:
1

Check Version

Run the version command:
npx create-nextjs-dapp --version
Expected output:
create-nextjs-dapp v0.1.0
2

View Help

Display the help message to see all available options:
npx create-nextjs-dapp --help
You should see the full CLI documentation with all available flags and wallet providers.
3

Create Test Project

Create a test project to ensure everything works:
npx create-nextjs-dapp test-project --chain evm --wallet rainbowkit
cd test-project
npm install
npm run dev
If successful, you’ll see the development server running at http://localhost:3000.

​
Troubleshooting

Problem: You’re running Node.js version 17 or lower.Solution: Upgrade to Node.js 18 or higher:
# Using nvm
nvm install 20
nvm use 20

# Or download from nodejs.org
Verify your version:
node --version
Problem: npm is not installed or not in your PATH.Solution:
  1. Reinstall Node.js from nodejs.org (includes npm)
  2. Or install npm separately: 
    curl -L https://www.npmjs.com/install.sh | sh
Verify npm installation:
npm --version
Problem: npm doesn’t have permission to install packages globally.Solution 1 (Recommended): Use npx instead of global installation:
npx create-nextjs-dapp
Solution 2: Fix npm permissions:
# Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
Solution 3: Use a Node version manager like nvm (recommended).
Problem: Your project name contains invalid characters.Solution: Use a valid npm package name:
  • Lowercase letters only
  • No spaces (use hyphens instead)
  • Start with a letter
  • Only letters, numbers, hyphens, and underscores
✅ Valid names:
my-dapp
my_dapp_v2
cooldapp123
❌ Invalid names:
My Dapp       # spaces not allowed
My-Dapp       # uppercase not allowed
123dapp       # can't start with number
my@dapp       # special chars not allowed
Problem: npm registry is slow or blocked in your region.Solution 1: Use a faster registry mirror:
# Temporarily use a different registry
npx --registry https://registry.npmmirror.com create-nextjs-dapp
Solution 2: Configure npm to use a mirror:
npm config set registry https://registry.npmmirror.com
Solution 3: Try a different package manager:
# pnpm is often faster
pnpm create nextjs-dapp
Problem: The --git flag was used but git is not installed.Solution 1: Install git:
# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows
# Download from https://git-scm.com
Solution 2: Skip git initialization:
npx create-nextjs-dapp my-dapp
# Don't use --git flag
You can initialize git manually later:
cd my-dapp
git init
Problem: You specified a package manager (e.g., --use-yarn) but it’s not installed.Solution: Install the package manager or use a different one:
# Install yarn
npm install -g yarn

# Install pnpm
npm install -g pnpm

# Install bun
curl -fsSL https://bun.sh/install | bash
Or use the default (npm):
npx create-nextjs-dapp my-dapp
Problem: You’re using an old version of create-nextjs-dapp.Solution: When you run the CLI, it will automatically notify you if a new version is available:
╭─────────────────────────────────────────────╮
│                                             │
│   Update available 0.1.0 → 0.2.0            │
│   Run npm i -g create-nextjs-dapp           │
│                                             │
╰─────────────────────────────────────────────╯
If using npx (recommended), simply run the command again:
npx create-nextjs-dapp@latest
If installed globally, update it:
npm update -g create-nextjs-dapp

​
System Requirements

Operating System

  • macOS 10.15+
  • Windows 10/11
  • Linux (Ubuntu 20.04+, Debian 10+, or equivalent)

Runtime

  • Node.js 18.0.0 or higher
  • npm 9.0.0+ (or equivalent yarn/pnpm/bun)

Disk Space

  • Minimum: 500 MB free space
  • Recommended: 2 GB free space

Memory

  • Minimum: 2 GB RAM
  • Recommended: 4 GB RAM or more

​
Additional Requirements

Depending on your chosen wallet provider, you may need:

​
API Keys

Most wallet providers require API keys or project IDs:
You’ll need to sign up for these services and obtain API keys before your dApp can connect to wallets. The generated .env.example file will remind you which keys are needed.

​
Git (Optional)

If you want to initialize a git repository with --git: 
git --version

​
Next Steps

Now that you have create-nextjs-dapp installed, you’re ready to:

Create Your First dApp

Follow the quickstart guide to build your first project

Explore CLI Options

Learn about all available CLI flags and options

Build docs developers (and LLMs) love

Get started for freeTalk to us