How to deploy NextJS with Cypress to AWS Amplify

I thought it should be pretty straightforward, since the AWS amplify documentation mentions it supports NextJS out of the box. However, when I try to deploy a frontend in NextJS, it always got stuck at the testing stage and the log message isn’t helpful at all. Took me a while to find a solution, and here is the fix.

For this tutorial, I’m going to deploy Docubot, a documentation creation software I had created with NextJS. It parses markdown files from another github repository, and presents it in a user friendly format website with navigation. In my case, it is some notes of my Kotlin learnings which is still work-in-progress. It is something like readthedocs and jekyll, but it’s fuss-free, without the need to use front matters or read any guide in order to use. Simply put the sequence in the folder and file names to get the navigation working. I’ll blog more about it next time.

When I linked my NextJS repository to amplify, the amplify.yml generated by default is as below:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
test:
  artifacts:
    baseDirectory: cypress
    configFilePath: '**/mochawesome.json'
    files:
      - '**/*.png'
      - '**/*.mp4'
  phases:
    preTest:
      commands:
        - npm ci
        - npm install wait-on
        - npm install pm2
        - npm install mocha mochawesome mochawesome-merge mochawesome-report-generator
        - npx pm2 start npm -- start
        - 'npx wait-on http://localhost:8080'
    test:
      commands:
        - 'npx cypress run --reporter mochawesome --reporter-options "reportDir=cypress/report/mochawesome-report,overwrite=false,html=false,json=true,timestamp=mmddyyyy_HHMMss"'
    postTest:
      commands:
        - npx mochawesome-merge cypress/report/mochawesome-report/mochawesome*.json > cypress/report/mochawesome.json
        - npx pm2 kill

One problem I immediately noticed is npx wait-on http://localhost:8080. NextJS uses port 3000. So i tried to correct it to use port 3000, but it always got stuck in the testing stage without any useful error messages. I think it got stuck waiting on http://localhost:3000 forever.

The solution is to use the static html export from NextJS. So instead of running cypress on the next start, I added an export script in my package.json to build and export the generated site to the default out folder.

https://github.com/thecodinganalyst/docubot/blob/master/package.json

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "export": "next build && next export"
  },

So I have to modify my amplify.yml build script to run npm run export instead of npm run build

https://github.com/thecodinganalyst/docubot/blob/master/amplify.yml

build:
      commands:
        - npm run export

I’ll also need to edit the test script section of amplify.yml to install http-server, as described in my previous post - Simple http server to test Angular production build. As http-server uses port 8080 by default, the wait-on will need to be changed back to 8080 too.

phases:
    preTest:
      commands:
        - npm ci
        - npm install wait-on
        - npm install pm2
        - npm install http-server
        - npm install mocha mochawesome mochawesome-merge mochawesome-report-generator
        - npx pm2 start http-server -- ./out
        - 'npx wait-on http://localhost:8080'

And we’ll also need to inform cypress to run the tests on port 8080 instead of port 3000.

{
  "baseUrl": "http://localhost:8080",
  "nodeVersion": "system",
  "env": {
    "GH_API_PERSONAL_ACCESS_TOKEN": "GET_YOUR_OWN_TOKEN_FROM_https://github.com/settings/tokens/new?scopes=repo",
    "GH_REPO": "/thecodinganalyst/hellokotlin"
  }
}

That’s it! The next time AWS Amplify runs, it succeeds. Though I still don’t know why the next start doesn’t run. The full amplify.yml is available on https://github.com/thecodinganalyst/docubot/blob/master/amplify.yml.

Meanwhile, if you are trying to run my sample NextJS application - Docubut, do note that you’ll need to create and specify a github personal access token (how to: https://github.com/settings/tokens/new?scopes=repo, and the github repo (sans the https://github.com) in the .env and cypress.json. Or you can just specify the environment variables in the App Settings > Environment Variables within the AWS Amplify portal. The names of the environment variable are as specified in the .env.