ac-lambda-deployment

Simple AWS Lambda deployment tool using AWS SDK v3. Deploys code, manages layers, and configures SQS triggers without the complexity of full infrastructure-as-code tools.

Features

• Code-focused deployment - Updates Lambda function code quickly
• Layer management - Attach and update Lambda layers
• SQS trigger configuration - Manage event source mappings
• Multi-environment support - Different configs for dev/prod
• Automatic retry logic - Handles concurrent update conflicts
• Include-based packaging - Only package specified files
• AWS profile support - Use different AWS profiles per environment

Installation

npm install ac-lambda-deployment --save-dev
# or
yarn add ac-lambda-deployment --dev

Quick Start

1. Create a configuration file:

// lambda.config.js
module.exports = {
    functionName: 'my-lambda-function',
    roleArn: 'arn:aws:iam::123456789012:role/lambda-execution-role',
    handler: 'lambda.handler',
    includes: ['lambda.js'],
    layers: [
        'arn:aws:lambda:eu-central-1:123456789012:layer:my-utils:1'
    ]
}

2. Add to package.json scripts:

{
    "scripts": {
        "deploy": "lambda-deploy",
        "deploy:prod": "NODE_ENV=production lambda-deploy --profile=prod"
    }
}

3. Deploy:

npm run deploy

Configuration

Basic Configuration

Create lambda.config.js in your project root:

module.exports = {
    functionName: 'my-function',
    roleArn: 'arn:aws:iam::123456789012:role/lambda-role',
    handler: 'lambda.handler',
    runtime: 'nodejs18.x',
    timeout: 30,
    memorySize: 128,
    includes: ['lambda.js', 'config.json'],
    environment: {
        NODE_ENV: 'production',
        API_KEY: 'your-api-key'
    }
}

Multi-Environment Configuration

// lambda.config.js
const env = process.env.NODE_ENV || 'dev'

const environments = {
    dev: {
        functionName: 'my-function-dev',
        roleArn: 'arn:aws:iam::123456789012:role/lambda-dev-role',
        profile: 'default',
        layers: [
            'arn:aws:lambda:eu-central-1:123456789012:layer:dev-utils:1'
        ]
    },
    production: {
        functionName: 'my-function-prod',
        roleArn: 'arn:aws:iam::123456789012:role/lambda-prod-role', 
        profile: 'production',
        layers: [
            'arn:aws:lambda:eu-central-1:123456789012:layer:prod-utils:2'
        ]
    }
}

module.exports = {
    handler: 'lambda.handler',
    runtime: 'nodejs18.x',
    includes: ['lambda.js'],
    ...environments[env]
}

SQS Triggers

module.exports = {
    functionName: 'my-sqs-processor',
    roleArn: 'arn:aws:iam::123456789012:role/lambda-sqs-role',
    sqsTriggers: [
        {
            queueArn: 'arn:aws:sqs:eu-central-1:123456789012:my-queue',
            batchSize: 10,
            maxBatchingWindow: 5,
            enabled: true
        }
    ]
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | functionName | string | required | Lambda function name | | roleArn | string | required | IAM role ARN for the function | | handler | string | lambda.handler | Function entry point | | runtime | string | nodejs18.x | Lambda runtime | | timeout | number | 30 | Function timeout in seconds | | memorySize | number | 128 | Memory allocation in MB | | includes | array | ['lambda.js'] | Files to include in deployment package | | layers | array | [] | Lambda layer ARNs | | environment | object | {} | Environment variables | | profile | string | default | AWS profile to use | | region | string | eu-central-1 | AWS region | | sqsTriggers | array | [] | SQS event source mappings |

Usage

Command Line

# Deploy with default configuration
npx lambda-deploy

# Deploy with specific AWS profile
npx lambda-deploy --profile=production

# Deploy with different region
npx lambda-deploy --region=us-east-1

# Deploy with custom config file
npx lambda-deploy --config=prod.config.js

# Multi-environment
NODE_ENV=production npx lambda-deploy --profile=prod

Programmatic Usage

const LambdaDeployer = require('ac-lambda-deployment')

async function deploy() {
    const deployer = new LambdaDeployer({
        region: 'eu-central-1',
        profile: 'production'
    })
    
    await deployer.deploy()
}

deploy().catch(console.error)

Package Structure

The tool uses an include-based approach - only specified files are packaged:

project/
├── lambda.js              # Your Lambda function (included)
├── lambda.config.js       # Configuration (not included)
├── package.json           # Dependencies info (not included) 
├── node_modules/          # Always included in package
└── other-files.js         # Only if specified in includes

Default includes: ['lambda.js'] Always included: node_modules/ (production dependencies)

AWS Permissions

Your Lambda execution role needs these permissions for SQS triggers:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sqs:ReceiveMessage",
                "sqs:DeleteMessage", 
                "sqs:GetQueueAttributes"
            ],
            "Resource": "arn:aws:sqs:*:*:*"
        }
    ]
}

