A simple and efficient controller for managing AWS Lambda@Edge functions in CloudFront distributions.
Lambda@Edge Function Controller is a TypeScript library that provides a clean API for attaching and detaching Lambda@Edge functions to/from CloudFront distributions. It handles the complex CloudFront configuration updates automatically, making it easy to manage edge functions in your CDN setup.
- Simple API: Easy-to-use methods for attaching and detaching Lambda@Edge functions
- Event Type Support: Supports all Lambda@Edge event types (viewer-request, viewer-response, origin-request, origin-response)
- Automatic Configuration: Automatically generates and updates CloudFront distribution configurations
- TypeScript Support: Full TypeScript support with comprehensive type definitions
- AWS SDK v3: Built with the latest AWS SDK for JavaScript v3
- Logging: Built-in logging with Bunyan for debugging and monitoring
- Flexible Configuration: Support for custom AWS clients and configurations
- A/B Testing: Quickly switch between different Lambda@Edge functions for testing
- Feature Flags: Enable/disable features at the edge without redeploying
- Security Updates: Rapidly deploy security patches to edge functions
- Performance Optimization: Test different edge function configurations
- Development Workflow: Manage edge functions across different environments
- Disaster Recovery: Quickly rollback to previous edge function versions
npm install lambda-edge-controller
# or
yarn add lambda-edge-controllerimport { LambdaEdgeController } from 'lambda-edge-controller';
// Create a controller instance
const controller = new LambdaEdgeController(
'arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1',
'viewer-request'
);
// Attach the Lambda@Edge function to a CloudFront distribution
await controller.attachEdgeFunction('E1234567890ABCD');
// Detach the Lambda@Edge function from a CloudFront distribution
await controller.detachEdgeFunction('E1234567890ABCD');import { LambdaEdgeController } from 'lambda-edge-controller';
import { CloudFrontClient } from '@aws-sdk/client-cloudfront';
// Create a custom CloudFront client
const cloudfrontClient = new CloudFrontClient({
region: 'us-east-1',
credentials: {
accessKeyId: 'YOUR_ACCESS_KEY',
secretAccessKey: 'YOUR_SECRET_KEY'
}
});
// Create controller with custom client
const controller = new LambdaEdgeController(
'arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1',
'viewer-request',
{ cloudfront: cloudfrontClient }
);
// Enable debug logging
controller.enableDebugger();
// Attach edge function
await controller.attachEdgeFunction('E1234567890ABCD');new LambdaEdgeController(
lambdaArn: string,
eventType?: EventType,
client?: ControllerClient
)Parameters:
lambdaArn: The ARN of your Lambda@Edge functioneventType: The CloudFront event type (default: 'viewer-request')client: Optional custom AWS clients
Event Types:
viewer-request: Function executes before CloudFront forwards a request to the originviewer-response: Function executes before CloudFront returns the response to the viewerorigin-request: Function executes before CloudFront forwards the request to the originorigin-response: Function executes after CloudFront receives the response from the origin
Attaches the Lambda@Edge function to the specified CloudFront distribution.
Removes the Lambda@Edge function from the specified CloudFront distribution.
Enables detailed logging for debugging purposes.
Disables detailed logging.
The project includes comprehensive examples and testing utilities in the examples/ directory.
- Install dependencies:
# Install project dependencies
pnpm install
# Install examples dependencies
cd examples
npm install- Build the library:
# From project root
pnpm run build- Configure environment:
cd examples
npm run setup
# This creates a .env file from env.example- Edit .env file:
# Required settings
LAMBDA_ARN=arn:aws:lambda:us-east-1:123456789012:function:my-edge-function:1
CLOUDFRONT_DISTRIBUTION_ID=E1234567890ABCD
# Optional settings
EVENT_TYPE=viewer-request
AWS_REGION=us-east-1
AWS_PROFILE=default
DEBUG=true# Run all unit tests
pnpm test
# Run tests in watch mode
pnpm run test:watch
# Run tests with coverage
pnpm run test:dev# Run the comprehensive integration test
cd examples
npm test
# Or directly
node aws-test.js# Test specific functionality
node -e "
const { LambdaEdgeController } = require('../dist/index.js');
const controller = new LambdaEdgeController('your-lambda-arn', 'viewer-request');
console.log('Controller created successfully');
"The examples directory provides:
- Basic Tests: Controller creation and configuration validation
- Advanced Tests: Custom AWS client configuration
- Integration Tests: Real AWS environment testing
- Error Handling: Comprehensive error scenarios
- Configuration Validation: Environment setup verification
- Node.js >= 18.18.0 (pnpm 10 needs 18.12+, and the pinned
@typescript-eslint/parser7.x needs^18.18.0 || >=20) - pnpm (the version is pinned by
packageManagerinpackage.json;corepack enablepicks it up) - AWS credentials with CloudFront permissions
- TypeScript knowledge
# Install dependencies
pnpm install
# Run linter
pnpm run lint
pnpm run lint --fix
# Type check
pnpm run typecheck
# Run tests
pnpm test
pnpm run test:watch
# Build
pnpm run build
# Generate documentation
pnpm run doc{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudfront:GetDistribution",
"cloudfront:UpdateDistribution"
],
"Resource": "*"
}
]
}Releases are automated. Merging to main runs semantic-release on CircleCI
(config: workflows/publish/npm-polyrepo-semantic-release.yaml in hideokamoto/circleci-configurations, settings: .releaserc.json).
- Merge a pull request whose commits follow Conventional Commits.
- CircleCI runs lint / typecheck / build / test, decides the next version from the commits since the last
v*tag (fix:→ patch,feat:→ minor,feat!:orBREAKING CHANGE→ major;chore:,docs:,ci:,build:etc. do not release), pushes the tag, publishes to npm with OIDC trusted publishing (no npm token), and creates the GitHub Release.
Do not run npm version or npm publish by hand, and do not bump version in package.json (the published version comes from the tag).
The library consists of three main components:
- LambdaEdgeController: Main controller class for managing edge functions
- ConfigUpdator: Handles CloudFront configuration updates
- Models: TypeScript interfaces and types
LambdaEdgeController
├── CloudFrontClient (AWS SDK)
├── ConfigUpdator
└── Logger (Bunyan)
ConfigUpdator
├── Lambda ARN management
├── Event type handling
└── Distribution config updates
- Fork the repository
- Create a feature branch
- Follow the commit message convention (Conventional Commits)
- Run tests and linting
- Submit a pull request
git commit -m "<type>[optional scope]: <description>
[optional body]
[optional footer]"Types:
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changesrefactor: Code refactoringtest: Adding or updating testschore: Maintenance tasks
MIT License - see LICENSE file for details.
- Issues: GitHub Issues
- Documentation: Generated Docs
- Examples: Examples Directory
- AWS Lambda@Edge Documentation
- CloudFront API Reference
- AWS SDK for JavaScript v3
- Conventional Commits
日本語版: README_ja.md