Skip to main content
Version: 2.75.0

How to Compile TypeScript for Production Deployment

Problem

Your Watt application uses TypeScript for development, but you need to optimize it for production:

  • Automatic TypeScript compilation during startup adds latency and memory usage
  • Production environments should use pre-compiled JavaScript for better performance
  • You want to avoid shipping TypeScript source files to production
  • You need consistent compilation across development and production environments

When to use this solution:

  • Production deployments where startup time is critical
  • Containerized environments with limited resources
  • Applications with large TypeScript codebases
  • CI/CD pipelines that can handle build steps

Solution Overview

This guide shows you how to pre-compile TypeScript before deployment while maintaining flexibility for development. You'll learn to:

  1. Configure TypeScript compilation settings
  2. Use different compilation modes for development vs. production
  3. Optimize production builds by excluding source files
  4. Handle multi-service TypeScript compilation

Step 1: Configure TypeScript Settings

Basic TypeScript Configuration

If you've generated your application using npx wattpm create, your config file will include TypeScript support:

{
"plugins": {
"paths": [{
"path": "plugins",
"encapsulate": false
}, "routes"],
"typescript": "{PLT_TYPESCRIPT}"
}
}

Environment Variable Configuration

Configure your .env file for development:

# Development - compile TypeScript on-the-fly
PLT_TYPESCRIPT=true

Configure your production .env file:

# Production - use pre-compiled JavaScript
PLT_TYPESCRIPT=false

Why this approach works:

  • Development gets automatic compilation for fast iteration
  • Production uses pre-compiled code for optimal performance
  • Same configuration file works across environments

Step 2: Compile for Production Deployment

Single Service Compilation

For individual Watt services:

# Navigate to your service directory
cd web/my-service

# Compile TypeScript to JavaScript
npx platformatic service compile

# Or if you have Platformatic CLI globally installed
plt service compile

Multi-Service (Runtime) Compilation

For Watt applications with multiple services:

# From your main application directory
npx platformatic runtime compile

# Or use the shorter command
plt runtime compile

What this does:

  • Compiles all TypeScript files to JavaScript
  • Preserves directory structure
  • Generates source maps for debugging
  • Validates TypeScript code before compilation

Step 3: Optimize Production Builds

Configure Output Directory

To avoid shipping TypeScript source files, configure an output directory:

{
"plugins": {
"paths": [{
"path": "plugins",
"encapsulate": false
}, "routes"],
"typescript": {
"enabled": "{PLT_TYPESCRIPT}",
"outDir": "dist"
}
}
}

Benefits of using outDir:

  • Separates compiled JavaScript from TypeScript source
  • Enables cleaner production deployments
  • Reduces deployment package size
  • Improves security by not exposing source code

TypeScript Configuration File

Create a tsconfig.json for optimal production builds:

{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "node",
"outDir": "./dist",
"rootDir": "./",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true,
"sourceMap": true,
"removeComments": true
},
"include": [
"plugins/**/*",
"routes/**/*",
"lib/**/*"
],
"exclude": [
"node_modules",
"dist",
"test/**/*"
]
}

Step 4: Update Package.json Scripts

Add build scripts to your package.json:

{
"scripts": {
"dev": "wattpm dev",
"build": "plt runtime compile",
"build:service": "plt service compile",
"start": "wattpm start",
"clean": "rm -rf dist"
}
}

Step 5: Verification and Testing

Verify Compilation

1. Test compilation locally:

# Clean any previous builds
npm run clean

# Compile TypeScript
npm run build

# Check compiled output
ls -la dist/ # Should show compiled .js files

2. Test compiled application:

# Set production environment
export PLT_TYPESCRIPT=false

# Start with compiled code
npm start

# Verify endpoints work
curl http://localhost:3042/

Verify Production Environment

1. Check that TypeScript is disabled:

# In production environment
echo $PLT_TYPESCRIPT # Should output: false

2. Verify faster startup:

# Time the startup with compiled code
time npm start

Expected results:

  • Faster application startup
  • Lower memory usage during startup
  • No TypeScript compilation logs

Docker Integration

Multi-Stage Dockerfile with TypeScript

# Build stage
FROM node:20-alpine AS build

WORKDIR /app
COPY package*.json ./
COPY --parents ./web/*/package.json ./

RUN npm install

COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine AS production

WORKDIR /app

# Copy compiled code and production dependencies
COPY --from=build /app/dist ./dist
COPY --from=build /app/package*.json ./
COPY --from=build /app/watt.json ./

RUN npm install --omit=dev

ENV PLT_TYPESCRIPT=false
ENV HOSTNAME=0.0.0.0
ENV PORT=3042

EXPOSE 3042

CMD ["npm", "start"]

Troubleshooting

Compilation Errors

Problem: TypeScript compilation fails with type errors

Solutions:

  • Run tsc --noEmit to check types without compilation
  • Fix TypeScript errors in source files
  • Update tsconfig.json strictness settings
  • Check that all dependencies have proper type definitions

Runtime Errors with Compiled Code

Problem: Application works in development but fails with compiled code

Solutions:

  • Verify all files were compiled (check dist/ directory)
  • Ensure import paths are correct in compiled code
  • Check that outDir configuration matches runtime expectations
  • Verify environment variables are set correctly (PLT_TYPESCRIPT=false)

Missing Files in Production

Problem: Some files missing after compilation

Solutions:

  • Check tsconfig.json include/exclude patterns
  • Verify that all necessary files are being compiled
  • Ensure non-TypeScript files are copied to output directory
  • Check that paths in configuration match compiled output

Performance Issues

Problem: Compilation is too slow

Solutions:

  • Use incremental compilation: "incremental": true in tsconfig.json
  • Exclude unnecessary files in tsconfig.json
  • Use TypeScript project references for large projects
  • Consider parallel compilation for multi-service projects

Next Steps

Now that you have optimized TypeScript compilation: