Getting a Next.js project running locally is a practical first step toward building with React. You need a supported Node.js version, the project’s dependencies, and the right development command. This guide walks through creating a project or starting an existing one, opening it in your browser, configuring environment variables, and fixing common setup errors.
Key takeaways
- Install a Node.js version supported by the Next.js release you plan to use; npm is included with Node.js.
- Use
npx create-next-app@latestto create a project, or install dependencies in an existing project. - Run
npm run devfrom the project directory and open the local address printed in your terminal. - Keep private values out of browser-exposed environment variables and source control.
Check the prerequisites
Before installing a project, make sure Node.js and npm are available in your terminal. Next.js requirements can change between releases, so check the current official installation guide for the minimum supported Node.js version. Installing a current Node.js LTS release is a sensible starting point, provided it meets that requirement.
Check your installed versions with:
node --version
npm --version
If either command is not recognized, install Node.js from its official website, then close and reopen your terminal so its updated PATH is loaded. The npm version may differ from examples in tutorials; that alone does not mean your setup is broken.
Create a new Next.js project
From the directory where you keep your development projects, run:
npx create-next-app@latest my-next-app
npx runs the project creation command without requiring you to install it globally. The command may ask about options such as TypeScript, a linter, Tailwind CSS, and the App Router. If you are learning, the defaults are generally fine; you can accept them or choose options that match your project.
When setup finishes, move into the new project directory:
cd my-next-app
The generated project includes a package.json file. Its scripts define commands for common tasks, including starting the development server.
Install and run an existing project
For a project you already have—such as one you cloned from a repository—open a terminal in its root directory. You should see a package.json file there. Install the dependencies declared by the project:
npm install
Then start the development server:
npm run dev
Run both commands from the project directory. If the project uses a different package manager, follow its README and use the matching lockfile and commands instead. For example, a repository with a pnpm-lock.yaml is typically set up with pnpm rather than npm; avoid mixing package managers unless the project instructions say to.
Open the project at localhost
After npm run dev starts successfully, the terminal prints a local address. In a typical setup, open http://localhost:3000 in your browser. The terminal output is authoritative: if port 3000 is already in use, Next.js may offer or select another port and print a different address, such as http://localhost:3001.
Keep the terminal process running while you work. In many cases, changes to application files appear in the browser without restarting the server. To stop the server, focus the terminal and press Ctrl+C on Windows, Linux, or macOS.
Configure environment variables
A project may need local configuration such as an API base URL or a development-only key. Next.js can load environment variables from files such as .env.local in the project root. For example:
# .env.local
API_BASE_URL=https://api.example.test
Read a server-side variable in application code with process.env.API_BASE_URL. Use a NEXT_PUBLIC_ prefix only for values that are intentionally available to browser-side code. Variables with that prefix can be included in the client bundle, so never use it for passwords, private API keys, or other secrets.
Check that .env.local is excluded from version control before adding sensitive values. Many Next.js starter projects configure this already, but confirm the project’s .gitignore. If you add or change environment variables while the development server is running, restart it so the new values are loaded. Consult the official environment variables documentation for details about variable loading and exposure.
A simple setup workflow
Use this sequence when you are starting from scratch:
- Install a supported Node.js version and verify it with
node --version. - Create a project with
npx create-next-app@latest my-next-app. - Enter the project directory with
cd my-next-app. - Start the development server with
npm run dev. - Open the exact local URL printed in the terminal.
- Add local configuration to
.env.localif the project needs it, and restart the server after changing values.
For an existing project, begin by opening its root directory, installing dependencies with the package manager indicated by its documentation or lockfile, and then running the dev script listed in package.json.
Common errors and how to fix them
node or npm is not recognized
Node.js may not be installed, or your terminal may not have refreshed its PATH. Install Node.js, reopen the terminal, and rerun the version checks. If you use a version manager, confirm that the intended Node.js version is active in this shell.
The project requires a different Node.js version
A newer or older project can require a different Node.js version than the one currently active. Check the project’s README, package.json engine requirements if present, and the official Next.js requirements. Switch to a compatible version rather than trying to work around the mismatch.
npm run dev reports a missing script
Make sure you are in the directory containing the project’s package.json. Open that file and look for a dev entry under scripts. If it is absent, follow the repository’s setup instructions; do not assume every JavaScript project is started with the same command.
Dependencies are missing or installation fails
Run the install command from the project root and read the first meaningful error in the terminal. Check that you are using the package manager expected by the project and a compatible Node.js version. If dependencies remain inconsistent, consult the project’s instructions before deleting lockfiles or reinstalling packages, since those files help keep installs reproducible.
Port 3000 is already in use
Another local process may be using that port. If Next.js prints a different available address, open that address instead. Otherwise, stop the other development server if you recognize it, or follow your operating system’s normal process-management steps. Do not terminate an unfamiliar process without checking what it does.
The page loads but configuration is missing
Confirm that .env.local is in the project root, the variable name matches the code exactly, and the development server was restarted after the file changed. Do not add a secret to a NEXT_PUBLIC_ variable to make it available in client-side code; keep private operations on the server.
Common setup mistakes
- Running commands from a parent folder instead of the directory containing
package.json. - Opening a guessed port instead of the URL printed by Next.js.
- Mixing npm, pnpm, and Yarn in a project without checking its lockfile or documentation.
- Committing
.env.localor exposing private values with aNEXT_PUBLIC_prefix. - Treating a running development server as a production deployment. The development command is intended for local work; use the project’s production build and deployment process when preparing a release.
Conclusion
To run a Next.js project locally, install a compatible Node.js version, create or open the project, install its dependencies, and start the dev script from the project root. Use the address shown in the terminal, keep local secrets in non-public environment variables, and consult the project’s documentation when its setup differs from the standard workflow.