Lift Documentation

Lift constructs are designed to be functional out of the box by automatically injecting necessary IAM permissions into Lambda functions deployed within the same serverless.yml file.

Important Limitation: Lift permissions only apply to Lambda functions deployed in the same stack (the same serverless.yml).

For example, if you define a storage construct, any function defined in the same file will automatically receive permissions to read and write to the bucket created by that construct.

# serverless.yml

constructs:
    avatars:
        type: storage

functions:
    myFunction:
        # myFunction automatically gets S3 permissions for the 'avatars' bucket

The database/dynamodb-single-table construct is pre-configured for production with the following characteristics:

• Primary Index: A composite primary index using generic attribute names: PK (Partition Key) and SK (Sort Key).
• Global Secondary Indexes (GSIs): Supports up to 20 GSIs with generic names (GSI-1 to GSI-20), partition keys (GSI-1-PK to GSI-20-PK), and sort keys (GSI-1-SK to GSI-20-SK).
• Data Types: All index attributes use the string data type, which is ideal for composite attributes (e.g., value1#value2).
• Streams: A DynamoDB stream is enabled, publishing new and old values for every write operation.
• TTL: Automatic garbage collection is enabled via a TimeToLive attribute.
• Billing: Set to PAY_PER_REQUEST mode.

Every construct includes an extensions property that allows you to override or add underlying CloudFormation Resource properties. This is useful for advanced configurations not covered by the standard construct options.

Example: Extending an S3 bucket from a storage construct to set AccessControl: PublicRead:

constructs:
    avatars:
        type: storage
        extensions:
            bucket:
                Properties:
                    AccessControl: PublicRead

Each construct's documentation lists the specific CloudFormation resources available for extension.

By default, if an error is thrown in a worker processing a batch, the entire batch is considered failed. To prevent this and only fail specific messages, your worker must return a JSON object containing the itemIdentifier for each failed message in a batchItemFailures array.

{
  "batchItemFailures": [
        {
            "itemIdentifier": "id2"
        },
        {
            "itemIdentifier": "id4"
        }
    ]
}

Lift is designed to simplify the deployment of full web applications to AWS by focusing on "the rest" of the infrastructure beyond just Lambda functions (e.g., CloudFormation, IAM, and other AWS services).

Key Goals

• Simplicity: Replaces complex CloudFormation with concise YAML and uses developer-centric vocabulary instead of AWS-specific terminology.
• Production-Readiness: Provisions services using opinionated, production-ready best practices by default.
• Low Friction: Designed to be installed and deployed in approximately 3 commands with minimal impact on your existing code via a single configuration file.

Design Principles

• No Lock-in: You can easily eject to native CloudFormation if your requirements change.
• Non-Invasive: Lift aims for minimal constraints on your project structure and code.

You can specify multiple domains in the domain list.

• Accessing the original Host: Because API Gateway doesn't preserve the Host header for multiple domains, Lift automatically populates the X-Forwarded-Host header via CloudFront Functions. Use this header in your Lambda code to identify which domain the user visited.
• Redirecting to a main domain: Use redirectToMainDomain: true to redirect all listed domains to the first domain in the list (e.g., redirecting mydomain.com to www.mydomain.com).

constructs:
    website:
        type: server-side-website
        domain:
            - www.mywebsite.com
            - mywebsite.com
        redirectToMainDomain: true

When you deploy a webhook construct, Lift automatically provisions the following AWS resources:

• API Gateway V2 HTTP API (with a $default stage).
• EventBridge EventBus to receive the webhook payloads.
• IAM Role granting API Gateway permission to use the PutEvents API on the EventBridge bus.
• API Gateway V2 route and integration (mapping HTTP request body parameters to the EventBridge Event body).
• Custom Lambda authorizer (if configured) to handle signature verification at the API Gateway level.

The queue construct deploys an SQS queue, a worker Lambda function, and a Dead Letter Queue (DLQ). You must specify a worker with a handler to process incoming messages.

Key features:

• Retries: Messages are retried up to 3 times by default.
• DLQ: Failed messages are stored in a DLQ for 14 days.
• Batching: Batch processing is disabled by default to ensure error handling is straightforward, though it is configurable via batch-size.

service: my-app
provider:
    name: aws

constructs:
    my-queue:
        type: queue
        worker:
            handler: src/worker.handler

plugins:
    - serverless-lift

To use Lift, add the serverless-lift plugin to your serverless.yml and define your resources under a top-level constructs key.

Example structure:

service: my-app

provider:
    name: aws

plugins:
    - serverless-lift

functions:
    # ...

constructs:
    # Define your Lift constructs here
    landing-page:
        type: static-website
        path: 'landing/dist'

    avatars:
        type: storage

The webhook construct exposes a busName variable. You can use this variable to trigger Lambda functions based on specific event patterns received via the webhook.

Use the syntax ${construct:<construct_name>.busName} to reference the deployed EventBridge bus. This allows you to filter for specific event sources or detail types (e.g., filtering for Stripe invoice payments).

constructs:
    stripe:
        type: webhook
        path: /my-webhook-endpoint

functions:
    myConsumer:
        handler: src/stripeConsumer.handler
        events:
            -   eventBridge:
                    eventBus: ${construct:stripe.busName}
                    pattern:
                        source:
                            - stripe
                        detail-type:
                            - invoice.paid