{"id":27779354,"url":"https://github.com/thunder-so/cdk-functions","last_synced_at":"2025-04-30T09:58:16.322Z","repository":{"id":288994346,"uuid":"961025704","full_name":"thunder-so/cdk-functions","owner":"thunder-so","description":"The easiest way to deploy an API on AWS Lambda with modern web frameworks. Supports Express, Hono, Fastify, Adonis.js, Nest.js and any web app framework.","archived":false,"fork":false,"pushed_at":"2025-04-29T01:36:37.000Z","size":32,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-29T02:48:07.037Z","etag":null,"topics":["adonis-framework","adonisjs","api","apigateway","apigateway-lambda","aws-lambda","expressjs","fastify","fastifyjs","feathersjs","hono","honojs","koajs","lambda","lambda-functions","nestjs","restify","sailsjs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@thunderso/cdk-functions","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thunder-so.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-05T15:38:34.000Z","updated_at":"2025-04-29T01:36:40.000Z","dependencies_parsed_at":"2025-04-20T23:27:17.835Z","dependency_job_id":"947d165f-f943-49f7-839e-f9abb85b9efe","html_url":"https://github.com/thunder-so/cdk-functions","commit_stats":null,"previous_names":["thunder-so/cdk-functions"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunder-so%2Fcdk-functions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunder-so%2Fcdk-functions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunder-so%2Fcdk-functions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thunder-so%2Fcdk-functions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thunder-so","download_url":"https://codeload.github.com/thunder-so/cdk-functions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251425092,"owners_count":21587432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adonis-framework","adonisjs","api","apigateway","apigateway-lambda","aws-lambda","expressjs","fastify","fastifyjs","feathersjs","hono","honojs","koajs","lambda","lambda-functions","nestjs","restify","sailsjs"],"created_at":"2025-04-30T09:58:15.787Z","updated_at":"2025-04-30T09:58:16.309Z","avatar_url":"https://github.com/thunder-so.png","language":"TypeScript","readme":"# CDK-Functions\n\n\u003cp\u003e\n    \u003ca href=\"https://github.com/thunder-so/cdk-functions/actions/workflows/publish.yml\"\u003e\u003cimg alt=\"Build\" src=\"https://img.shields.io/github/actions/workflow/status/thunder-so/cdk-functions/publish.yml?logo=github\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@thunderso/cdk-functions\"\u003e\u003cimg alt=\"Version\" src=\"https://img.shields.io/npm/v/@thunderso/cdk-functions.svg\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@thunderso/cdk-functions\"\u003e\u003cimg alt=\"Downloads\" src=\"https://img.shields.io/npm/dm/@thunderso/cdk-functions.svg\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@thunderso/cdk-functions\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/npm/l/@thunderso/cdk-functions.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nThe easiest way to deploy an API on AWS Lambda with modern web frameworks. \n\nSupported frameworks:\n\n- [Express.js](https://expressjs.com/)\n- [Hono](https://hono.dev/)\n- [Fastify](https://www.fastify.io/)\n- [Koa](https://koajs.com/)\n- [NestJS](https://nestjs.com/)\n- [AdonisJS](https://adonisjs.com/)\n- [Sails.js](https://sailsjs.com/)\n- [LoopBack](https://loopback.io/)\n- [Feathers](https://feathersjs.com/)\n- [Restify](http://restify.com/)\n- Any web application framework\n\nAWS resources:\n\n- Server-side logic with [AWS Lambda](https://aws.amazon.com/lambda/) for dynamic content and API handling\n- Publicly available by a custom domain (or subdomain) via [Route53](https://aws.amazon.com/route53/) and SSL via [Certificate Manager](https://aws.amazon.com/certificate-manager/)\n- [Amazon API Gateway](https://aws.amazon.com/api-gateway/) for creating, deploying, and managing secure APIs at any scale.\n- Environment variables can be securely stored and managed using [AWS Systems Manager Parameter Store](https://aws.amazon.com/systems-manager/features/#Parameter_Store).\n- Build and deploy with [Github Actions](https://docs.github.com/en/actions)\n\n\n## Prerequisites\n\nYou need an [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) to create and deploy the required resources for the site on AWS.\n\nBefore you begin, make sure you have the following:\n  - Node.js and npm: Ensure you have Node.js (v18 or later) and npm installed.\n  - AWS CLI: Install and configure the AWS Command Line Interface.\n\n  - AWS CDK: Install the AWS CDK globally\n```\nnpm install -g aws-cdk\n```\n\n  - Before deploying, bootstrap your AWS environment:\n```\ncdk bootstrap aws://your-aws-account-id/us-east-1\n```\n\nThis package uses the `npm` package manager and is an ES6+ Module.\n\n## Installation\n\nNavigate to your project directory and install the package and its required dependencies. \n\nYour `package.json` must also contain `tsx` and this specific version of `aws-cdk-lib`:\n\n```bash\nnpm i tsx aws-cdk-lib@2.150.0 @thunderso/cdk-functions --save-dev\n```\n\n\n## Setup\n\n1. Login into the AWS console and note the `Account ID`. You will need it in the configuration step.\n\n2. Run the following commands to create the required CDK stack entrypoint at `stack/index.ts`. \n\n```bash\nmkdir stack\ncd stack\ntouch index.ts \n```\n\nYou should adapt the file to your project's needs.\n\n\u003e [!NOTE]\n\u003e Use different filenames such as `production.ts` and `dev.ts` for environments.\n\n## Configuration\n\n```ts\n//stack/index.ts\nimport { App } from \"aws-cdk-lib\";\nimport { FunctionStack, type FunctionProps } from '@thunderso/cdk-functions';\n\nconst fnStackProps: FunctionProps = {\n\n  // Set your AWS environment\n  env: {\n    account: 'your-account-id',\n    region: 'us-east-1',\n  },\n  \n  // Label your infrastructure\n  application: 'your-application-id',\n  service: 'your-service-id',\n  environment: 'dev',\n\n  rootDir: '', // supports monorepos e.g. api/ \n\n  // Configure the function\n  functionProps: {\n    codeDir: 'dist/',\n    handler: 'index.handler',\n  },\n\n};\n\nnew FunctionStack(new App(), \n    `${fnStackProps.application}-${fnStackProps.service}-${fnStackProps.environment}-stack`, \n    fnStackProps\n);\n```\n\n## Deploy\n\nBy running the following script, the CDK stack will be deployed to AWS.\n\n```bash\nnpx cdk deploy --require-approval never --all --app=\"npx tsx stack/index.ts\" \n```\n\n## Destroy the Stack\n\nIf you want to destroy the stack and all its resources (including storage, e.g., access logs), run the following script:\n\n```bash\nnpx cdk destroy --require-approval never --all --app=\"npx tsx stack/index.ts\" \n```\n\n\n# Deploy using GitHub Actions\n\nIn your GitHub repository, add a new workflow file under `.github/workflows/deploy.yml` with the following content:\n\n```yaml .github/workflows/deploy.yml\nname: Deploy Function to AWS\n\non:\n  push:\n    branches:\n      - main  # or the branch you want to deploy from\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Build application\n        run: npm run build\n\n      - name: Deploy to AWS\n        run: |\n          npx cdk deploy --require-approval never --all --app=\"npx tsx stack/index.ts\"\n        env:\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          AWS_DEFAULT_REGION: 'us-east-1'  # or your preferred region\n```\n\nAdd `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as repository secrets in GitHub. These should be the access key and secret for an IAM user with permissions to deploy your stack.\n\n\n# Manage Domain with Route53\n\n1. [Create a hosted zone in Route53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html) for the desired domain, if you don't have one yet.\n\n  This is required to create DNS records for the domain to make the app publicly available on that domain. On the hosted zone details you should see the `Hosted zone ID` of the hosted zone.\n\n2. [Request a public regional certificate in the AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) for the desired domain in the same region as the function and validate it, if you don't have one yet.\n\n  This is required to provide the app via HTTPS on the public internet. Take note of the displayed `ARN` for the certificate. \n\n\u003e [!IMPORTANT]\n\u003e The certificate must be issued in the same region as the function.\n\n```ts\n// stack/index.ts\nconst fnStackProps: FunctionProps = {\n  // ... other props\n\n  domain: 'api.example.com',\n  hostedZoneId: 'XXXXXXXXXXXXXXX',\n  regionalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-abcd-1234-abcd-1234abcd1234',\n};\n```\n\n# Using environment variables\n\nCreate a secure parameter in SSM Parameter Store:\n\n```bash\naws ssm put-parameter --name \"/my-app/API_KEY\" --type \"SecureString\" --value \"your-secret-api-key\"\n```\n\nPass environment variables to your lambda function to inject secrets. The library automatically adds the necessary permissions to the Lambda function's role to read parameters from SSM Parameter Store.\n\n```ts\n// stack/index.ts\nconst appStackProps: SPAProps = {\n  // ... other props\n\n  environmentVariables: [\n    { key: 'API_URL', resource: '/my-app/API_URL' },\n    { key: 'API_KEY', resource: '/my-app/API_KEY' },\n  ],\n\n};\n```\n\n# Configure the Lambda\n\nEach configuration property provides a means to fine-tune your function’s performance and operational characteristics.\n\n```ts\n// stack/index.ts\nimport { App } from \"aws-cdk-lib\";\nimport { Runtime, Architecture } from 'aws-cdk-lib/aws-lambda';\nimport { FunctionStack, type FunctionProps } from '@thunderso/cdk-functions';\n\nconst fnStackProps: FunctionProps = {\n  // ... other props\n  \n  functionProps: {\n    url: true,\n    runtime: Runtime.NODEJS_20_X,\n    architecture: Architecture.ARM_64,\n    codeDir: 'dist',\n    handler: 'index.handler',\n    memorySize: 1792,\n    timeout: 10,\n    tracing: true,\n    exclude: ['**/*.ts', '**/*.map'],\n  },\n\n};\n\nnew FunctionStack(new App(), \n    `${fnStackProps.application}-${fnStackProps.service}-${fnStackProps.environment}-stack`, \n    fnStackProps\n);\n```\n\n### `url`\nSpecifies whether to enable Lambda function URL.\n- **Type**: `boolean`\n- **Default**: Defaults to `url: true`.\n\n### `runtime`\nSpecifies the runtime environment for the Lambda function, determining which Lambda runtime API versions are available to the function.\n- **Type**: `Runtime`\n- **Examples**: `Runtime.NODEJS_20_X`, `Runtime.PYTHON_3_8`\n- **Default**: The runtime defaults to `Runtime.NODEJS_20_X`.\n\n### `architecture`\nDefines the instruction set architecture that the Lambda function supports.\n- **Type**: `Architecture`\n- **Examples**: `Architecture.ARM_64`, `Architecture.X86_64`\n- **Default**: The architecture defaults to `Architecture.ARM_64`.\n\n### `codeDir`\nIndicates the directory containing the Lambda function code.\n- **Type**: `string`\n- **Usage Example**: `codeDir: 'dist'`\n- **Default**: `codeDir: ''`.\n\n### `handler`\nSpecifies the function within your code that Lambda calls to start executing your function.\n- **Type**: `string`\n- **Usage Example**: `handler: 'index.handler'`\n- **Default**: `handler: 'index.handler'`\n\n### `exclude`\nLists the file patterns that should be excluded from the Lambda deployment package.\n- **Type**: `string[]`\n- **Usage Example**: `exclude: ['*.test.js', 'README.md']`\n\n### `memorySize`\nThe amount of memory, in MB, allocated to the Lambda function.\n- **Type**: `number`\n- **Default**: 1792 MB\n- **Usage Example**: `memorySize: 512`\n\n### `timeout`\nThe function execution time (in seconds) after which Lambda will terminate the running function.\n- **Type**: `number`\n- **Default**: 10 seconds\n- **Usage Example**: `timeout: 15`\n\n### `tracing`\nEnables or disables AWS X-Ray tracing for the Lambda function.\n- **Type**: `boolean`\n- **Default**: `false`\n- **Usage Example**: `tracing: true`\n\n\n# Advanced: Scaling Properties\n\nWhen configuring AWS Lambda functions, understanding scaling properties is essential for efficient resource management and cost optimization. The two primary scaling properties you can configure are `reservedConcurrency` and `provisionedConcurrency`.\n\n```ts\n// stack/index.ts\nimport { App } from \"aws-cdk-lib\";\nimport { FunctionStack, type FunctionProps } from '@thunderso/cdk-functions';\n\nconst fnStackProps: FunctionProps = {\n  // ... other props\n  \n  functionProps: {\n    // ... other props\n    reservedConcurrency: 5,\n    provisionedConcurrency: 10,\n  },\n\n};\n\nnew FunctionStack(new App(), \n    `${fnStackProps.application}-${fnStackProps.service}-${fnStackProps.environment}-stack`, \n    fnStackProps\n);\n```\n\n### `reservedConcurrency`\nReserved concurrency sets a limit on the number of instances of the function that can run simultaneously. It ensures that your function has access to a specified amount of concurrent executions, preventing it from being throttled if account-level concurrency limits are reached.\n- **Use Case**: This is useful when you want to have predictable execution patterns or ensure other functions don't consume all available concurrency.\n- **Example**: `reservedConcurrency: 5`\n\n### `provisionedConcurrency`\nProvisioned concurrency keeps a set of pre-initialized environments ready to respond immediately to incoming requests. This helps in reducing latency and eliminating cold starts when the function is triggered.\n- **Use Case**: Ideal for latency-sensitive applications where response time is critical.\n- **Example**: `provisionedConcurrency: 10`\n\nWhile both reserved and provisioned concurrency deal with execution limits, they serve different purposes. Reserved concurrency guarantees a portion of the total function pool across your AWS account, while provisioned concurrency is specifically about warming up a set number of function instances to achieve low-latency execution.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthunder-so%2Fcdk-functions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthunder-so%2Fcdk-functions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthunder-so%2Fcdk-functions/lists"}