ssp

serverless-scriptable-plugin

Adding script support to Serverless 1.x which enables you to customize Serverless behavior without writing a plugin.

Showing:

Popularity

Downloads/wk

15.7K

GitHub Stars

90

Maintenance

Last Commit

1mo ago

Contributors

9

Package

Dependencies

1

Size (min+gzip)

23.3KB

License

ISC

Type Definitions

Tree-Shakeable

No?

Categories

Readme

npm version npm Build Status Test Coverage Code Climate Issue Count

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:

  • Run any command or nodejs scripts in any stage of serverless lifecycle
  • Add custom commands to serverless, e.g. npx serverless YOUR-COMMAND Example

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

Example

  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. Add a custom command to serverless

    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. 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:
          after:package:createDeploymentArtifacts: zip -q -r .serverless/package.zip src node_modules
    
    service: service-name
    package:
      artifact: .serverless/package.zip
    
  4. 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 }
          }
        }
      );
    
  5. Run multiple commands for the serverless event

    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
    
  1. Suppress console output (Optional) 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

  • Version 0.8.0 and above

  • Version 0.7.1

    • [Feature] Fix vulnerability warning by remove unnecessary dev dependencies
  • Version 0.7.0

    • [Feature] Return promise object to let serverless to wait until script is finished
  • Version 0.6.0

    • [Feature] Supported execute multiple script/command for the same serverless event
  • Version 0.5.0

    • [Feature] Supported serverless variables in script/command
    • [Improvement] Integrated with codeclimate for code analysis and test coverage
  • Version 0.4.0

    • [Feature] Supported colored output in script/command
    • [Improvement] Integrated with travis for CI
  • Version 0.3.0

    • [Feature] Supported to execute any command for serverless event
  • Version 0.2.0

    • [Feature] Supported to execute javascript file for serverless event

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial