Skip to main content
Version: 2.75.2

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: