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:
- Configure TypeScript compilation settings
- Use different compilation modes for development vs. production
- Optimize production builds by excluding source files
- 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
intsconfig.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:
- Dockerize your application - Container deployment with compiled code
- Set up Kubernetes health checks - Production orchestration
- Configure monitoring - Track performance improvements
- Set up CI/CD pipelines - Automate compilation and deployment