Deploy a Next.js project to Netlify using GitLab CI

Next.js from Vercel and it has great support on hosting the project without hassle. Netlify is also a JamStack hosting platform and have git based build and deployment support without much hassle too.

GitLab CI is the go to CI platfrom since we have moved our projects to GitLab. From building docker images to deploying to Google Cloud Run is handled by GitLab CI. Setup a yaml based config file and GitLab take care of the rest.

All above mentioned services has a generous free tier.

Netlify support CLI based manual deployments. After doing some research I managed to get up and running with GitLab CI.

Since Next.js support exporting static web sites and SSR based deployments I will explain the both.

If you don't have account in Netlify please create one and create personal access token from User settings > Applications.

You also need to create a Netlify site to deploy. The way I do it is, install the Netlify CLI in your device.

yarn global add netlify-cli

After that login to your account from CLI by

netlify login

After that you can create the project from CLI. (Since to create a project from UI you need to connect a git repository.)

netlify sites:create --disable-linking

This is an interactive command you have to select your team and give a name your site. Recent update of CLI has linking the site to current directory which we don't need since we do it from the CI.

After that your will get the site id in the result. Copy it.

Then these environment variables needs to be saved in Gitlab project > Settings > CI/CD > Variables.

NETLIFY_SITE_ID: <site id of the created site>
NETLIFY_AUTH_TOKEN: <personal access token>

Above variables are mandatory to deploy the project. You can set them in the .gitlab-ci.yml too but not recommended.

Deploying static Next.js based site

Next.js has support to generate complete static websites. But there are some limitations, Like internationalization, next/image component are not supported.

First add these scripts to you package.json

"scripts":{
    "build": "next build",
    "export": "next export"
}

Now create netlify.toml file in the root of the project.

[build]
command: "yarn build && yarn export"
publish: "out"

Next create or add following task to your .gitlab-ci.yml file.

stages:
  - deploy

deploy-to-netlify:
  stage: deploy
  only:
    refs:
      - master    
  image: node:lts
  variables: 
    - NETLIFY_USE_YARN: true
    - NEXT_TELEMETRY_DISABLED: 1
  cache:
    paths:
      - .yarn
      - /.next/cache
  before_script:
    - yarn global add netlify-cli
    - yarn install --frozen-lockfile --non-interactive --prefer-offline --cache-folder .yarn
  script:
    - netlify deploy --prod --build

This task will run in master branch when commits are pushed.

Deploy dynamic Next.js project.

Netlify has Essential Next.js Build Plugin which we can use. It supports image optimazation now out of the box. I'm going to use the v4 which is currently in beta which also support Next.js 12.

First we need to install the Essential Next.js Build Plugin as a dev dependancy.

yarn add @netlify/plugin-nextjs -D

After that you need to update netlify.toml as the following.

[build]
command = "yarn build"
publish = ".next"

[[plugins]]
package = "@netlify/plugin-nextjs"

All other files are remain the same.