A good gitignore for Next.js


There are a few common files that should be ignored for every Next.js project. We give a recommended configuration for working with git in Next.js projects

What should you gitignore with Next.js

While developing locally Next.js will generate a directory .next/ which contains the files that get served to your browser. This set of files will also be generated at built time (with more optimizations). Since the next build step should occur in your continuous integration (CI) pipeline you don’t need to commit them to source control.

As Next.js is based on Node.js you’ll also need to ignore the node_modules/ directory. Some other common things to ignore are .env files, so you don’t leak secrets into source control.

What should you not gitignore with Next.js

You definitely do not want to ignore a few things in the project. Firstly do not ignore the lock file (eg yarn.lock or npm-lock.json). These are important for having consistently installed dependencies.

If you are using Typescript with Next.js you also want to be sure not to ignore the tsconfig.json file that Next.js will automatically generate for you since that will be needed to reliably compile the Typescript application back down to Javascript.

Sample gitignore

Probably the best maintained gitignore for node applications can be found here:


The main pieces that are relevant to Next.js if you want a smaller config are:

// .gitnignore
# next.js build output

# dotenv environment variables file (build for Zeit Now)

# Dependency directories

# Logs

You'll notice that we've added .env and .env.build while .env is a super common way to add env variables .env.build is a file specifically for Zeit now to be able to load different variables to Next.js when building for production. This can come in handy if say you have a local test database and you want to give Next.js a different database target for testing / production (a good practice).

Other github goodies (eg. Github Actions)

Github's new Actions product is a great way to run Continuous Integration tasks if you are already using Github. It seamlessly integrates with the Pull Request workflow and there are constantly new Actions being developed. Here is a sample workflow for Next.js that we use to build this site:

name: CI

on: [push]

    runs-on: ubuntu-latest

      - uses: actions/checkout@v1

      - name: Deploy for staging
          BUILD_ID: ${{ github.sha }}
          ZEIT_TOKEN: ${{ secrets.ZEIT_TOKEN }}
        run: >
          now deploy
          --build-env NODE_ENV=production
          --build-env BUILD_ID=${BUILD_ID}
          --env NODE_ENV=production
          --token ${ZEIT_TOKEN}
          > ${HOME}/deployment-url.txt

      - name: Alias with PR number
          ZEIT_TOKEN: ${{ secrets.ZEIT_TOKEN }}
        run: >
          now alias
          --token ${ZEIT_TOKEN}
          `cat ${HOME}/deployment-url.txt`
          ${{ github.event.repository.name }}-pr.now.sh

      - name: Use Node.js
        uses: actions/setup-node@v1
          node-version: 10.16.x

      - name: Install Packages
        run: yarn

      - name: Run cypress tests
        run: >
          yarn cypress:run
          CI: true
          CYPRESS_baseUrl: https://${{ github.event.repository.name }}-pr.now.sh

      - name: Run Jest tests
        run: >
          yarn test

To use the same configuration you'll have to be using Zeit Now for deploys and then add a Zeit token into the settings of your repository in Github.

This workflow also features using Cypress to test the application on the temporary deployed version.

Zeit's Github Integration

If you are deploying your project on Zeit Now then you can opt in to their github integration which for Next.js applications comes with a bunch of goodies. The most basic thing is that whenever you push your code it will deploy your application to a separate testing url. You can see above we use that test URL to perform our end-to-end tests on a real production deployment. Then when your merge your Pull Request Zeit will alias that test url to the production one automatically.

Another great feature of that can be added to Github Actions is Next.js page diff previews. Which will give you a preview of the pages in your Next App that changed with your deployment.