Containerizing TypeScript Applications with Docker: A Complete Guide

Why Containerizing TypeScript Applications is a Must-Have for Modern Developers

Imagine this scenario: you've written a cool TypeScript application on your MacBook, everything works perfectly. You upload the code to a server running Ubuntu — and you get a bunch of errors. Sound familiar? The problem lies in environment differences: Node.js versions, system libraries, environment variables. Docker solves this pain once and for all. Containerizing TypeScript applications allows you to package your code along with all its dependencies into an isolated container that will run identically on any server, in the cloud, or on a colleague's local machine.

In this article, we'll break down how to properly containerize a TypeScript application using Docker. You'll learn not only the basic steps but also advanced techniques: multi-stage builds, image size optimization, dependency caching, and working with environment variables. Let's go!

What is Docker and Why Does a TypeScript Developer Need It

Docker is a platform for creating, delivering, and running applications in containers. A container is a lightweight, standalone environment that contains everything needed to run your TypeScript application: code, runtime (Node.js), system tools, libraries, and settings.

The advantages for TypeScript projects are clear:

\n
• Environment reproducibility — no more "it works on my machine" and "it crashed in production."
\n
• Isolation — each application runs in its own container without interfering with other services.
\n
• Scalability — easily run 10 instances of your TypeScript server using Docker Compose or Kubernetes.
\n
• Ease of deployment — a single image can be run on any platform: AWS, Google Cloud, DigitalOcean, or locally.
\n

Prerequisites

Before you start, make sure you have installed:

\n
• Docker — download from the official website (works on Windows, macOS, Linux).
\n
• Node.js version 18 or higher (for compiling TypeScript).
\n
• TypeScript — installed globally or locally in the project.
\n

As an example, we'll use a simple Express application in TypeScript. But the approach is universal: you can containerize any TypeScript project — from a Telegram bot to a NestJS server.

Project Structure

First, let's create a minimal TypeScript application structure:

my-typescript-app/\n├── src/\n│   └── index.ts\n├── package.json\n├── tsconfig.json\n└── Dockerfile

The file src/index.ts will contain a simple HTTP server:

import express from 'express';\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\napp.get('/', (req, res) => {\n  res.send('Hello from TypeScript + Docker!');\n});\n\napp.listen(PORT, () => {\n  console.log(`Server is running on port ${PORT}`);\n});

The file tsconfig.json with basic settings:

{\n  "compilerOptions": {\n    "target": "ES2020",\n    "module": "commonjs",\n    "outDir": "./dist",\n    "rootDir": "./src",\n    "strict": true,\n    "esModuleInterop": true\n  }\n}

Writing the First Dockerfile for a TypeScript Application

The simplest way is to do a single-stage build. But we'll immediately take the right path and create a multi-stage build. This will reduce the final image size several times over.

# Stage 1: Build\nFROM node:18-alpine AS builder\nWORKDIR /app\nCOPY package*.json ./\nRUN npm install\nCOPY . .\nRUN npm run build\n\n# Stage 2: Production\nFROM node:18-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCOPY --from=builder /app/package*.json ./\nRUN npm install --production\nEXPOSE 3000\nCMD ["node", "dist/index.js"]

Let's break down each stage:

\n
• bu