Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 72 ยท Getting Started

Creating a Next.js App

Create a Next.js project with create-next-app, understand each prompt (TypeScript, Tailwind, src folder), and learn the dev, build and start scripts.

The fastest way to start a Next.js project is a command-line tool called create-next-app. It asks a few questions, writes a ready-to-run project into a new folder and installs the dependencies. A minute later you have a dev server on your own machine showing a working page.

This lesson walks through that command, what each choice means, what lands on disk and what the three scripts in package.json do. The commands here run on your computer, not in this page, so they are shown read-only. The live examples at the end are stand-ins: one builds the command and file list from your choices, and one explains a package.json and checks Node.js versions.

What you need first

Next.js runs on Node.js, the JavaScript runtime you probably already use for tools like npm. Recent versions of Next.js need a currently supported Node.js version, and Next.js 16 requires at least Node.js 20.9. Use an LTS (long-term support) release, and check the requirement in the installation page of the version you pick, because it can rise over time.

You also need a package manager. npm ships with Node.js, and pnpm, Yarn and Bun work just as well. This tutorial writes npm in examples; swap in your own tool.

Terminal
# read-only: check your tools
node --version
npm --version

Running create-next-app

Run the tool with your package manager, giving it the name of the folder to create:

Terminal
# read-only
npx create-next-app@latest my-app

The @latest part makes sure you get the newest release rather than a copy cached on your machine. The same command exists for other package managers:

Terminal
# read-only
pnpm create next-app my-app
yarn create next-app my-app
bun create next-app my-app

The tool then asks questions. The wording changes slightly between versions, but the topics are stable:

The questions you will answer

Project name Becomes the folder and the package name.
TypeScript Yes is the best choice for almost everyone.
Linter ESLint checks common mistakes for you.
Tailwind CSS Optional utility-first styling, preconfigured.

Recent versions also offer a short list of recommended defaults.

1 / 2

If you press Enter through the prompts, you get the recommended defaults: TypeScript, ESLint, Tailwind CSS, the App Router and the @/* import alias. That is a fine starting point, and it is the setup this tutorial assumes. Each choice can be added or removed later, so none of them locks you in.

Skipping the questions with flags

Every question has a command-line flag, which is handy for scripts and for documenting how a project was created:

Terminal
# read-only
npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm

Other useful flags are --skip-install (write the files but do not install packages), --disable-git (do not create a Git repository) and --yes (accept the defaults without asking). Run npx create-next-app@latest --help to see the list for your version.

What you get

For the default answers, the project looks like this. Names such as eslint.config.mjs depend on your choices and version, so treat the list as typical rather than exact:

TEXT
my-app/
  app/
    favicon.ico
    globals.css
    layout.tsx
    page.tsx
  public/
    next.svg
    vercel.svg
  .gitignore
  eslint.config.mjs
  next.config.ts
  package.json
  postcss.config.mjs
  tsconfig.json
  README.md

The folders and files matter more than the details:

  • app/ is the App Router. The page.tsx here is your home page, and layout.tsx wraps every page. The next lessons explain both.
  • public/ holds static files such as images and icons. A file at public/logo.svg is served at /logo.svg.
  • next.config.ts is where you configure Next.js. It starts almost empty.
  • package.json lists dependencies and scripts. The key dependencies are next, react and react-dom.
  • tsconfig.json configures TypeScript, including the @/* alias.

After the first run you will also see a .next/ folder, which is Next.js's build output and cache. It is in .gitignore, and you never edit it by hand. A file called next-env.d.ts also appears, which wires Next.js's types into TypeScript.

The three scripts

Open package.json and look at scripts:

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

Each one is a different mode of the same tool:

  • npm run dev starts the development server at http://localhost:3000. It compiles pages on demand, reloads the browser when you save a file and shows detailed error overlays. It is slower and less optimized than production on purpose. Use it while you write code.
  • npm run build creates the optimized production build. It compiles everything, pre-renders the pages that can be made ahead of time, and prints a table of your routes. A type error or a failed static page stops the build, so it is also a strong check before you deploy.
  • npm run start runs the production server for a finished build. It does nothing useful until you have run build.
  • npm run lint runs the linter (in Next.js 16 it calls ESLint directly; older versions used next lint).
Terminal
# read-only: the everyday loop
cd my-app
npm run dev
# open http://localhost:3000, edit app/page.tsx, save, the page updates

To use another port, pass it to the tool: next dev -p 4000, or set the PORT environment variable.

Turbopack

Next.js ships its own bundler, Turbopack, written in Rust. In Next.js 16 it is the default for both next dev and next build, so you get fast startup and fast refresh without doing anything. Older versions used webpack by default and offered Turbopack with a --turbopack flag. If a project has a custom webpack setup that Turbopack does not support yet, you can opt out with next dev --webpack and next build --webpack. Most new projects never need to.

Edit app/page.tsx and save while the dev server runs. The change appears in the browser without a full reload, and component state is kept where possible. This fast refresh feature is the main reason development feels quick.

Try it: build the command

The first live stand-in turns your choices into a create-next-app command and the files you would get. It follows the conventions above but is not the real tool, so the file list is a simplified model.

Build your create-next-app command

Turn on "src dir" and watch the three app files move under src/. Turn off TypeScript and .tsx becomes .js, next.config.ts becomes next.config.mjs and tsconfig.json becomes jsconfig.json.

Try it: scripts and Node versions

The second stand-in is a Node.js program. It reads a package.json, explains each script, and checks a few Node.js versions against the minimum that Next.js 16 documents (20.9). The version comparison is a simplified version of what npm does with an engines field.

Node.js Explain package.json scripts and check Node versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that typecheck is not one of Next.js's own commands: scripts in package.json can run any tool, and you will add your own as the project grows. If you ever see the "too old" result on your machine, upgrade Node.js before debugging anything else, because an old runtime is the most common cause of confusing install errors.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command creates a new Next.js project interactively?

    create-next-app is the official scaffolding tool. The @latest makes sure you get the newest release.
  2. 2. What does npm run build do?

    next build compiles for production and pre-renders what it can. next start then serves the result.
  3. 3. Where is a file at public/logo.svg served from?

    The contents of public are served from the site root, without the folder name.
  4. 4. Which bundler is the default for next dev and next build in Next.js 16?

    Turbopack became the default bundler in Next.js 16. You can opt out with the --webpack flag if you need to.
  5. 5. You run npm run start before ever running npm run build. What happens?

    next start only serves the output of next build. Without a build there is nothing to serve.

Summary

  • npx create-next-app@latest my-app scaffolds a project; the prompts cover TypeScript, linting, Tailwind CSS, the src folder, the App Router and an import alias, and each has a flag.
  • Next.js needs a supported Node.js version (20.9 or newer for Next.js 16); check the documentation for yours.
  • The generated project has app/ for routes, public/ for static files, next.config.ts for settings and a package.json with the main scripts.
  • dev is for writing code with fast refresh, build makes the production build, start serves that build, and lint runs the linter.
  • Turbopack is the default bundler in Next.js 16 for both development and production builds.

Next: Project Structure