Fargate-nodejs

Deploy Node.js/TypeScript to AWS Fargate with automatic esbuild bundling, similar to Lambda's NodejsFunction.

Video walkthrough

A hands-on walkthrough showing how fargate-nodejs works, why it exists, and how it compares to Lambda and raw Fargate:

👉 https://www.youtube.com/watch?v=LMTDykz6NuI

Features

• Automatic code bundling with esbuild (no Docker knowledge required)
• TypeScript and JavaScript support
• Works for HTTP services, SQS workers, scheduled tasks, or background jobs
• Optional ALB integration
• Auto-scaling based on CPU, memory, or SQS queue depth
• IAM roles and security groups configured automatically

Installation

npm install fargate-nodejs

Quick Start

HTTP service:

import { FargateNodejsService } from 'fargate-nodejs';

const service = new FargateNodejsService(stack, 'MyService', {
  entry: './src/index.ts',
  runtime: '18',
  containerPort: 3000,
});

SQS worker (no ports needed):

const worker = new FargateNodejsService(stack, 'Worker', {
  entry: './src/worker.ts',
  environment: { QUEUE_URL: queue.queueUrl },
  autoScaling: {
    sqsQueue: queue,
    messagesPerTask: 10,
  },
});

Configuration

With Load Balancer

import * as elbv2 from 'aws-cdk-lib/aws-elasticloadbalancingv2';

const service = new FargateNodejsService(stack, 'MyService', {
  entry: './src/index.ts',
  loadBalancer: {
    loadBalancer: alb,
    pathPatterns: ['/api/*'],
    healthCheckPath: '/health',
  },
});

With Auto Scaling

const service = new FargateNodejsService(stack, 'MyService', {
  entry: './src/index.ts',
  autoScaling: {
    minCapacity: 2,
    maxCapacity: 10,
    targetCpuUtilization: 70,
    // Or for SQS: sqsQueue: queue, messagesPerTask: 5
  },
});

Advanced Configuration

const service = new FargateNodejsService(stack, 'MyService', {
  entry: './src/index.ts',
  projectRoot: './my-app',
  cpu: 512,
  memoryLimitMiB: 1024,

  bundling: {
    minify: true,
    sourceMap: true,
    externalModules: ['aws-sdk'],
  },

  environment: { API_KEY: 'value' },
  secrets: { DB_PASSWORD: ecs.Secret.fromSecretsManager(secret) },

  assignPublicIp: false,
  enableExecuteCommand: true,
});

// Grant permissions
service.grantPermissions([...]);

Properties

Key properties:

• entry (required) - Path to entry file
• runtime - Node.js version (14, 16, 18, 20, 22, 23)
• containerPort - Port to expose (omit for workers)
• cpu / memoryLimitMiB - Resource limits
• bundling - esbuild options (minify, sourceMap, externalModules)
• autoScaling - CPU/memory/SQS-based scaling
• loadBalancer - ALB integration
• environment / secrets - Container config

See types.ts for full API.

Why use this?

vs Lambda: No 15-minute timeout, no cold starts, better for long-running workloads, WebSockets, or anything that needs persistent connections.

vs raw Fargate: No Docker expertise needed, automatic bundling, cleaner CDK code.

Examples

• Basic HTTP Service - Express app
• SQS Worker - Background worker with queue scaling

Development

npm install
npm run build
npm test

Contributing

Contributions are welcome! Here's how you can help:

New to contributing? Check out GitHub's guide to contributing to a project.

Reporting Issues

• Check if the issue already exists in GitHub Issues
• Provide a clear description and reproduction steps
• Include your CDK version, Node.js version, and relevant code snippets

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run tests: npm test
5. Build the project: npm run build
6. Commit with a clear message: git commit -m "feat: add new feature"
7. Push to your fork: git push origin feature/my-feature
8. Open a Pull Request with a description of your changes

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/fargate-nodejs.git
cd fargate-nodejs

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Test locally with examples
cd examples/basic
npm install
npx cdk synth

Code Style

• Follow the existing code style
• Use TypeScript for all code
• Keep commits atomic and well-described

Testing

• Add unit tests for new features
• Ensure all tests pass before submitting
• Test with the example projects when possible

License

MIT