Alternative Configuration

You can also configure in package.json:

{
    "name": "my-project",
    "lambda": {
        "functionName": "my-function",
        "roleArn": "arn:aws:iam::123456789012:role/lambda-role",
        "includes": ["lambda.js", "utils.js"]
    }
}

Security

Important: Never commit lambda.config.js to version control if it contains sensitive data.

# .gitignore
lambda.config.js
lambda.*.config.js

Create a template instead:

// lambda.config.example.js
module.exports = {
    functionName: 'your-function-name',
    roleArn: 'arn:aws:iam::YOUR-ACCOUNT:role/YOUR-ROLE',
    environment: {
        API_KEY: 'your-api-key'
    }
}

Comparison with Other Tools

| Tool | Code Deploy | Infrastructure | Complexity | |------|-------------|----------------|------------| | ac-lambda-deployment | ✅ Fast | Layers, SQS only | Low | | Serverless Framework | ✅ | ✅ Full | High | | AWS SAM | ✅ | ✅ Full | Medium | | Terraform | ❌ | ✅ Full | High | | ClaudiaJS | ✅ Fast | Basic | Low (deprecated) |

Use ac-lambda-deployment when:

• You want fast code deployments
• Infrastructure is managed separately (Terraform/CDK)
• You need simple layer and SQS trigger management
• You want ClaudiaJS-like simplicity with modern AWS SDK

Examples

Simple API Function

// lambda.config.js
module.exports = {
    functionName: 'api-handler',
    roleArn: 'arn:aws:iam::123456789012:role/api-lambda-role',
    handler: 'lambda.handler',
    timeout: 10,
    memorySize: 256,
    environment: {
        DATABASE_URL: process.env.DATABASE_URL
    }
}

SQS Message Processor

// lambda.config.js  
module.exports = {
    functionName: 'queue-processor',
    roleArn: 'arn:aws:iam::123456789012:role/sqs-lambda-role',
    sqsTriggers: [
        {
            queueArn: 'arn:aws:sqs:eu-central-1:123456789012:process-queue',
            batchSize: 5,
            maxBatchingWindow: 10
        }
    ],
    layers: [
        'arn:aws:lambda:eu-central-1:123456789012:layer:shared-utils:1'
    ]
}

Troubleshooting

Permission Denied

chmod +x ./node_modules/ac-lambda-deployment/index.js

Concurrent Update Error

The tool automatically retries when Lambda is being updated. Wait 30-60 seconds between deployments.

Function Not Found

Make sure the function exists or provide roleArn to create it automatically.

License

MIT © 2025 AdmiralCloud AG, Mark Poepping

Support

• Check AWS credentials: aws sts get-caller-identity
• Verify function exists: aws lambda get-function --function-name your-function
• Enable debug logging: AWS_SDK_LOAD_CONFIG=1 DEBUG=* npx lambda-deploy