Serverless boilerplate based on serverless-webpack + typescript. Define ready to deploy project with predefined scripts, linter-prettier rules, basic lib and helpers. Based on pseudo Onion Architecture: lambda[controller] -> (services + helpers)[[domain layer]] -> repositories.
In order to dig deeper in onion architecture check this boilerplate: https://github.com/Melzar/onion-architecture-boilerplate
$: npm i -g serverless # install serverless framework
$: sls create --template https://github.com/collierrgbsitisfise/serverless-bonk-template --path <dir name>- serverless-webpack
- serverless-offline
- serverless-dotenv-plugin
- serverless-prune-plugin
- serverless-iam-roles-per-function
.
├── resources # resources such as VPC, DynamoDB Tables etc.
├── scripts # will be used in CI/CD, development process - should not be part of production bundle.
├── schemas # schemas to validate API request on API gateway level.
├── @mocks # mocks which will be used in tests/development.
├── @types # types.
├── env # env files.
├── lib # helpers to operate with lambdas itself, should not be used inside lambda, should not operate somehow with business logic.
├── apiGatewayLambdaWrapper.ts # wrap lambdas which are linked to api gateway.
├── cloudWatchLambdaWrapper.ts # wrap lambdas which are subscribed to cloud watch event.
├── snsLambdaWrapper.ts # wrap lambdas which are subscribed to sns message.
├── sqsLambdaWrapper.ts # wrap lambdas which are subscribed to sqs message.
└── dynamoDBStreamLambdaWrapper.ts # wrap lambdas which are subscribed to dynamoDB stream.
├── src
│ ├── functions # lambda fucntions.
│ │ ├── example
│ │ │ ├── example.ts # `Example` lambda source code.
│ │ │ └── example.yaml # `Example` function template part.
│ │ │
│ │ └── index.ts # import/export all lambdas.
│ │
│ ├── helpers # helpers which are used inside src folder.
│ ├── services # services logic which will operate with external API/repositories, will contain domain logic.
│ └── repositories # operate with database.
│
├── package.json
├── serverless.ts # serverless service file.
├── tsconfig.json # typescript compiler configuration
├── tsconfig.paths.json # typescript paths
├── webpack.config.js # webpack configuration
├── .eslintrc.js # ESlint config
└── .prettierrc.js # prettier config
| Command | Script |
|---|---|
| Lint | npm run lint |
| Prettier | npm run prettier |
| Typescript check | npm run ts-check |
| Test | npm run test |
| Setup env | ENV=<envValue> npm run setup # will create .env on root level |
-
Run next commands
$: ENV=<envValue> npm run setup # setup env file
$: npm run deploy # deployOn the libs folder are defined utils which will operate with lambda itself. The libs utils should't be used inside handler. In boilerplate are predefined lambda wrappers for base case scenario lambda use:
- lambda tied to dynamodb stream
- lambda tied to sns
- lambda tied to sqs
- lambda tied to cloudwatch event
- lambda tied to ApiGateway
Wrapper for lambda tied to dynamoDB stream
import { DynamoDBStreamEvent, Context, Callback } from 'aws-lambda';
export const dynamoDblambdaWrapper = (
lambda: (event: DynamoDBStreamEvent, context: Context, callback: Callback) => Promise<any>,
onSucces: (event: DynamoDBStreamEvent, result: any) => any | PromiseLike<any>,
onError: (event: DynamoDBStreamEvent, error: Error) => any | PromiseLike<any>,
) => {
return function wrapp(event: DynamoDBStreamEvent, context?: Context, callback?: Callback): Promise<any> {
return Promise.resolve()
.then(() => lambda(event, context, callback))
.then((res: any) => onSucces(event, res))
.catch((err: Error) => onError(event, err));
};
};Wrapper for lambda tied to ApiGateway
export type Headers = { [key: string]: string };
export type LambdaFunction = (
event: APIGatewayEvent,
context?: Context,
callback?: Callback,
) => [any, number, Headers] | Promise<[any, number, Headers]>;
export type OnSuccesHandler = (
value: any,
statusCode: number,
headers?: Headers,
) => APIGatewayProxyResult | PromiseLike<APIGatewayProxyResult>;
export type OnErrorHandle = (error: Error) => Promise<APIGatewayProxyResult>;
const defaultHeaders = {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Credentials': true,
};
const onSuccesHandler = (
data: any,
statusCode: number,
headers?: Headers,
): APIGatewayProxyResult | PromiseLike<APIGatewayProxyResult> => ({
statusCode,
headers: {
...defaultHeaders,
...headers,
},
body: JSON.stringify(data),
});
const onErrorHandler = async (error: Error): Promise<APIGatewayProxyResult> => {
return {
statusCode: 500,
headers: defaultHeaders,
body: JSON.stringify(error),
};
};
export const apiGatewayLambdaWrapper = (
lambda: LambdaFunction,
onSucces: OnSuccesHandler = onSuccesHandler,
onError: OnErrorHandle = onErrorHandler,
) => {
return function wrapp(event: APIGatewayEvent, context: Context, callback: Callback): Promise<APIGatewayProxyResult> {
return Promise.resolve()
.then(() => lambda(event, context, callback))
.then(([res, code, headers]: [any, number, Headers]) => onSucces(res, code, headers))
.catch(onError);
};
};Some raw data(example of sns message, api request, sqs message, etc) which could be used during local development or for test.
general types, which will be used across project..
For each environment should be predefined <ENV>.env file, which will be used by setup-script before deploy.
Should't contain sensitive info such as secrets , db passwords, etc. Such kind of info must be retrived from secret-manager in runtime
Define resources which will be created/updated on deploy, such as dynamodb table, SqlRDSInstance, etc.
Define request schemas by which ApiGateway will validate request. Also could be defined response schemas. All of them could be used in test or/and for documentation
.js files which usually are used in CI/CD. Also it could be used in development purpose.
Scripts examples example:
- setup .env variables
- setup development webhooks using ngrok
- adding additional
.envvariables on CI/CD - purge cloudfront cache
Internal logic of application services, repository, helpers.
There is an article which describes one of the predefined helpers