{"id":18158159,"url":"https://github.com/seikho/ship-it","last_synced_at":"2026-05-09T03:36:46.266Z","repository":{"id":57358534,"uuid":"93625096","full_name":"Seikho/ship-it","owner":"Seikho","description":"Quick, dirty, and all batteries included AWS Lambda Deployment","archived":false,"fork":false,"pushed_at":"2017-08-24T04:09:06.000Z","size":72,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-16T21:14:46.562Z","etag":null,"topics":["aws","deployment","lambda","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Seikho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-07T10:52:38.000Z","updated_at":"2022-08-19T03:06:37.000Z","dependencies_parsed_at":"2022-09-26T16:40:49.571Z","dependency_job_id":null,"html_url":"https://github.com/Seikho/ship-it","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Seikho/ship-it","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seikho%2Fship-it","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seikho%2Fship-it/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seikho%2Fship-it/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seikho%2Fship-it/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Seikho","download_url":"https://codeload.github.com/Seikho/ship-it/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Seikho%2Fship-it/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272024755,"owners_count":24860528,"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","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aws","deployment","lambda","nodejs","typescript"],"created_at":"2024-11-02T07:05:45.779Z","updated_at":"2026-05-09T03:36:46.208Z","avatar_url":"https://github.com/Seikho.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project SHIPIT: AWS REST Lambda Deployment\n\n## Purpose\nThe purpose of this library is to create small projects or services that have their deployment configuration baked in.\n\nThis is to minimise the configuration necessary on Continuous Integration (CI) platforms such as Jenkins,\nbut to still retain a sane deployment with staged environments.\n\n## How to include external dependencies\nI recommend the use of `browserify`. Include it was a `devDependency` in your project\nIn `package.json` include a `bundle` script that looks like this:\n```sh\n\"bundle\": \"browserify -e src/index.js -o bundle.js --standalone --bare -x aws-sdk\"\n```\n\n- `e src/index.js`: This is an example of providing the entry point to your Lambda\n- `-o bundle.js`: This is an example of providing an output location for your bundle\n- `--standalone`: Outputs a UMD module which will preserve your module exports for using by Lambda\n- `--bare`: Will exclude Node standard libraries from the bundle\n- `x aws-sdk`: Will exclude `aws-sdk` from the bundle as it is implicitly provided by the Lambda environment\n\nIn your `.registerLambda()`.`files` property, provide `bundle.js` instead of all of the individual modules.\n\n## Gotchas\n\n### Names are Important\n\nThe names are important for maintaing the link between `Deployer` consumption and services on AWS.\n\nIf the Lambda function or API name are renamed, artifacts will remain on AWS that may be running that are not intended.\n\nIf this happens the services must be removed by using the AWS Console (user interface) or by other means.\n\n### Lambdas / RestAPIs must not be shared between projects and `Deployer` instances\n\n**Policies, permissions, and RestAPI resources are deleted during each `.deploy()` call**\n\n**Ensure that RestAPIs (names) and Lambda (names) are not shared between projects and other instances of the `Deployer`.**\n\n## Release Notes\n\n#### v0.6.0\n- [Feature] Support POST body\n  - See `LambdaEvent` type\n\n#### v0.5.0\n- [Feature] Add support for Lambda VPC configuration\n\n#### v0.4.0\n- [Feature] Add support for Lambda run-time environment variables\n\n#### v0.3.0\n- [Breaking] Delete all APIGateway resources and Lambda policies at the beginning of each deploy\n\n#### v0.2.x\n- [Bugfix] Fix config validation log messages\n- [Bugfix] Fix CloudWatchEvent.putTargets call\n\n#### v0.2.0\n- [Feature/Breaking] Make Lambdas re-usable between callers\n- [Feature] Fallback to environment for Deployer config\n- [Feature] Support CloudWatchEvents as callers\n- [Breaking] Move Lambda registration to `Deployer.registerLambda()`\n- [Breaking] Rename `Deployer.register()` to `Deployer.registerCaller()`\n\n## Usage\n\n### Requirements\n\n**Functional Requirements**\n- AWS Account ID\n  - Found in AWS Console -\u003e Support -\u003e Support Center -\u003e Top right corner\n- AWS API Access\n  - AWS secret (Region, Access Key ID, Secret Access Key)\n  - AWS Role with full lambda access\n  - API Gateway name (User determined, Must be unique)\n- Lambda Function names (User determined, Each must be unique)\n\n### API\n\n**Example usage**\n```js\nimport * as path from 'path'\nimport Deployer from 'ship-it'\n\nconst deployer = new Deployer({\n  apiName: 'My Rest API',\n  accountId: '1234567890',\n  region: 'ap-southest-2',\n  accessKeyId: '....',\n  secretAccessKey: '....',\n  role: 'arn:aws:iam::1234567890:role/some-role-name'\n})\n\n// This returns a RegisteredLambda object which can be re-used by callers\nconst lambda = deployer.registerLambda({\n  description: 'My Lambda Function',\n  files: [path.resolve(__dirname, 'handlers', 'index.js')],\n  functionName: 'My-Lambda-Function',\n  handler: 'index.handler'\n})\n\ndeployer.registerCaller({\n  kind: 'api',\n  lambda, // Needs to be a RegisteredLambda from .registerLambda\n  method: 'GET',\n  path: '/users/42',\n  contentType: 'application/json'\n})\n\ndeployer.registerCaller({\n  kind: 'event',\n  lambda,\n  name: 'event-name',\n  schedule: 'rate(1 minute)', // Is a Schedule expression, See: http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html\n  description: 'Trigger my Lambda'\n})\n\n// Is asynchronous\ndeployer.deploy()\n```\n\n#### LambdaEvent\n\n```ts\nexport type LambdaEvent = {\n  body: { [key: string]: any }\n  params: { [pathPart: string]: string }\n  query: {\n    [key: string]: string\n  }\n  header: {\n    [header: string]: string\n  }\n  method: string\n}\n```\n\n#### Deployer\n\nSome configuration will coalesce to specific environment variables:\n- `apiName` -\u003e `process.env.AWS_API_NAME`\n- `accountId` -\u003e `process.env.AWS_ACCOUNT_ID`\n- `region` -\u003e `process.env.AWS_REGION`\n- `accessKeyId` -\u003e `process.env.AWS_ACCESS_KEY_ID`\n- `secretAccessKey` -\u003e `process.env.AWS_SECRET_ACCESS_KEY`\n- `role` -\u003e `process.env.AWS_ROLE`\n\n```ts\ninterface ConstructorParams {\n\n  // Must be unique\n  apiName: string\n\n  // Found in AWS console\n  accountId: string\n\n  // AWS Region\n  region: string\n\n  // Provided by AWS when creating an API key pair\n  accesskeyId: string\n\n  // Provided by AWS when creating an API key pair\n  secretAccessKey: string\n\n  // Provided by AWS when creating an IAM role\n  role: string\n}\nconstructor(params: ConstructorParams)\n```\n\n#### Deployer.registerLambda\n\n```ts\nfunction registerLambda(lambda: Lambda): RegisteredLambda\n```\n\n```ts\ninterface RegisteredLambda extends Lambda {\n  id: number\n}\n\ntype File = \n  | string\n  | { path: string, folder: string }\n\ninterface Lambda {\n  /**\n   * Formal Lambda function name\n   * Must be unique\n   */\n  functionName: string\n\n  /**\n   * Human readable description of the Lambda function\n   */\n  description: string\n\n  /**\n   * [filename].[function].\n   * E.g. 'index.handler'\n   * Where:\n   * - 'index.js' is in the root of the archive\n   * - 'handler' is exported as 'export function handler(...)'\n   */\n  handler: string\n\n  // Defaults to 128\n  memorySize?: number\n\n  // Defaults to 15\n  timeout?: number\n\n  /**\n   * Environment variables for the Lambda function at run-time\n   */\n  environment?: { [key: string]: string }\n\n  /**\n   * Absolute paths to the files to be included in the zip file\n   *\n   * Or { path: string, folder: string } where folder is the destination inside the Lambda folder context\n   * This enables relative 'require()'s to help project structure not become one flat folder\n   * when working on multiple Lambdas in a single project\n   */\n  files: File[]\n}\n\n```\n\n#### Deployer.registerCaller(caller: Caller)\n\n```ts\nfunction registerCaller(caller: Caller): void\n```\n\n```ts\ntype Caller = APICaller | EventCaller\n```\n\n```ts\ninterface APICaller {\n    // 'event' will be supported in the future\n    kind: 'api'\n\n    // HTTP Method of the caller\n    // 'GET', 'PUT', 'POST', 'DELETE', ...\n    method: string\n\n    // Route path of the resource\n    // E.g. /users\n    path: string\n\n    // Return Content-Type of the Lambda\n    // E.g. application/json\n    contentType: string\n}\n```\n```ts\ninterface EventCaller {\n  kind: 'event'\n\n  /**\n   * Name of the event\n   * E.g. my-schedule-event\n   */\n  name: string\n\n  /**\n   * Human readable description of the event\n   * E.g. \"Hourly update trigger\"\n   */\n  description: string\n\n  /**\n   * Cron or Rate expression\n   * See: http://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html\n   */\n  schedule: string\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseikho%2Fship-it","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseikho%2Fship-it","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseikho%2Fship-it/lists"}