Who This Is For

If you are new to AWS and thinking of using Amplify to deploy your app, this blog is for you.

Amplify is marketed as an easy, all-in-one deployment platform. And for simple use cases, it is. But once you start pushing it a little : different package managers, larger projects, custom configurations : you start running into walls that are not mentioned anywhere in the getting started guides.

I have spent a lot of time deploying different kinds of applications on Amplify. I have hit these walls firsthand. This blog is a collection of the things I discovered the hard way, explained simply, so you do not have to go through the same debugging sessions.

A Quick Intro to AWS Amplify for Beginners

Before we get into the issues, here is a quick explanation of what Amplify actually is.

AWS Amplify is a hosting and deployment platform from Amazon Web Services. You connect your GitHub repository to Amplify, and every time you push code, Amplify automatically builds and deploys your app. It handles the servers, the CDN (Content Delivery Network : the system that delivers your app quickly to users around the world), and the deployment pipeline for you.

It sounds perfect. And for many projects, it works well. But here are the things you need to know before you go all in.

Issue 1: The Cache Feature Does Not Actually Help

The Problem

Amplify has a built-in caching feature. In theory, it saves folders like node_modules (the folder where all your app's dependencies or packages live) between builds. The idea is that on the next build, those packages are already there and do not need to be downloaded again, making the build faster.

In practice, the opposite happens.

Amplify's cache works by zipping up the folder and uploading it to storage after a build, then downloading and unzipping it before the next build. This zip and unzip process itself takes significant time — in my experience, around 3 minutes to restore and 3 minutes to save.

Now here is the deeper problem. The two most common commands used to install packages are:

npm ci : This is the recommended command for automated deployments. It deletes node_modules completely and reinstalls everything from scratch every single time. It does not matter that Amplify just spent 3 minutes restoring that folder. npm ci will delete it immediately.

npm install: This one does not always delete node_modules, but it re-evaluates your packages and may reinstall parts of it anyway.

In both cases, the cache Amplify restored is either deleted immediately or partially ignored.

I ran experiments on both large projects and minimal ones. The result was consistent — removing the cache made builds faster, not slower.

The Solution

Remove the cache section from your amplify.yml file entirely. Here is what a clean build config looks like without cache:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: build
    files:
      - '**/*'

No cache block. Cleaner, faster, simpler.

Issue 2: The 220MB Artifact Size Limit

The Problem

Amplify has a hard limit on the size of your build artifacts. Artifacts are the files produced after your build, things like your compiled JavaScript, CSS, images, and in some cases the node_modules folder if your app needs it at runtime.

The limit is 220MB.

This sounds like a lot until you are building a Next.js app (a popular React framework) with server-side features. Next.js SSR (Server-Side Rendering — where pages are generated on the server instead of the browser) requires parts of node_modules to be bundled with the output. A medium-sized project can easily exceed 220MB once all those dependencies are included.

When you hit this limit, the build fails with a vague error. If you are not aware of this constraint, you will spend a long time looking in the wrong places.

The Solution

There are a few ways to handle this:

The first option is to use output: 'standalone' in your next.config.js file if you are using Next.js. Standalone mode bundles only the exact files needed to run the app, which significantly reduces the output size.

// next.config.js
const nextConfig = {
  output: 'standalone',
};

module.exports = nextConfig;

The second option is to audit your dependencies. Tools like npm-analyze or the --why flag in pnpm can help you find packages that are large and may not be needed at runtime.

The third option, if you are consistently hitting this limit, is to consider moving to a different deployment setup such as running your app in a container on ECS (Elastic Container Service) or using a different hosting provider that does not have this constraint.

Issue 3: pnpm's Symlink Structure Breaks at Runtime

The Problem

pnpm is a modern, faster alternative to npm for managing packages. It is popular because it saves disk space and installs faster. However, pnpm uses a unique approach to storing packages : it uses symlinks (think of them as shortcuts that point to where a file actually lives) instead of copying files directly into your node_modules folder.

Amplify's build and runtime environment does not handle these symlinks well.

What typically happens is this: your build completes successfully. Everything looks fine. But when your app actually runs, it throws a Cannot find module error : meaning it cannot locate a package that is clearly installed. The app is broken at runtime even though the build passed.

This is a known issue that has been reported by multiple developers and is documented in Amplify's GitHub issues.

The Solution

The fix is to force pnpm to use a "hoisted" install mode, which makes it behave more like npm by copying packages directly instead of using symlinks. Add this to your amplify.yml in the preBuild section:

preBuild:
  commands:
    - echo "node-linker=hoisted" >> .npmrc
    - corepack enable
    - pnpm install --shamefully-hoist

The --shamefully-hoist flag tells pnpm to put all packages directly in node_modules the traditional way. The name sounds alarming but it is a well-known workaround specifically for environments that do not support symlinks.

Alternatively, if you are not tied to pnpm, switching to npm for your Amplify builds is the simplest fix. You can keep pnpm locally for development and use npm in the Amplify build config.

A Note on These Constraints

None of these limitations are front and center in Amplify's documentation. Most of them are buried in GitHub issue threads, Stack Overflow answers, or AWS re:Post forums. As a beginner, you would have no reason to look for them until something breaks.

That is the pattern with Amplify, it works smoothly for straightforward use cases, but the moment you step slightly outside the default path, you hit constraints that are hard to debug without prior knowledge.

This is not to say Amplify is bad. For small to medium projects, it is genuinely convenient. But going in with eyes open about these limitations will save you real time.

Quick Reference

Here is a summary of everything covered:

Cache, remove it entirely. It adds time instead of saving it because npm ci and npm install both ignore or delete the cached node_modules anyway.

220MB artifact limit plan for it. Use Next.js standalone output mode and audit your dependencies if you are close to the limit.

pnpm symlinks, use hoisted mode. Add node-linker=hoisted to your .npmrc and use --shamefully-hoist when installing, or switch to npm for Amplify builds.

Have You Hit Other Amplify Limitations?

This list is based on my own experience. Amplify has more quirks than these three, and I am sure other developers have hit walls I have not encountered yet.

If you have run into something that is not covered here, I would love to hear about it. Drop a comment or reach out directly, let us build a more complete picture of what Amplify can and cannot do, so the next developer does not have to figure it out the hard way.

Need Help?

If you are stuck on any of these issues or running into something else with your Amplify setup, feel free to reach out. I am happy to help.

Email me at khantanseer43@gmail.com