How to Start a New Next.js Project

The quickest supported way to start a Next.js project is to install Node.js 20.9 or newer, run create-next-app, enter the project directory, and start the development server:

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

Open http://localhost:3000. The generated project uses the current recommended defaults: TypeScript, Tailwind CSS, ESLint, the App Router, Turbopack, and the @/* import alias. See the official Next.js installation guide.

1. Check the prerequisites

• Node.js: 20.9 or newer is the current minimum.
• Operating system: macOS, Windows (including WSL), or Linux.
• Package manager: pnpm, npm, yarn, or bun.
• Supported browsers in the guide: Chrome 111+, Edge 111+, Firefox 111+, and Safari 16.4+.

node --version
npm --version
pnpm --version

If node --version prints a version below 20.9, upgrade Node before creating the app. Using a version manager such as nvm, fnm, or Volta can keep project and system Node versions separate.

2. Create the project

pnpm

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

npm

npx create-next-app@latest my-app --yes
cd my-app
npm run dev

Yarn

yarn create next-app my-app --yes
cd my-app
yarn dev

Bun

bunx create-next-app@latest my-app --yes
cd my-app
bun dev

The --yes flag accepts the saved preferences or the CLI defaults without asking questions. Remove it when you want to choose each option interactively.

3. Complete the interactive setup

Without --yes, the setup flow lets you choose:

Choice	What it controls
TypeScript or JavaScript	Static type checking and typed source files versus plain JavaScript.
ESLint, Biome, or no linter	Linting rules and, with Biome, an integrated formatting workflow.
React Compiler	Whether to enable the compiler option exposed by the current CLI.
Tailwind CSS	Whether Tailwind is configured during creation.
src/ directory	Whether application source lives under src/ instead of the repository root.
App Router	The modern app/ routing and layout model.
Import alias	The default @/* alias or a custom alias.

For a new application, the official setup recommends the App Router and enables TypeScript, Tailwind, ESLint, and Turbopack by default.

4. Verify the first page locally

1. Run the development command from the generated directory.
2. Visit http://localhost:3000.
3. Edit app/page.tsx (or src/app/page.tsx if you selected src/).
4. Save the file and confirm the browser reloads with your change.

cd my-app
pnpm dev

Stop the server with Ctrl+C. For a production-like check, create and serve a build:

pnpm build
pnpm start

5. App Router or Pages Router?

Router	Use it when	Project convention
App Router	You are starting a new project and want the current recommended setup.	app/ or src/app/, layouts, and route segments.
Pages Router	An existing codebase or team standard already uses the pages/ convention.	pages/ or src/pages/.

Both workflows use the same current Node.js 20.9 minimum and can be bootstrapped with create-next-app. Choose one convention for a project and keep route files consistent; the official documentation maintains separate guides for each router.

6. Useful create-next-app options

The CLI reference documents explicit flags for repeatable, scriptable setup:

pnpm create next-app@latest my-app \
  --ts \
  --tailwind \
  --eslint \
  --app \
  --turbopack \
  --src-dir \
  --import-alias "@/*"

Flag	Purpose
--ts, --typescript	Create a TypeScript project.
--js, --javascript	Create a JavaScript project.
--tailwind	Enable Tailwind CSS.
--eslint, --biome, --no-linter	Select the linting setup.
--react-compiler	Enable the React Compiler option.
--app	Use the App Router.
--src-dir	Put application files under src/.
--turbopack, --webpack	Select the development bundler.
--import-alias	Set a custom import alias.
--empty	Start with an empty project template.
--example	Start from a documented example or public GitHub example URL.
--skip-install	Generate files without installing dependencies immediately.

Example template syntax:

pnpm create next-app --example [example-name] [your-project-name]

Use the create-next-app CLI reference for the complete current flag list.

7. Manual installation

Use manual setup when you need to control dependency versions or an existing repository layout.

mkdir my-app
cd my-app
pnpm init
pnpm add next@latest react@latest react-dom@latest

Add scripts to package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

You must then create the route files and configuration expected by your chosen router. For most new projects, the generator is less error-prone because it creates this structure and installs the matching dependencies for you.

8. Common setup problems

Symptom	Cause	Fix
“Node.js version … is not supported”	Node is older than 20.9.	Upgrade Node, reopen the terminal, and rerun the command.
pnpm: command not found	pnpm is not installed or is not on PATH.	Use npm, yarn, or bun, or install pnpm and reopen the shell.
Port 3000 is already in use	Another process owns the default port.	Stop that process or run pnpm dev -- --port 3001, then open port 3001.
Changes do not appear	The wrong directory is running, or the browser cache is stale.	Check pwd, confirm the edited file belongs to the running app, and hard refresh.
Install fails on Windows	Shell permissions, a locked directory, or an unsupported Node installation.	Use a current Node installer or WSL, choose a writable folder, and rerun the package-manager command.
Dependency lockfile conflicts	Multiple package managers were used.	Keep one lockfile, remove the unintended one, reinstall, and use that manager consistently.
Environment variables are missing	The variable was not defined for the current shell or environment file.	Check .env.local, restart the dev server after changes, and expose only browser-safe values with the appropriate public prefix.

9. Performance, reliability, and cost considerations

• Development speed: Turbopack is the generated development default; choose Webpack explicitly if a project requires it.
• Repeatability: Pin the Node version and commit the lockfile so teammates and CI install the same dependency graph.
• Reliability: Run pnpm build (or the equivalent command) in CI before deployment to catch production-only build errors.
• Cost: Creating and running the project locally is software-only; the generator itself has no purchase requirement. Hosting is a separate deployment decision.
• Repository layout: Decide early whether to use a root directory or src/, and whether the project uses App Router or Pages Router.

10. Capture a page after you build it

Once your app is reachable from a public URL, you can automate screenshots for documentation, previews, or visual checks. ScreenshotNeo is a website screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Its clean capture flow accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result in X-Page-Verdict and X-Billed headers.

Or skip the browser setup

Use the ScreenshotNeo API documentation for the complete option list. The basic request is:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Relevant options include full-page screenshots with lazy images loaded, CSS element capture, dark mode, 12 device presets or any viewport, retina scale, PDF paper size and margins, custom CSS and JavaScript, clicks, selector or delay waits, network-idle waits, request blocking, custom headers and cookies, user agent, Authorization, timezone, geolocation, transparent backgrounds, resizing, configurable cache TTL, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, usage reporting, and an OpenAPI specification. Parameter names used by other screenshot APIs also work.

An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Free accounts include 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Can I create a JavaScript project instead of TypeScript?

Yes. Choose JavaScript interactively or pass --js or --javascript.

Is App Router mandatory?

No. It is the recommended default for new projects; Pages Router remains supported for projects that use the pages/ convention.

Can I use an existing directory?

Yes, generate into the directory you intend to own, or use manual installation when the repository already has its own structure.

What URL should I open after setup?

Start the development server and open http://localhost:3000, unless you selected another port.