Home

Awesome

npm version npm Build Status Test Coverage Code Climate Issue Count license

What's the plugins for?

This plugin allows you to write scripts to customize Serverless behavior for Serverless 1.x and upper

It also supports running node.js scripts in any build stage.

Features:

Quick Start

  1. Install 
    npm install --save-dev serverless-scriptable-plugin
  2. Add to Serverless config 
    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    # add custom hooks
    hooks:
      before:package:createDeploymentArtifacts: npm run build

    # or custom commands
    commands:
      migrate: echo Running migration

Upgrade from <=1.1.0

This serverless-scriptable-plugin now supports event hooks and custom commands. Here's an example of upgrade to the latest schema. The previous config schema still works for backward compatibility.

Example that using the previous schema:

plugins:
  - serverless-scriptable-plugin

custom:
  scriptHooks:
    before:package:createDeploymentArtifacts: npm run build

Changed to:

plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    hooks:
      before:package:createDeploymentArtifacts: npm run build

Examples

  1. Customize package behavior

    The following config is using babel for transcompilation and packaging only the required folders: dist and node_modules without aws-sdk

    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    hooks:
      before:package:createDeploymentArtifacts: npm run build

package:
  exclude:
    - '**/**'
    - '!dist/**'
    - '!node_modules/**'
    - node_modules/aws-sdk/**

  2. <a name="custom-command"></a>Add a custom command

    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    hooks:
      before:migrate:command: echo before migrating
      after:migrate:command: echo after migrating
    commands:
      migrate: echo Running migration

    Then you could run this command by:

    $ npx serverless migrate
Running command: echo before migrating
before migrating
Running command: echo Running migrating
Running migrating
Running command: echo after migrating
after migrating

  3. Deploy python function

    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
      hooks:
        before:package:createDeploymentArtifacts: ./package.sh

# serverless will use the specified package that generated by `./package.sh`
package:
  artifact: .serverless/package.zip

    and package.sh script file to package the zip file (https://docs.aws.amazon.com/lambda/latest/dg/python-package.html)

      PACKAGE_FILE=.serverless/package.zip
  rm -f $PACKAGE_FILE && rm -rf output && mkdir -p output
  pip install -r requirements.txt --target output/libs
  # You can use the following command to install if you are using pipenv
  # pipenv requirements > output/requirements.txt && pip install -r output/requirements.txt --target output/libs
  (cd output/libs && zip -r ../../$PACKAGE_FILE . -x '*__pycache__*')
  (zip -r $PACKAGE_FILE your-src-folder -x '*__pycache__*')

    Serverless would then deploy the zip file you built to aws lambda.

  4. Run any command as a hook script

    It's possible to run any command as the hook script, e.g. use the following command to zip the required folders

    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    hooks:
      before:package:createDeploymentArtifacts: zip -q -r .serverless/package.zip src node_modules

service: service-name
package:
  artifact: .serverless/package.zip

  5. Dynamically change resources

    Create CloudWatch Log subscription filter for all Lambda function Log groups, e.g. subscribe to a Kinesis stream

    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    hooks:
      after:package:compileEvents: build/serverless/add-log-subscriptions.js

provider:
  logSubscriptionDestinationArn: 'arn:aws:logs:ap-southeast-2:{account-id}:destination:'

    and in build/serverless/add-log-subscriptions.js file:

    const resources = serverless.service.provider.compiledCloudFormationTemplate.Resources;
const logSubscriptionDestinationArn = serverless.service.provider.logSubscriptionDestinationArn;

Object.keys(resources)
  .filter(name => resources[name].Type === 'AWS::Logs::LogGroup')
  .forEach(logGroupName => resources[`${logGroupName}Subscription`] = {
      Type: "AWS::Logs::SubscriptionFilter",
      Properties: {
        DestinationArn: logSubscriptionDestinationArn,
        FilterPattern: ".",
        LogGroupName: { "Ref": logGroupName }
      }
    }
  );

  6. Run multiple commands

    It's possible to run multiple commands for the same serverless event, e.g. Add CloudWatch log subscription and dynamodb auto scaling support

    plugins:
  - serverless-scriptable-plugin

custom:
  scriptable:
    hooks:
      after:package:createDeploymentArtifacts: 
        - build/serverless/add-log-subscriptions.js
        - build/serverless/add-dynamodb-auto-scaling.js

service: service-name
package:
  artifact: .serverless/package.zip

  7. Suppress console output

    You could control what to show during running commands, in case there are sensitive info in command or console output.

    custom:
  scriptable:
    showStdoutOutput: false # Default true. true: output stderr to console, false: output nothing
    showStderrOutput: false # Default true. true: output stderr to console, false: output nothing
    showCommands: false # Default true. true: show the command before execute, false: do not show commands

    hooks:
      ...
    commands:
      ...

Hooks

The serverless lifecycle hooks are different to providers, here's a reference of AWS hooks: https://gist.github.com/HyperBrain/50d38027a8f57778d5b0f135d80ea406#file-lifecycle-cheat-sheet-md

Change Log