Understanding the Build Context and .dockerignore

Everything in your build context is shipped to the builder -- so a stray node_modules can cripple a CI build.

The build context is the set of files Docker sends to the builder before it reads your Dockerfile. A misunderstood context is a common cause of slow builds and broken cache keys in CI. This lesson explains what the context is and how .dockerignore controls it.

What the build context is

When you run docker build ., the final . is the context -- the directory Docker packages and sends to the builder. The builder can only COPY or ADD files that are inside this context. A large context means a large transfer on every build.

Why a bloated context hurts CI

If your context includes node_modules, .git, build output, or large fixtures, every build sends megabytes (or gigabytes) to the builder before any instruction runs. Worse, changes to those files can invalidate your COPY . . cache layer even when nothing relevant changed.

Write a .dockerignore

A .dockerignore file uses gitignore-style patterns to exclude paths from the context. Keep it next to your Dockerfile.

.git
node_modules
dist
build
coverage
*.log
.env
.env.*
Dockerfile
.dockerignore

Verify what is included

• Exclude dependency directories -- they are reinstalled inside the image anyway.
• Exclude .git unless your build genuinely needs commit history.
• Exclude secrets and local .env files so they never leak into an image.
• Exclude build output that the image regenerates.

Key takeaways

• The build context is everything in the build directory, sent to the builder before any instruction runs.
• A .dockerignore keeps the context small, builds fast, and the COPY cache stable.
• Always exclude node_modules, .git, build output, and secrets from the context.

Related guides