How to install Next.js on Node.js 20 LTS

Create a new Next.js application and start the development server on your Ubuntu 24.04 VPS. These steps use Node.js 20 LTS and the official create-next-app tool to generate a production-ready project structure.

Prerequisites

• Ubuntu 24.04 (Jammy) or Debian 12 (Bookworm) server with root or sudo access.
• Node.js version 20.x installed (Node 20.11.0 or higher recommended for Next.js 14).
• NPM 10.x or Yarn 1.22+ installed globally.
• A domain name pointing to your server IP address.
• At least 2GB of free disk space in the home directory.

Step 1: Update system packages

Ensure your package manager is up to date before installing new software. Run the following command to refresh the APT cache and upgrade existing system packages.

sudo apt update && sudo apt upgrade -y

You will see a list of packages being upgraded. Press Enter to confirm the installation and wait for the process to complete.

Step 2: Verify Node.js and NPM versions

Check that you have the correct version of Node.js and NPM installed. Run the following commands to display the versions. Next.js 14 requires Node.js 18.17 or 20.11 or higher.

node -v
npm -v

You should see output similar to v20.11.0 for Node and 10.2.4 for NPM. If your versions are lower, install Node.js 20 LTS from the official NodeSource repository first.

Step 3: Create a new Next.js project

Use the official create-next-app tool to scaffold a new project. This command downloads the latest Next.js template and installs it into a new directory. Run the following command in your terminal.

npx create-next-app@latest my-next-app --typescript --eslint --tailwind --app --src-dir --import-alias "@/*"

When prompted, press Enter to accept the default settings. The tool will create a directory named my-next-app and install all necessary dependencies. This process may take a few minutes depending on your internet connection speed.

Step 4: Navigate to the project directory

Change your current directory to the newly created project folder. Use the cd command to move into the directory and verify you are inside the project root.

cd my-next-app
ls -la

You will see a directory listing containing files like package.json, tsconfig.json, and the src folder. This confirms the project structure was created correctly.

Step 5: Install dependencies

Install all the packages listed in your package.json file. This step downloads Node modules required to run the application. Run the following command to install dependencies.

npm install

Wait for the process to finish. You will see a progress bar and then a message stating that dependencies were successfully installed. If you have a large project, this may take several minutes.

Step 6: Start the development server

Launch the Next.js development server to test your application. Run the following command to start the local server.

npm run dev

The terminal will display a URL like http://localhost:3000. Open this URL in your browser to see the default Next.js welcome page. The server will show a warning about the development environment, which is normal.

Verify the installation

Confirm that the Next.js server is running and responding to requests. Open your browser and navigate to http://localhost:3000. You should see the default Next.js welcome page with the Next.js logo and text. Alternatively, use curl to check the response.

curl http://localhost:3000

The output should contain the HTML content of the default page. This confirms that Next.js is installed correctly and the development server is functioning.

Troubleshooting

Here are common errors you might encounter during installation or execution.

Error: "node:internal/modules/cjs/loader: Cannot find module"

This error usually means Node.js is not installed or the path is incorrect. Verify the installation by running node -v. If Node.js is missing, install it from NodeSource. Ensure you are running the command in the correct directory where package.json exists.

Error: "npm ERR! code ENOENT"

This indicates that a package cannot be found in the registry. Check your internet connection and ensure you are not behind a corporate proxy. Try clearing the npm cache with npm cache clean --force and reinstalling dependencies.

Error: "Port 3000 is already in use"

Another application is occupying port 3000. Kill the process using that port or change the port in your package.json file. Find the process ID with lsof -i :3000 and terminate it with kill -9 PID.

Error: TypeScript compilation fails

If you see TypeScript errors, check your tsconfig.json file for syntax mistakes. Ensure all dependencies are listed in package.json. Run npm install again to ensure all types are downloaded correctly.

Error: Tailwind CSS not loading

Ensure that tailwindcss is listed in the dependencies. Run npm install tailwindcss postcss autoprefixer to add the missing packages. Then run npx tailwindcss init to create the configuration files.