Skip to content

Read this on the main serverless docs site

Extending the configuration schema

Plugin can extend the serverless.yml syntax with custom configuration:

service: app
provider:
  name: aws

# ...

my-plugin:
  my-plugin-config: foo

To do so, plugins must define schema validation (see below), and can retrieve configuration values via serverless.service:

class MyPlugin {
  constructor(serverless) {
    this.serverless = serverless;
    this.hooks = {
      'before:deploy': () => this.beforeDeploy(),
    };
  }

  beforeDeploy() {
    // `service` contains the (resolved) serverless.yml config
    const service = this.serverless.service;
    console.log('Provider name: ', service.provider.name);
    console.log('Functions: ', service.functions);
    console.log('Custom plugin config: ', service['my-plugin']['my-plugin-config']);
  }
}

module.exports = MyPlugin;

Note: configuration values are only resolved after plugins are initialized. Do not try to read configuration in the plugin constructor, as variables aren't resolved yet. Read configuration in lifecycle events only.

Validating the configuration

Any additional configuration defined by plugins in serverless.yml must come with validation rules.

Serverless Framework uses JSON schema validation backed by the AJV library. You can extend the base schema in plugins via:

  • defineTopLevelProperty
  • defineCustomProperties
  • defineFunctionEvent
  • defineFunctionEventProperties
  • defineFunctionProperties
  • defineProvider

Use the following map to know which helper suits your needs:

custom:
  my-plugin:
    customProperty: foobar # <-- use defineCustomProperties

my-plugin: # <-- use defineTopLevelProperty
  customProperty: foobar

provider:
  name: new-provider # <-- use defineProvider
  my-plugin:
    customProperty: foobar

functions:
  someFunc:
    handler: handler.main
    customProperty: foobar # <-- use defineFunctionProperties
    events:
      - yourPluginEvent: # <-- use defineFunctionEvent
          customProperty: foobar
      - http:
          customProperty: foobar # <-- use defineFunctionEventProperties

We'll walk though those helpers. You may also want to check out examples from the Serverless Framework codebase.

Top-level properties via defineTopLevelProperty

If your plugin requires additional top-level properties (like provider, custom, service...), you can use the defineTopLevelProperty helper to add their definition. For example:

# serverless.yml
service: my-service

myPlugin:
  someProperty: foobar

Add validation for the myPlugin: section:

class MyPlugin {
  constructor(serverless) {
    // For reference on JSON schema, see https://github.com/ajv-validator/ajv
    serverless.configSchemaHandler.defineTopLevelProperty('myPlugin', {
      type: 'object',
      properties: {
        someProperty: { type: 'string' },
      },
      required: ['someProperty'],
    });
  }
}

This way, if the user sets someProperty by mistake to false, the Framework would display an error:

Configuration error: yourPlugin.someProperty should be string

Properties in custom via defineCustomProperties

If your plugin depends on properties defined in the custom: section, you can use the defineCustomProperties helper. For example:

# serverless.yml

custom:
  myCustomProperty: foobar

Add validation for the myCustomProperty property:

class MyPlugin {
  constructor(serverless) {
    // For reference on JSON schema, see https://github.com/ajv-validator/ajv
    serverless.configSchemaHandler.defineCustomProperties({
      type: 'object',
      properties: {
        myCustomProperty: { type: 'string' },
      },
      required: ['myCustomProperty'],
    });
  }
}

This way, if the user sets myCustomProperty by mistake to false, the Framework would display an error:

Configuration error: custom.myCustomProperty should be string

Function properties via defineFunctionProperties

If your plugin adds new properties to functions, you can use the defineFunctionProperties helper. For example:

# serverless.yml

functions:
  foo:
    handler: handler.main
    someCustomProperty: my-property-value

Add validation for the someCustomProperty property:

class MyPlugin {
  constructor(serverless) {
    // For reference on JSON schema, see https://github.com/ajv-validator/ajv
    serverless.configSchemaHandler.defineFunctionProperties('providerName', {
      properties: {
        someCustomProperty: { type: 'string' },
        anotherProperty: { type: 'number' },
      },
      required: ['someCustomProperty'],
    });
  }
}

This way, if the user sets anotherProperty by mistake to hello, the Framework would display an error:

Configuration error at 'functions.foo.anotherProperty': should be number

Function events via defineFunctionEvent

If your plugin adds support to a new function event, you can use the defineFunctionEvent helper. For example:

# serverless.yml

functions:
  someFunc:
    handler: handler.main
    events:
      - myPluginEvent:
          someProp: hello
          anotherProp: 1

Add validation for the myPluginEvent event:

class MyPlugin {
  constructor(serverless) {
    // For reference on JSON schema, see https://github.com/ajv-validator/ajv
    serverless.configSchemaHandler.defineFunctionEvent('providerName', 'myPluginEvent', {
      type: 'object',
      properties: {
        someProp: { type: 'string' },
        anotherProp: { type: 'number' },
      },
      required: ['someProp'],
      additionalProperties: false,
    });
  }
}

This way, if the user sets anotherProp by mistake to some-string, the Framework would display an error:

Configuration error: functions.someFunc.events[0].myPluginEvent.anotherProp should be number

Function event properties via defineFunctionEventProperties

If your plugin adds new properties to a function event, you can use the defineFunctionEventProperties helper. For example:

# serverless.yml

functions:
  foo:
    handler: handler.main
    events:
      - http:
          path: '/quote'
          method: GET
          documentation: Get a quote

In the example above, the plugin adds a new documentation property on http events for aws. To validate that properties:

class MyPlugin {
  constructor(serverless) {
    // For reference on JSON schema, see https://github.com/ajv-validator/ajv
    serverless.configSchemaHandler.defineFunctionEventProperties('aws', 'http', {
      properties: {
        documentation: { type: 'string' },
      },
      required: ['documentation'],
    });
  }
}

This way, if the user sets documentation by mistake to false, the Framework would display an error:

Configuration error: functions.foo.events[0].http.documentation should be a string

New provider via defineProvider

If your plugin provides support for a new provider, register it via defineProvider:

class MyPlugin {
  constructor(serverless) {
    // For reference on JSON schema, see https://github.com/ajv-validator/ajv
    serverless.configSchemaHandler.defineProvider('newProvider', {
      // Eventual reusable schema definitions (will be put to top level "definitions" object)
      definitions: {
        // ...
      },

      // Top level "provider" properties
      provider: {
        properties: {
          stage: { type: 'string' },
          remoteFunctionData: { type: 'null' },
        },
      },

      // Function level properties
      function: {
        properties: { handler: { type: 'string' } },
      },

      // Function events definitions (can be defined here or via `defineFunctionEvent` helper)
      functionEvents: {
        someEvent: {
          name: 'someEvent',
          schema: {
            type: 'object',
            properties: {
              someRequiredStringProp: { type: 'string' },
              someNumberProp: { type: 'number' },
            },
            required: ['someRequiredStringProp'],
            additionalProperties: false,
          },
        },
      },

      // Definition for eventual top level "resources" section
      resources: {
        type: 'object',
        properties: {
          // ...
        },
      },

      // Definition for eventual top level "layers" section
      layers: {
        type: 'object',
        additionalProperties: {
          type: 'object',
          properties: {
            // ...
          },
        },
      },
    });
  }
}