Serverless Plugin Scripts

1.0.2 · abandoned · verified Tue Apr 21

serverless-plugin-scripts is a utility plugin for the Serverless Framework that extends its capabilities by allowing users to define custom shell commands and attach scripts to existing Serverless lifecycle events directly within their `serverless.yml` configuration files. The latest stable version, 1.0.2, was released in October 2017. As the project has not seen any updates or commits since then, it is considered abandoned and is no longer actively maintained. While it might still function with older Serverless Framework versions (specifically pre-v2, and likely struggling with v3+), it lacks compatibility with recent major Serverless releases and modern JavaScript/TypeScript project setups. There is no active release cadence, and users should be aware of potential security vulnerabilities or runtime issues due to its age. Its key differentiator was offering a simple, declarative way to embed shell commands into the Serverless deployment and development workflow, mitigating the need for external build scripts for simple operations. However, for robust CI/CD or complex build processes, more modern and maintained alternatives are recommended.

Common errors

```
Plugin "serverless-plugin-scripts" isn't a valid plugin
```
cause The Serverless Framework version being used is too new (e.g., v3+) and has breaking changes that prevent this old plugin from loading correctly.

fix Downgrade your Serverless Framework CLI version (e.g., `npm install -g serverless@~1`) or remove this plugin and migrate its functionality to external scripts or a newer, compatible plugin.
```
custom.scripts.commands.myCommand: must be a string
```
cause The command handler for a custom script command in `serverless.yml` was provided as an object instead of a direct string, or an incorrect YAML structure was used.

fix Ensure that simple commands are defined as a single string, e.g., `myCommand: 'echo Hello'`. For more complex configurations (like adding a description), use the `handler` property: `myCommand: { handler: 'echo Hello', description: '...' }`.
```
Error: spawn npm ENOENT
```
cause A script defined in `custom.scripts.hooks` or `commands` attempts to execute a command (like `npm`, `yarn`, `aws`, etc.) that is not found in the environment's PATH.

fix Ensure all necessary executables are installed and accessible in the system's PATH where the Serverless command is executed. For CI/CD, verify the build environment setup.
```
Cannot read property 'service' of undefined
```
cause Variable interpolation using `${self:service}` or similar might fail if the Serverless context is not fully initialized or accessible at the point the script is invoked, or due to incompatibility with newer Serverless versions.

fix This issue might indicate a deeper incompatibility with the Serverless Framework version. For simpler cases, ensure the `service` property is defined at the top of your `serverless.yml`. For complex scenarios, it may necessitate migrating away from this abandoned plugin.

Warnings

breaking This plugin is effectively abandoned since its last update in October 2017. It is highly unlikely to be compatible with Serverless Framework versions 3.x and above, which introduced significant breaking changes to the plugin system.
Fix: Consider migrating to a more actively maintained plugin or implementing custom script execution directly within your CI/CD pipeline or build scripts. Manually executing `npm run build` as part of your deployment process is often a safer alternative.
gotcha Executing shell commands directly via a plugin can pose security risks if the commands are not carefully vetted or if user input is incorporated without proper sanitization. Given the plugin's abandoned status, there will be no security patches for potential vulnerabilities.
Fix: Minimize the scope of executed commands, avoid direct user input, and prioritize alternative, more secure methods for complex operations. Regularly review the commands for potential exploits.
deprecated The Serverless Framework has evolved significantly since this plugin's last release. Some lifecycle event names or core functionalities might have changed or been deprecated, leading to scripts not being invoked as expected.
Fix: Consult the official Serverless Framework documentation for your specific version to verify correct lifecycle event names and plugin API usage. Consider updating to a newer, maintained plugin if available.

Install

npm install serverless-plugin-scripts npm
yarn add serverless-plugin-scripts yarn
pnpm add serverless-plugin-scripts pnpm

Imports

Plugin Activation
```
plugins:
  - serverless-plugin-scripts
```
This plugin is activated by listing its name under the `plugins` section in `serverless.yml`. It does not expose any direct JavaScript exports for `import` or `require` statements in your application code; its functionality is entirely configuration-driven.
Custom Commands
```
custom:
  scripts:
    commands:
      myCommand: echo 'Running my custom command'
```
Custom CLI commands are defined within the `custom.scripts.commands` block in `serverless.yml`. These commands can then be invoked via `serverless myCommand` from the terminal.
Lifecycle Hooks
```
custom:
  scripts:
    hooks:
      'deploy:createDeploymentArtifacts': npm run build
```
Scripts attached to Serverless lifecycle events are defined under `custom.scripts.hooks` in `serverless.yml`. The event names must exactly match Serverless Framework's internal events (e.g., `deploy:createDeploymentArtifacts`).

Quickstart

This quickstart demonstrates how to install `serverless-plugin-scripts`, configure custom CLI commands and lifecycle hooks in `serverless.yml`, and execute them using the Serverless CLI.

# serverless.yml
service: my-serverless-app

plugins:
  - serverless-plugin-scripts

custom:
  scripts:
    commands:
      hello: echo "Hello from ${self:service} service at $(date) using Serverless Framework!"
      greet:
        handler: echo "Greeting from serverless-plugin-scripts. The first argument is $1"
        description: "Greets with an optional argument"
    hooks:
      'deploy:createDeploymentArtifacts': npm run build-frontend # Example build step
      'package:createPackage': echo "Packaging started for ${self:service} at $(date)"
      'after:deploy:deploy': echo "Deployment completed for ${self:service}! All resources are up."

# Terminal commands to run after setting up serverless.yml
npm install --save serverless-plugin-scripts
serverless hello
serverless greet --param myName # Note: arguments are passed positionally as $1, $2, etc.
serverless deploy

view raw JSON →