How to Upgrade Node.js Version in Amplify Build

Introduction

Deploying Next.js applications on AWS Amplify can sometimes present unforeseen challenges, especially when you have complex dependencies that require specific runtime versions. One such obstacle involves the jwt-decode package requiring Node.js version greater than 18, while the default configuration on Amplify is set to Node.js version 16. This discrepancy leads to build failures, leaving developers scratching their heads. In this blog post, we'll explore a solution to this common issue that leverages the latest capabilities offered by AWS Amplify.

Understanding the Issue

The jwt-decode package, a common utility in modern web applications for decoding JWT tokens, necessitates Node.js version 18 or higher. AWS Amplify, which automates the build, deploy, and hosting processes for web applications, defaults to Node.js version 16. Additionally, AWS environments traditionally run on Amazon Linux 2, which has not supported the GLIBC version required by more recent versions of Node.js.

This created a difficulty, as developers were left with few options; using custom Docker images with the required Node.js version was a possible workaround, but this came with the risk of relying on third-party configurations that may not be secure or stable.

A Timely Solution

Thankfully, AWS has been responsive to the developer community's needs. In a recent discussion on GitHub, AWS announced support for Node.js version 18.13.0, circumventing the GLIBC version issue. To leverage Node.js 18.13.0 in your Amplify build, you need to adjust both your build settings and the amplify.yml configuration file.

How to Fix the Build Issue

1. Access the Amplify Console in your AWS account and navigate to your application.
2. Click on App settings and then Build settings.
3. Edit the Build image settings to specify the Node.js runtime version. Set the version to 18.13.0.

Next, modify your amplify.yml file, which controls the build process. Add a new build step that invokes nvm use 18 to ensure the appropriate Node.js version is active during the build process.

Here's an example snippet of how the amplify.yml could look:

version: 1
backend:
  phases:
    build:
      commands:
        - nvm use 18
        - '# Execute Amplify CLI with the helper script'
        - amplifyPush --simple
frontend:
  phases:
    preBuild:
      commands:
        - yarn install
    build:
      commands:
        - env | grep -e DATABASE_URL >> .env.production
        - yarn run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

Once you submit these changes, trigger a new build with AWS Amplify. Monitor the build process in the Amplify Console. If all goes well, the build should succeed with the necessary Node.js version in place, and your jwt-decode dependency should operate without issue.

Conclusion

Resolving build issues due to Node.js version incompatibility in AWS Amplify requires staying informed about AWS updates and modifications to both build settings and the amplify.yml file. By following the steps above, developers can successfully deploy Next.js applications that depend on the jwt-decode package or any other packages requiring newer Node.js versions. Remember to always keep an eye on official AWS documentation and community forums for the latest best practices and fixes for building and deploying your applications on the cloud.

As technologies evolve, it is always best to consult the official AWS documentation or relevant GitHub issues for the most up-to-date solutions to technical issues.