Serverless Helper

A framework to implement serverless framework config file with ease and standarized resources.

Installation

npm install sls-helper

Usage

// serverless.js

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [

		['bucket', {
			resourceName: 'ServiceBucket',
			name: 'my-bucket'
		}],

		'custom.myHelperWithoutConfigs'
	]
});

Plugins

In order to implement a plugin for the framework, you must publish a package with the following pattern: sls-helper-plugin-{plugin-name}.

The plugin-name must then be used as a prefix to use a helper of that plugin, for example: plugin-name.helperName

The package must export an object mapping helper names to helper implementations.

Each helper is a function that receives the following arguments:

• serviceConfig: The current service config object
• helperParams: The (optional) configuration for the helper.

It also has to return the new service config object.

Plugin list:

• JANIS

Core Helpers

S3 Bucket (bucket)

Used to implement a bucket with blocked public access

| Option | Type | Description | Attributes | Default value | |--------|------|-------------|------------|---------------| | resourceName | string | The logical name of the bucket | Required | | | name | string | The bucket name | Required | | | acl | string | The bucket acl | | Private | | cors | boolean | object | array | The bucket CORS configuration. If set to true, default configuration is set (every origin, every header) | | | | cors.id, cors[].id | string | The CORS rule ID | | | | cors.origin, cors[].origin | array | string | boolean | The CORS rule origin(s) (if value is true, it's set as every origin) | | | | cors.methods, cors[].methods | array | string | The CORS rule method(s) | | | | cors.headers, cors[].headers | array | string | The CORS rule headers(s) | | | | cors.exposedHeaders, cors[].exposedHeaders | array | string | The CORS rule exposed headers(s) | | | | cors.maxAge, cors[].maxAge | number | The CORS rule max age | | | | tags | object | A key-value object of tags to associate to the bucket | | | | rawProps | object | Extra raw properties | See the official documentation | |

Example

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [
		['bucket', {
			resourceName: 'ServiceBucket',
			name: 'my-bucket'
		}]
	]
});

IAM Role Statement (iamStatement)

(since 1.2.0)

Used to implement an IAM Role statement for your service

| Option | Type | Description | Attributes | Default value | |--------|------|-------------|------------|---------------| | effect | string | The IAM statement effect | Enum('Allow', 'Deny') | 'Allow' | | action | string | array<string> | The IAM statement action | Required | | | resource | string | array<string> | The IAM statement resource | Required | |

Example

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [
		['iamStatement', {
			action: [
				's3:PutObject',
				's3:GetObject'
			],
			resource: 'arn:aws:s3:::my-bucket/*'
		}]
	]
});

API Lambda Proxy (apiLambdaProxy)

Used to implement Lambda Proxy APIs

| Option | Type | Description | Attributes | Default value | |--------|------|-------------|------------|---------------| | functionName | string | The function name | Required | | | handler | string | The function handler | Required | | | description | string | The function description | | | | path | string | The API path | Required | | | method | string | The API HTTP method | Required | | | useApiKey | boolean | Whether the API requires API key or not | | false | | queryParameters | object | A key value to map query string parameters to a boolean indicating if it's required or not | | | | requestHeaders | object | A key value to map headers to a boolean indicating if it's required or not | | | | authorizer | string | The authorizer config | See the official documentation | | | cors | object | boolean | See the official documentation | | | | async | boolean | Whether the API will execute as an async lambda or not | | false |

Example

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [
		['apiLambdaProxy', {
			functionName: 'MyFunctionName',
			handler: 'path/to/my.handler',
			path: '/hello-world',
			method: 'get'
		}]
	]
});

Lambda Function (function)

(since 1.1.0)

Used to implement Lambda Functions

| Option | Type | Description | Attributes | Default value | |--------|------|-------------|------------|---------------| | functionName | string | The function name | Required | | | handler | string | The function handler | Required | | | description | string | The function description | | | | events | array[object] | The function events | | | | layers | array[object] | An array of function-level layers. This will override any provider-level layers (since 1.14.0) | | | | addLayers | array[object] | An array of function-level layers. This will be appended to any provider-level layers (since 1.14.0) | | | | timeout | number | The function timeout | | | | memorySize | number | The function memorySize in MB (since 1.10.0) | | | | reservedConcurrency | number | Reserved concurrency limit for the function. By default, AWS uses account concurrency limit (since 1.11.0) | | | | package.include | array[string] | The List of paths of files to include | | | | url | boolean | Set as true to create a Lambda URL resource | | false | | rawProperties | object | Raw properties to be setup in the function configuration object | | |

Example

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [
		['function', {
			functionName: 'MyFunctionName',
			handler: 'path/to/my.handler',
			events: [
				{
					schedule: 'rate(1 hour)',
				},
				{
					s3: {
						bucket: 'myBucket',
						event: 's3:ObjectCreated:*',
						rules: [
							{ prefix: 'somePrefix' },
							{ suffix: 'someSuffix' }
						]
					}
				}
			],
			url: true,
			rawProperties: {
				rawProperties: 1
			}
		}]
	]
});

Environment variables (envVars)

(since 1.3.0)

Used to implement environment variables

Configuration options are the environment variables key-value object

Example

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [
		['envVars', {
			MY_VAR: 'and the value',
			SOME_OTHER_VAR: 'and some other value'
		}]
	]
});

Resource (resource)

(since 1.8.0)

Used to implement custom resources

| Option | Type | Description | Attributes | Default value | |--------|------|-------------|------------|---------------| | name | string | The resource logical name | Required | | | resource | object | The resource configuration object for Cloudformation | Required | |

Example

const { helper } = require('sls-helper');

module.exports = helper({
	hooks: [
		['resource', {
			name: 'MyQueue',
			resource: {
				Type: 'AWS::SQS::Queue',
				Properties: {
					QueueName: 'my-super-queue'
				}
			}
		}]
	]
});