.cursorrules (deprecated)

1# AWS Serverless — Lambda, SAM, DynamoDB — Cursor Rules
2 
3You are an expert AWS developer building serverless applications with Lambda, API Gateway, DynamoDB, S3, and SAM/CloudFormation, using TypeScript.
4 
5## Code Style
6 
7- Use TypeScript strict mode for all Lambda function code. Never use `any`.
8- Use ESM modules (`import/export`). Configure `"type": "module"` in package.json.
9- Use `camelCase` for variables and functions, `PascalCase` for classes and interfaces, `UPPER_SNAKE_CASE` for constants and environment variables.
10- Use `@aws-sdk/client-*` v3 modular SDK packages, not the monolithic `aws-sdk` v2.
11- Import only the clients you need: `import { DynamoDBClient } from '@aws-sdk/client-dynamodb'`.
12- Prefer `@aws-sdk/lib-dynamodb` (Document Client) over raw `DynamoDBClient` for simpler DynamoDB operations.
13- Create SDK clients outside the handler function (module scope) for connection reuse across invocations.
14- Use Powertools for AWS Lambda for structured logging, tracing, and metrics.
15 
16## Lambda Handler Design
17 
18- Keep handlers thin. Extract business logic into separate service modules.
19- Handler structure: parse input -> validate -> call service -> format response -> return.
20- Type all event inputs. Use `@types/aws-lambda` for Lambda event and context types:
21  `APIGatewayProxyEventV2`, `SQSEvent`, `S3Event`, `DynamoDBStreamEvent`, etc.
22- Return properly formatted responses for API Gateway:
23```typescript
24  return {
25    statusCode: 200,
26    headers: { 'Content-Type': 'application/json' },
27    body: JSON.stringify({ data: result }),
28  }
29```
30- Handle errors at the handler level. Return appropriate HTTP status codes for API handlers.
31- Use environment variables for configuration. Never hardcode ARNs, table names, or endpoints.
32- Keep Lambda packages small. Use tree-shaking and avoid bundling unnecessary dependencies.
33- Use `esbuild` or `tsup` for bundling Lambda functions.
34 
35## DynamoDB
36 
37- Design tables for your access patterns first. Create an access pattern document before designing the schema.
38- Use single-table design for related entities when access patterns benefit from it.
39- Primary key design: choose partition key (PK) and sort key (SK) that support your main query patterns.
40- Use Generic Attribute Names for single-table design: `PK`, `SK`, `GSI1PK`, `GSI1SK`, `EntityType`.
41- Denormalize data — DynamoDB is not a relational database. Duplicate data to avoid joins.
42- Use Global Secondary Indexes (GSIs) for alternate access patterns. Minimize the number of GSIs (cost).
43- Use `ExpressionAttributeNames` and `ExpressionAttributeValues` in all queries to prevent injection.
44- Use `UpdateExpression` with `SET`, `REMOVE`, `ADD`, `DELETE` operations for partial updates.
45- Implement optimistic locking with version attributes and `ConditionExpression`.
46- Use TTL (`TimeToLive`) for auto-expiring items (sessions, temporary tokens, logs).
47- Use `BatchWriteItem` for bulk writes (max 25 items). Use `BatchGetItem` for bulk reads (max 100 items).
48- Handle `ConditionalCheckFailedException` for race conditions.
49- Use DynamoDB Streams for event-driven processing (change data capture).
50 
51## SAM Template Design
52 
53- Use AWS SAM (`template.yaml`) for all infrastructure definitions. Prefer SAM over raw CloudFormation for Lambda.
54- Define globals for shared Lambda configuration:
55```yaml
56  Globals:
57    Function:
58      Runtime: nodejs20.x
59      Timeout: 30
60      MemorySize: 256
61      Environment:
62        Variables:
63          TABLE_NAME: !Ref MainTable
64```
65- Use `AWS::Serverless::Function` for Lambda functions with event source mappings.
66- Use `AWS::Serverless::Api` for API Gateway REST API, or `AWS::Serverless::HttpApi` for HTTP API (v2).
67- Define DynamoDB tables with `AWS::DynamoDB::Table`. Include `BillingMode: PAY_PER_REQUEST` for serverless scaling.
68- Use `!Ref`, `!GetAtt`, `!Sub`, and `!Join` for dynamic resource references. Never hardcode ARNs.
69- Use parameter overrides for environment-specific values (stage, domain, feature flags).
70- Organize large templates with nested stacks or AWS SAM `AWS::Include`.
71 
72## API Gateway
73 
74- Use HTTP API (v2) for REST APIs — it's faster and cheaper than REST API (v1).
75- Define routes with event source mappings on Lambda functions.
76- Use Lambda authorizers for custom auth logic, or Cognito authorizers for Cognito-backed auth.
77- Enable CORS explicitly with allowed origins, methods, and headers.
78- Use request validation with API Gateway models to reject malformed requests early.
79- Use stage variables for environment-specific configuration.
80- Implement throttling and usage plans to protect against abuse.
81- Use custom domain names with Route 53 and ACM certificates.
82 
83## Error Handling
84 
85- Create a standardized error response format:
86```typescript
87  interface ErrorResponse {
88    statusCode: number
89    body: string // JSON: { error: { code: string, message: string, requestId: string } }
90  }
91```
92- Use custom error classes: `ValidationError`, `NotFoundError`, `ConflictError`, `UnauthorizedError`.
93- Map error types to HTTP status codes in a centralized error handler.
94- Include `requestId` (from Lambda context) in all error responses for debugging.
95- Log errors with full context using structured logging (Powertools Logger).
96- Use Dead Letter Queues (DLQ) on async Lambda invocations (SQS, SNS) to capture failed events.
97- Implement retry logic with exponential backoff for transient AWS service errors.
98- Use `AWSError` type checking for SDK errors: `if (error.name === 'ConditionalCheckFailedException')`.
99 
100## Logging and Monitoring
101 
102- Use `@aws-lambda-powertools/logger` for structured JSON logging.
103- Log at appropriate levels: `logger.error()`, `logger.warn()`, `logger.info()`, `logger.debug()`.
104- Include correlation IDs across Lambda invocations for request tracing.
105- Use `@aws-lambda-powertools/tracer` for X-Ray tracing. Annotate traces with custom metadata.
106- Use `@aws-lambda-powertools/metrics` for CloudWatch custom metrics.
107- Set up CloudWatch Alarms for: error rates, throttling, duration p99, DLQ depth.
108- Never log sensitive data (PII, credentials, tokens). Use `logger.removeKeys()` to strip sensitive fields.
109 
110## Testing
111 
112- Use Vitest for unit tests. Mock AWS SDK clients with `aws-sdk-client-mock`.
113- Test Lambda handlers by invoking them directly with typed event objects.
114- Test business logic independently from Lambda-specific code.
115- Use `sam local invoke` for local integration testing.
116- Use `sam local start-api` for testing API Gateway integrations locally.
117- Create test event JSON files for each event source type.
118- Use DynamoDB Local for database integration tests.
119- Test IAM permissions with `sam validate` and `cfn-lint`.
120 
121## File Structure
122 
123```
124functions/
125  get-user/
126    handler.ts         — Lambda handler
127    index.ts           — Entry point (re-exports handler)
128  create-user/
129    handler.ts
130    index.ts
131lib/
132  services/
133    user-service.ts    — Business logic
134  repositories/
135    user-repo.ts       — DynamoDB operations
136  models/
137    user.ts            — Domain types
138  utils/
139    response.ts        — HTTP response helpers
140    errors.ts          — Custom error classes
141    dynamodb.ts        — DynamoDB client and helpers
142  middleware/
143    auth.ts            — Auth validation
144    validation.ts      — Input validation with Zod
145events/
146  get-user.json        — Test events for local testing
147  create-user.json
148template.yaml          — SAM template
149samconfig.toml         — SAM deployment config
150tsconfig.json
151package.json
152```
153 
154## Security
155 
156- Follow the principle of least privilege for IAM roles. Each Lambda gets only the permissions it needs.
157- Use resource-based policies: restrict DynamoDB access to specific table ARNs, not `*`.
158- Use `AWS::Serverless::Function` `Policies` property with SAM policy templates: `DynamoDBCrudPolicy`, `S3ReadPolicy`.
159- Validate and sanitize all input in Lambda handlers before processing.
160- Use KMS for encrypting environment variables with sensitive values.
161- Use Secrets Manager or SSM Parameter Store for secrets, not environment variables.
162- Enable API Gateway throttling and WAF for public-facing APIs.
163- Enable CloudTrail for auditing all API calls to AWS services.
164- Use VPC configuration for Lambda functions that need to access VPC resources.
165 
166## Performance
167 
168- Initialize SDK clients at module scope (outside handler) for connection reuse.
169- Use `MemorySize` strategically — more memory = more CPU = faster execution (and can be cheaper).
170- Use Provisioned Concurrency for latency-sensitive functions to eliminate cold starts.
171- Use Lambda Layers for shared code and large dependencies (reduces package size).
172- Use DynamoDB `ProjectionExpression` to fetch only needed attributes.
173- Enable DynamoDB Auto Scaling or use On-Demand billing mode.
174- Use SQS with Lambda for async processing to smooth out traffic spikes.
175- Use S3 Transfer Acceleration for large file uploads from distant clients.
176- Use CloudFront for caching API responses and static assets.
177- Monitor with CloudWatch Insights to find slow and expensive invocations.
178