The Backstage Deployment Standard: 5 Strategies to Increase Build Speed and Reduce Image Size

Jun 30, 2026

—

Hello! Today, we’re going to delve into optimization strategies for ‘build speed’ and ‘image size’, the most common concerns when containerizing Backstage, the leading developer portal. 🚀

While Backstage is powerful, it can have many dependencies and a complex build process. We’ve compiled key strategies on how to deploy it quickly and lightly in a production environment! 💡

🏗️ Backstage Container Optimization: Why is it important?

Backstage has a large monorepo structure, and without any optimization, Docker builds can lead to the following problems:

Huge Image Size: Images bloating from hundreds of MBs to GBs 🐘
Slow Build Time: Changing a single line of source code requires reinstalling all dependencies, making you wait for a coffee break ☕
Security Vulnerabilities: Unnecessary build tools included in the image expand the attack surface 🛡️

Let’s explore the best strategies to solve these issues one by one!

1. Implement Multi-stage Builds 🖇️

This is the most basic yet powerful strategy. It separates the build stage from the runtime stage, ensuring that the final image contains only the files essential for execution.

✅ How to configure it?

Build Stage: Includes the full Node.js environment, Python (for building some native modules), Yarn, and all other build tools to perform yarn build.
Production Stage: Copies only the completed static files and compiled backend binaries. Typically, node:slim or alpine versions are used to minimize the base image size.

This approach removes build-time libraries (e.g., gcc, make, python) from the final image, potentially reducing its size by over 80%! 📉

2. Layer Caching Strategy ⚡

Docker reuses unchanged layers. However, incorrect ordering can lead to reinstalling all dependencies every time.

✅ Optimization Tips

Copy dependency files first: Instead of COPY . . first, copy package.json and yarn.lock first, then run yarn install. This allows the library layer to remain cached even if source code changes.
Utilize Skeleton: Backstage can generate skeleton.tar.gz and bundle.tar.gz during yarn build. The skeleton contains only the dependency structure, maximizing cache efficiency. 🦴

3. Base Image Selection: Slim vs Alpine 🐧

Choosing the underlying OS is crucial for reducing image size.


Image Type	Size	Characteristics

—	—	—
Node Default	Approx. 900MB+	Heavy, includes all tools
Node Slim	Approx. 200MB	Debian-based, good compatibility, lightweight
Node Alpine	Approx. 50MB	Ultra-lightweight, uses musl libc, potential conflicts with some native modules

Recommended Strategy: For compatibility and stability, node:20-slim (or the latest LTS slim version) offers the most suitable balance for the Backstage operating environment. ⚖️

4. Docker BuildKit and Cache Mount 🛠️

In modern Docker environments, activating BuildKit and using the –mount=type=cache option is essential.

Dockerfile

# Example: Build using Yarn cache
RUN --mount=type=cache,target=/root/.yarn/berry/cache 
    yarn install --immutable

This method significantly speeds up build times by reusing the host’s cache directory instead of downloading hundreds of packages every time you build in a CI/CD pipeline. 🏎️💨

5. Remove Unnecessary Files (.dockerignore) 🚫

Strictly exclude files that do not need to be included in the image build context. Be sure to add the following items to your .dockerignore file!

node_modules (as they are reinstalled in the build stage)
.git (version control history is unnecessary for production)
dist and build artifacts
*.md, docs, and other documentation files

📝 Summary and Conclusion

The ‘golden recipe’ for optimizing Backstage containerization is as follows:

Multi-stage builds to separate build tools and artifacts ✂️
Use a lightweight base image from the node:slim family 🍃
Maximize cache efficiency with Skeleton structure and layer ordering 🔄
Shorten package installation time with BuildKit cache mounts ⚡
Maintain a lean build context with .dockerignore 🧹

By applying these strategies, you can operate a faster, safer, and lighter Backstage service! We hope your deployment pipeline becomes much lighter. 😊