Next.js CLI Commands

Next.js comes with a powerful Command Line Interface (CLI) that helps you develop, build, and deploy your applications. Understanding these CLI commands is essential for efficient Next.js development. In this guide, we'll explore the most important Next.js CLI commands you'll use in your projects.

Introduction

The Next.js CLI is a set of commands that allow you to:

• Start a development server
• Build your application for production
• Start a production server
• Create new Next.js projects
• Execute custom scripts

These commands are typically run from your terminal and are configured in your project's package.json file. Let's dive into each command and understand how they work.

Creating a New Next.js Project

The easiest way to start a new Next.js project is to use create-next-app:

bash

npx create-next-app@latest my-next-app
# or
yarn create next-app my-next-app
# or
pnpm create next-app my-next-app

When you run this command, you'll be prompted to configure your project:

✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … No
✔ Would you like to use App Router? … Yes
✔ Would you like to customize the default import alias (@/*)? … No

After answering these questions, a new directory will be created with a fully set up Next.js project.

Development Command

To start a development server, use the next dev command:

bash

npx next dev
# or
yarn dev
# or
npm run dev

Output:

ready - started server on 0.0.0.0:3000, url: http://localhost:3000
event - compiled client and server successfully in 188 ms (17 modules)
wait - compiling...
event - compiled successfully in 14 ms (17 modules)

This command starts a development server with hot reloading at http://localhost:3000. Any changes you make to your code will automatically refresh the page.

Development Command Options

The next dev command supports several options:

• -p, --port [port]: Start the development server on a specific port (default: 3000)

  bash

  npx next dev -p 4000

• -H, --hostname [hostname]: Set the hostname for the development server

  bash

  npx next dev -H 192.168.1.2

• --turbo: Enable Turbo dev server (experimental)

  bash

  npx next dev --turbo

Build Command

To build your application for production, use the next build command:

bash

npx next build
# or
yarn build
# or
npm run build

Output:

info  - Checking validity of types
info  - Creating an optimized production build
info  - Compiled successfully
info  - Collecting page data
info  - Generating static pages (3/3)
info  - Finalizing page optimization

Route (pages)                              Size     First Load JS
┌ ○ /                                      5.2 kB        81.1 kB
├   /_app                                  0 B            75.9 kB
├ ○ /404                                   182 B          76.1 kB
└ ○ /about                                 2.58 kB       78.5 kB
+ First Load JS shared by all              76 kB
  ├ chunks/framework-2c79e2a64abdb08b.js   45.2 kB
  ├ chunks/main-0ecb9ccfcb6c9b24.js        29.2 kB
  ├ chunks/pages/_app-3c9f8c0c5bd6f746.js  499 B
  └ chunks/webpack-69bfa6990bb9e155.js     769 B

This command creates an optimized production build of your application in the .next folder. The output shows the size of each page and the shared JavaScript bundles.

Start Command

To start a production server with the built application, use the next start command:

bash

npx next start
# or
yarn start
# or
npm run start

Output:

ready - started server on 0.0.0.0:3000, url: http://localhost:3000

This command starts a production server that serves your built application. It's important to note that you must run next build before running next start.

Start Command Options

The next start command supports these options:

• -p, --port [port]: Start the production server on a specific port (default: 3000)

  bash

  npx next start -p 8000

• -H, --hostname [hostname]: Set the hostname for the production server

  bash

  npx next start -H 0.0.0.0

Lint Command

Next.js comes with built-in ESLint configuration. To run the linter, use the next lint command:

bash

npx next lint
# or
yarn lint
# or
npm run lint

Output:

info  - Using styled-jsx with babel-plugin-macros requires babel-plugin-macros to be configured in your babel config.
info  - ESLint found no problems on 12 files
✨  Done in 2.65s.

This command runs ESLint on all files in the pages/, app/, components/, lib/, and src/ directories.

Lint Command Options

• --dir: Specify the directory to lint (default: .)

  bash

  npx next lint --dir pages

• --fix: Automatically fix linting issues

  bash

  npx next lint --fix

Export Command

To export your Next.js application as static HTML, use the next export command:

bash

npx next build && npx next export
# or
yarn build && yarn export
# or
npm run build && npm run export

Output:

info  - Checking validity of types
info  - Creating an optimized production build
info  - Compiled successfully
info  - Collecting page data
info  - Generating static pages (3/3)
info  - Finalizing page optimization
Export successful. Files written to /your-project/out

This command exports your application to static HTML files in the out directory. Note that some Next.js features like API routes and server-side rendering won't work with exported sites.

Note: As of Next.js 13.3, next export is being replaced with output: 'export' in your next.config.js file.

Info Command

To print relevant information about your Next.js application, use the next info command:

bash

npx next info
# or
yarn next info
# or
npm run next info

Output:

Operating System:
  Platform: linux
  Arch: x64
  Version: #1 SMP Debian 5.10.140-1 (2022-09-02)
Binaries:
  Node: 16.15.0
  npm: 8.5.5
  Yarn: 1.22.19
  pnpm: 7.9.0
Relevant packages:
  next: 13.4.12
  react: 18.2.0
  react-dom: 18.2.0

This command is useful when you need to share environment information for debugging purposes.

Telemetry Command

Next.js collects anonymous telemetry data about general usage. To manage this, use the next telemetry command:

bash

# To disable telemetry
npx next telemetry disable

# To enable telemetry
npx next telemetry enable

# To check the status
npx next telemetry status

Output:

Telemetry is disabled.

Custom Scripts in package.json

Typically, you'll define these commands as scripts in your package.json file:

json

{
  "name": "my-next-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "13.4.12",
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

With these scripts defined, you can run:

bash

npm run dev
npm run build
npm run start
npm run lint

You can also add custom scripts for common workflows:

json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "dev:turbo": "next dev --turbo",
    "build:analyze": "ANALYZE=true next build",
    "export": "next build && next export",
    "clean": "rm -rf .next out"
  }
}

Real-World Examples

Setting Up a Development Environment with Custom Port

bash

# Start the development server on port 4000
npm run dev -- -p 4000

Creating a Production Deployment Pipeline

bash

# Full production build and start sequence
npm run build && npm run start

Building and Analyzing Bundle Sizes

Using the @next/bundle-analyzer package:

js

// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // your Next.js config
});

Then run:

bash

ANALYZE=true npm run build

This will open a visual representation of your bundle sizes in the browser.

Continuous Integration Setup

In a CI/CD pipeline (e.g., GitHub Actions):

yaml

steps:
  - uses: actions/checkout@v2
  - uses: actions/setup-node@v2
    with:
      node-version: '16'
  - name: Install dependencies
    run: npm ci
  - name: Lint
    run: npm run lint
  - name: Build
    run: npm run build
  - name: Test
    run: npm run test

Summary

Next.js CLI commands are essential tools for developers working with the framework. The main commands to remember are:

• next dev: Start a development server
• next build: Build for production
• next start: Start a production server
• next lint: Run ESLint checks
• next export: Export as static HTML (being replaced by output: 'export')
• next info: Print environment information
• next telemetry: Manage telemetry settings

These commands can be run directly using npx, yarn, or through npm scripts defined in your package.json file. Understanding these commands and their options will help you efficiently develop, debug, and deploy your Next.js applications.

Additional Resources

• Next.js CLI Documentation
• Next.js Custom Server Documentation
• Next.js Deployment Documentation

Exercises

1. Create a new Next.js project using create-next-app and start the development server on port 4000.
2. Add a custom script in your package.json to build and export your application as static HTML.
3. Run the Next.js linter with the --fix option to automatically fix linting issues.
4. Set up a custom script that combines building and starting the application in a single command.
5. Use the next info command to check your environment details and verify your Next.js version.