How to set up a Next.js Project


We'll walk through the first steps that you should take with a new Next.js project, from installing the package to getting your dev server running, and some common companion things to set up such as linting.

Installing Next.js

To get started start a new project in a folder name of your choice, we'll call ours next-project. Initialize the project with either NPM or Yarn (we prefer yarn so will show that).

yarn init -y

Then go ahead and install Next.js along with React:

yarn add next react react-dom

Then add a few scripts to your package.json:

// package.json

  "name": "next-project",
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  "dependencies": {
    "next": "^9.1.3",
    "react": "^16.10.2",
    "react-dom": "^16.10.2"

To get things kicked off we are going to create a hello world page at the root of our application. First create a /pages directory:

// pages/index.js

export default () => <div>Hello World!</div>

Running locally

To see our application running locally you simply need to run yarn dev to run the next script which will spin up a development server on your machine. There are a few things to keep in mind while running Next.js locally:

  • Next does not respect cache headers when running locally
  • Next will not pre-fetch pages
  • Next won't have pre-built a full bundle of all the pages, it does that on the fly as you visit them (to make the DX snappier by default).

You can point your browser to [localhost:3000](http://localhost:3000) (or another port if that one was blocked by another application you have running) and then you should be able to see hello world at the top of the screen.

Linting / Formatting

Probably the first thing you want to do is get a code-linter and formatter set up with your Next.js project to keep the javascript looking sane. The usual recommendations here are to use Eslint + Prettier. There are many presets for Eslint, but a simple place to start is with something like Wesbos' configuration. Just add yarn add --dev eslint prettier eslint-config-wesbos and add a simple .eslintrc configuration:

  "extends": ["wesbos"],
  "rules": {
    "no-console": 2,
    "prettier/prettier": [
        "trailingComma": "es5",
        "singleQuote": true,
        "printWidth": 120,
        "tabWidth": 8

It's a good idea to pick prettier / eslint configurations that work for you, they can save you a lot of headache down the road. Especially the recent additions to the react eslint library will warn you on things that are actually possibly wrong with your code (like missing dependencies in hooks). These tools are a great way to keep your code clean.

You'll probably also want to set up either some kind of format-on-save in your code editor + some kind of assurance that the code you ship into source control has been formatted correctly. There are a couple of approaches to the source control piece:

  • run tests eg through Jest to test that your files are all compliant with the lint rules
  • add a pre-commit hook with Husky to enforce that all commits conform to lint rules

You may want both of these, but in a small project I typically prefer either just relying on the IDE (if it's just me) or with a small team using Husky alone (since folks know not to skip the hook). In a large project it probably also warrants running the linting through continuous integration, but this will add a bit of time to the process.

Create Next App

Create Next App is another great way to quickly bootstrap a Next.js project. You can even point it at any of the examples in the Next.js examples directory if you know you will be needing a specific setup.

Next.js does not have a plugin ecosystem, instead relying on reference implementations of various integrations (eg like graphql, custom style libraries, database integrations etc). These are a great way for the Next.js team to show off capabilities and best practices without having to build a ton of plugins. However, the cost is that if you develop a somewhat common workflow for Next.js projects you will inevitably write the same boiler plate many times. So we would recommend taking your common stack (eg database / data layer / linting settings / testing framework) and creating your own boiler plate out of them. It also often can help you to debug issues in your application that are related to your specific set up (eg styled-components has some conflict) that might not be related to specific things you are doing in the actual pages/

That being said, to get started with create-next-app you simply use npx :

npx create-next-app with-apollo

Here we're using the with-apollo example as a starting point for our application (say we are using graphql). This will generate the whole example project for us as a starting point and we can get started developing with the usual yarn dev.