Using Multiple Dockerfiles in a Monorepo with Shared Code (2026)

In modern software development, monorepos are becoming increasingly popular for managing multiple related projects. A common challenge in these setups is efficiently using Docker to manage dependencies, especially when multiple applications share common code. In this tutorial, we'll explore how to effectively use multiple Dockerfiles within a monorepo, focusing on shared code management.

Key Takeaways

• Understand the basics of Dockerfiles in a monorepo.
• Learn how to structure Dockerfiles to manage shared code.
• Explore a practical example with a Node.js and React setup.
• Discover common pitfalls and troubleshooting tips.

Introduction

Managing a monorepo efficiently with Docker can streamline your development workflow, especially when dealing with multiple applications that depend on shared code. This tutorial will guide you through setting up multiple Dockerfiles to cater to different applications within a monorepo. We will use a Node.js application and two React applications as examples, demonstrating how to handle shared dependencies and ensure each Docker setup is optimal for its respective application.

By the end of this guide, you will have a solid understanding of how to structure Dockerfiles in a monorepo for a seamless development environment. This knowledge is crucial for developers looking to maintain scalability and consistency across multiple projects.

Prerequisites

• Basic understanding of Docker and Dockerfiles.
• Familiarity with Node.js and React applications.
• Access to a Windows development environment with Docker installed.
• Experience with Git and command line operations.

Step 1: Understanding the Monorepo Structure

Let's first understand the directory structure of our monorepo:

project/
  node-app/
  react-app-1/
  react-app-2/
  shared/

In this setup, node-app, react-app-1, and react-app-2 are our applications, each requiring access to the shared directory. This shared directory contains common utilities and modules that all applications depend upon.

Step 2: Setting Up Dockerfiles for Each Application

We need to create separate Dockerfiles for each application while ensuring they can access the shared code. Here's a breakdown of how to achieve this:

Dockerfile for Node.js Application

Let's create a Dockerfile for node-app:

# node-app/Dockerfile
FROM node:16
WORKDIR /app
COPY ./shared ./shared
COPY ./node-app ./node-app
WORKDIR /app/node-app
RUN npm install
CMD ["node", "app.js"]

In this Dockerfile, we copy both the shared code and the specific application code into the Docker image, ensuring that the Node.js application can access the shared utilities.

Dockerfile for React Applications

Similarly, for each React application, we need to ensure they can access the shared code:

# react-app-1/Dockerfile
FROM node:16
WORKDIR /app
COPY ./shared ./shared
COPY ./react-app-1 ./react-app-1
WORKDIR /app/react-app-1
RUN npm install
RUN npm run build
CMD ["npm", "start"]

# react-app-2/Dockerfile
FROM node:16
WORKDIR /app
COPY ./shared ./shared
COPY ./react-app-2 ./react-app-2
WORKDIR /app/react-app-2
RUN npm install
RUN npm run build
CMD ["npm", "start"]

These Dockerfiles follow a similar pattern, ensuring shared code is copied alongside the specific application code.

Step 3: Building and Running Docker Images

With the Dockerfiles in place, we can build and run our Docker images. Navigate to each application's directory and execute the following commands:

# For node-app
cd node-app
docker build -t node-app .
docker run -p 3000:3000 node-app

# For react-app-1
cd ../react-app-1
docker build -t react-app-1 .
docker run -p 3001:3000 react-app-1

# For react-app-2
cd ../react-app-2
docker build -t react-app-2 .
docker run -p 3002:3000 react-app-2

These commands will build Docker images for each application and run them, exposing them on different ports as needed.

Common Errors/Troubleshooting

Here are some common issues and solutions you might encounter:

• Error: "Forbidden path outside the build context"
  Solution: Ensure your Dockerfile only copies files within the build context. You may need to restructure your directory or use multi-stage builds.
• Error: "Module not found"
  Solution: Double-check that all necessary modules are included in the package.json and are installed correctly.
• Error: "Port already in use"
  Solution: Make sure each application is exposed on a unique port.

Frequently Asked Questions

Can I use a single Dockerfile for all applications?

It's possible but not recommended for complex setups, as it can lead to bloated images and harder maintenance.

Why can't I copy files from outside the build context?

Docker restricts copying files from outside the context to maintain isolation and security during builds.

How do I handle environment variables in this setup?

Use a .env file or Docker secrets to manage environment variables securely.

Frequently Asked Questions

Can I use a single Dockerfile for all applications?

It's possible but not recommended for complex setups, as it can lead to bloated images and harder maintenance.

Why can't I copy files from outside the build context?

Docker restricts copying files from outside the context to maintain isolation and security during builds.

How do I handle environment variables in this setup?

Use a .env file or Docker secrets to manage environment variables securely.