Introducing Upgraded Build Instances on Amplify Hosting

AWS Amplify Hosting has built web applications using a fixed instance environment. As applications grow more complex and require intensive build processes for dependency management, asset optimization, and comprehensive testing, developers need more powerful build environments to maintain productivity and deployment speed.

Today, we’re excited to introduce customizable build instances for Amplify Hosting. This update adds two new instance sizes: Large and XLarge, both offering increased memory and CPU resources. Development teams can now scale their build resources to match their specific needs. This is especially useful when handling large dependency trees, processing numerous static assets, or running memory-intensive operations like TypeScript compilation and parallel testing frameworks.

Challenges with Fixed Size Build Instance

Customers building large applications and running heavier workloads experience increased build times, slow CI/CD and build failures due to memory errors. As development teams adopt Amplify Hosting, they expect scalable build environments that can match a variety of workloads. While build time optimizations exist, applications cannot grow within a fixed instance size container configuration of 8GiB memory and 4 vCPUs. Virtual memory (swap space) introduces significant performance penalties compared to physical memory, and no effective alternatives exist for expanding compute capacity or storage within a fixed environment. These hardware limitations create fundamental barriers that software optimizations alone cannot overcome.

Build Instance Specifications

Introducing Customizable Build Instances

Amplify Hosting’s new customizable build instances allow developers to select the computing resources that best match their application needs. This allows achieving predictable build performance by eliminating resource constrains. In addition to our Standard build instance, we are introducing Large and XLarge instances. The following table summarizes the specifications of all of Amplify Hosting’s build instance offerings:

You can configure build instances at the application level either during the app creation or later udpating your existing applications. Updated configuration will extend to all of your app’s branches and change an app’s build instance size across builds. Any build running for the app, irrespective of the branch, will use the build instance size that you configured at the app level when you triggered the build. You can configure build instance size when creating a new app or updating an existing app.

• To customize build instance size for a new app via Amplify console: During the App Settings step, scroll down and click on Advanced settings. From the drop down list, select the Build Instance type you would like to configure for your app.

Figure 1 – Configure build instance size for a new app

• To customize build instance size for an existing app via Amplify console: Navigate to your app, open the Hosting tab, and select Build Settings. Scroll down to Advanced settings and click Edit. From the drop down, select the Build Instance type you would like to update your app with.

Figure 2 – Modify build instance for an existing app

Note: Build instance allocation process can require additional provisioning time before your build starts. For larger instances, especially XLarge, your build might experience latency before the build starts, due to this overhead time. However, you are billed only for the actual build time, not the overhead time.

Performance Testing Explanation

Now we will demonstrate the value of more powerful instances by using a Next.js application that generates more than 100 static pages. We will walk you through the deployment of this app on Amplify Hosting, show you how to debug memory-related build failures, and teach you how to upgrade the build instance to meet your application’s memory needs.

Deploying an application to Amplify HostingWe will first deploy the static app using the default settings:

Figure 3 – Review and create an app page

Once the deployment starts, Amplify Hosting provision the resources and carry the deployment further:

Figure 4 – Deployment in progress

Configuring app to use large memory

After deployment starts, our app will fail its first build due to JavaScript heap out of memory issue. The runtime environment requests the heap memory, and the host operating system should allocate it. The JavaScript Node.js V8 runtime environment enforces a default heap size limit, which depends on several factors including the host memory size. That is why Standard and Large build instances use a default Node.js heap size of 2096 MB, while the XLarge instance uses a default heap size of 4144 MB.

Figure 5 – Deployment 1 failed due to heap size memory limit

We can solve the conservative Node.js default heap memory limit issue by increasing the heap size. Since the app is using Standard build instance with 8 GiB memory, we will need to increase the heap size to 7000 MB which is ~7 GB. This leaves approximately 1 GB memory for operating system to use for other processes and avoids unintended behavior.

Next, we will modify the build specification with the following command to increase Node.js heap memory limit.

export NODE_OPTIONS='--max-old-space-size=7000'

Alternately, NODE_OPTIONS can also be set as an environment variable in our app. Refer documentation for more details.

We will also update the build spec file as following to accommodate these changes in our build flow:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        # Set the heap size to 7000 MB
        - export NODE_OPTIONS='--max-old-space-size=7000'
        # To check the heap size memory limit in MB
        - node -e "console.log('Total available heap size (MB):', v8.getHeapStatistics().heap_size_limit / 1024 / 1024)"
        - npm ci --cache .npm --prefer-offline
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - .next/cache/**/*
      - .npm/**/*

We will trigger a new deployment with the modified heap size by going to the Deployments page and clicking on Redeploy this version button

However, the app still fails to build. This time, we see a log stating “Total available heap size (MB): 7048” that confirms our increased heap size. Interestingly, we also see a SIGKILL directive that indicates the operating system forcefully terminated the build process. This indicates another out of memory error.

Figure 6 – Deployment 2 failed due to out of memory

Upgrading build instance

Standard instance has a memory limit of 8 GiB and despite increasing the heap size close to this limit. Because of that, we are still running out of memory. We can solve this issue by upgrading our build instance to Large. This way we will allocate more memory to our build process.

We will update the build spec file as following to deploy on Large instance:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        # Set the heap size to 14000 MB
        - export NODE_OPTIONS='--max-old-space-size=14000'
        # To check the heap size memory limit in MB
        - node -e "console.log('Total available heap size (MB):', v8.getHeapStatistics().heap_size_limit / 1024 / 1024)"
        - npm ci --cache .npm --prefer-offline
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - .next/cache/**/*
      - .npm/**/*

We will update the build instance by opening the Hosting tab, and selecting Build settings. Afterwards, scroll down to Advanced settings and clicking on Edit. From the drop down, select the Build instance type as Large.

Figure 7 – Update build instance size to Large

Next, on the Deployments page, we will click on Redeploy this version to create a new deployment with Large instance. We also notice the first log line in build logs showing the build instance specifications.

Figure 8 – Deployment 3 in progress on Large build instance

We can see that our app is deployed successfully.

Figure 10 – App is deployed

Conclusion

In this blog, we have explored how you can create and update app workflows for configuring build instance sizes and demonstrated how you can solve memory issues in your projects hosted by Amplify Hosting. To explore further about build instance sizes and learn more about this feature, check out the Amplify Hosting documentation. For information on pricing for build instances, you can check our pricing page.

About the Authors

Sohaib Uddin Syed, Software Engineer, Amplify Hosting

Sohaib Uddin Syed is a Software Development Engineer at AWS Amplify Hosting. Sohaib builds software that enables customers to build their front-end web applications using the scalability of AWS. In his free time, Sohaib enjoys watching football (soccer), cooking and spending time with family and friends.

Angela Zheng, Software Engineer, Amplify Hosting

Angela Zheng is a Software Development Engineer at AWS Amplify Hosting. She works on creating features that make hosting front-end web applications accessible and straightforward for developers at any scale. In her free time, she enjoys dancing, playing a game of volleyball, experimenting with recipes in the kitchen, and traveling.

Matt Auerbach, Sr Product Manager, Amplify Hosting

Matt Auerbach is a NYC-based Product Manager on the AWS Amplify Team. He educates developers regarding products and offerings, and acts as the primary point of contact for assistance and feedback. Matt is a mild-mannered programmer who enjoys using technology to solve problems and making people’s lives easier. B night, however…well he does pretty much the same thing. You can find Matt on X @mauerbac. He previously worked at Twitch, Optimizely & Twilio.