UndieGravity LogoUndiegravity

How to Run a Next.js or React Template on Your Computer

Install Node.js, run npm install and npm run dev, set environment variables, and fix the most common errors when running a Next.js or React template locally.

By UndieGravity, , 1 min read

You cloned a Next.js or React template and want to see it running. It takes three commands once Node.js is installed. This guide also covers the errors beginners hit most often.

1. Install Node.js

Download the LTS (long term support) version from nodejs.org. It includes npm, the package manager. Check the template's package.json for an engines field; Next.js 16 needs Node.js 20.9 or newer. Verify the install:

node -v
npm -v

2. Install dependencies

cd my-site
npm install

This downloads every package listed in package.json into a node_modules folder. It can take a minute the first time. If the project has a pnpm-lock.yaml or yarn.lock instead of package-lock.json, use that package manager.

3. Set environment variables (if needed)

If the project has an .env.example file, copy it and fill in the values:

cp .env.example .env.local

Never commit .env.local; it is for your secrets. Variables starting with NEXT_PUBLIC_ are visible in the browser, so never put secret keys in them.

4. Start the dev server

npm run dev

Open the address it prints, usually http://localhost:3000 for Next.js or http://localhost:5173 for Vite. Edit any file and the page updates as you save.

5. Build for production

npm run build
npm start

Always run a build before deploying. It catches type errors and broken imports that the dev server tolerates.

Common errors and fixes

  • Port 3000 is already in use: another app is running. Stop it, or run npm run dev -- -p 3001.
  • Module not found: dependencies are missing. Run npm install again.
  • Unsupported engine or syntax errors on startup: your Node.js is too old. Install the current LTS.
  • ERESOLVE peer dependency errors: try npm install --legacy-peer-deps for an older template, but prefer updating the conflicting package.
  • Blank page with errors in the browser console: a required environment variable is missing; check .env.example again.

Keep reading