How getlift/lift works
Project Type and Purpose
• Type: Open-source Serverless Framework plugin
• Purpose: Expose high-level “constructs” (static websites, SPAs, queues, storage, etc.) in serverless.yml by generating AWS CDK constructs and synthesizing CloudFormation templates.
Key Architectural Components
A. Serverless Framework CLI
– Entry point for users writing serverless.yml
– Loads plugins (including serverless-lift) and executes hooks (deploy, package, invoke, etc.)
B. serverless-lift Plugin (src/plugin.ts)
– Registers itself with the Serverless Framework hook system
– Parses the “constructs” section in serverless.yml
– For each construct: instantiates the right Construct class via an internal registry
C. Construct Layer (src/constructs)
– ConstructInterface / StaticConstructInterface define the public API
– Concrete constructs under src/constructs/aws (e.g., StaticWebsite, Queue, Storage, Webhook, DynamoDBSingleTable, Vpc, ServerSideWebsite, SinglePageApp)
– Each construct implements a high-level resource definition and CDK best practices
D. CloudFormation Synthesis (src/CloudFormation.ts)
– Orchestrates AWS CDK App and Stack creation
– Feeds in CDK constructs from the Construct layer
– Synthesizes a CloudFormation template (JSON/YAML)
E. Provider Abstraction (src/providers)
– ProviderInterface / StaticProviderInterface define hooks to integrate into different runtimes
– AwsProvider implements AWS-specific logic: credentials resolution, region, environment, bootstrapping CDK context
F. Utilities (src/utils)
– Helper functions (logger, naming conventions, error handling, S3 sync, sleep, CFN function associations)
G. Testing and Fixtures (test/)
– Unit tests for each construct and utility
– End-to-end fixtures for common serverless.yml variations
Relationships & Data Flow
1. User runs “serverless deploy”
2. Serverless Framework loads serverless-lift plugin
3. plugin.ts:
– Reads “constructs” from serverless.yml
– For each construct:
a. Selects provider (AwsProvider)
b. Instantiates the Construct class
c. Calls its “toCloudFormation” or equivalent method
4. Constructs call into CloudFormation.ts:
– Build CDK App & Stack, add CDK resources
– Stack.synth() generates CloudFormation template
5. Serverless Framework receives synthesized template and merges with functions, resources sections, then deploys to AWS via CloudFormation
6. (Optional) User runs “serverless lift eject” to export CFN template directly
Architectural Patterns & Principles
• Plugin architecture: decouples CLI integration from core logic
• Factory/Registry: dynamic instantiation of constructs by name/type
• Adapter/Provider: abstracts AWS-specific behavior to allow future providers
• Composition over inheritance: constructs compose CDK low-level constructs
• Single Responsibility: each file/class has one primary concern
Detailed Elements to Capture
– plugin.ts as orchestrator
– src/constructs/abstracts vs. src/constructs/aws implementations
– src/providers/AwsProvider role
– src/CloudFormation.ts synthesizer
– How utilities support naming and syncing
– Interaction between user’s serverless.yml constructs block and the plugin