Deploy a static Next.js site to Netlify (with Git LFS)
Tags: netlify, nextjs, gitlfs
Published: 2021-01-29 05:54:01

This is a quick note on how to deploy your _static_ Next.js site with Netlify. 

## Step 1: Prepare the build script
In `package.json`, add (or revise) the `build` script as follows:
```json
{
  ...

  "scripts": {
    ...

    "build": "next build && next export",

    ...
  }
}
```
Note: `...` indicates other lines of code in the `package.json` file.

For detail, see [Vercel (2021)](https://nextjs.org/docs/advanced-features/static-html-export).

## Step 2: Push to the main branch

Don't forget to push the changes in `package.json` to the GitHub repo. Netlify won't look into your local repo. :-)

## Step 3: Configure Netlify's "build settings"

On your Netlify user dashboard, find the build settings in the Netlify user dashboard by following this help document: [Netlify (2021b)](https://docs.netlify.com/configure-builds/get-started/#basic-build-settings).

Then set
- Build command: `npm run build`
- Publish directory: `out`

as suggested by [Netlify (2021a)](https://docs.netlify.com/configure-builds/common-configurations/#next-js).

## Step 4 (optional): Turn on the Git LFS feature of Netlify

If you are using Git LFS, you need to tell Netlify to obtain all the assets stored with Git LFS. 

On your Netlify user dashboard, find the "Environment variables" section by clicking "Site settings" on the top menu bar, and then "Build & deploy" in the left column menu, and then "Environment". (See [Netlify 2021c](https://docs.netlify.com/configure-builds/environment-variables/#declare-variables) for detail.)

Click the "Edit variables" and set "GIT_LFS_ENABLED" as key and "true" as value.

By doing this, Netlify will “use `git lfs clone` to check out your repository — otherwise we just use `git clone`” (quoted from [Netlify 2021d](https://docs.netlify.com/configure-builds/environment-variables/#netlify-configuration-variables)) when cloning your GitHub repo.

If the cloning fails during the deployment, it's most likely that your large files haven't been pushed to the GitHub's LFS server (as it happened to me). To push all your LFS-tracked files, run
```
git lfs push --all origin
```
from your local repo ([GitHub 2021](https://docs.github.com/en/github/managing-large-files/resolving-git-large-file-storage-upload-failures)).

---

Now your Next.js site should be deployed successfuly with Netlify!

It took more than an hour for me to figure this out, as neither Next.js nor Netlify clearly indicates where we can find this information in their documentation. Netlify claims it's super easy to deploy your site. After I've figured it out, it is indeed not super complicated. It's just that Netlify's user dashboard UI is not very easy to use, and its help document is not clear enough about where to find relevant information.

If you use server-side rendering, it seems to be a totally different story. See [Netlify (2021a)](https://docs.netlify.com/configure-builds/common-configurations/#next-js).

I've chosen Netlify, not Vercel, to deploy my Next.js app, because I want to use Git LFS. Vercel is not capable of handling Git LFS. I have requested this feature along with several others; no response yet. For the latest, see [Vercel GitHub issue #3716](https://github.com/vercel/vercel/discussions/3716).