serverless-plugin-composed-vars

    1.0.3 • Public • Published

    serverless-plugin-composed-vars

    This plugin is Serverless variables reimagined, making them composable and easier to manage. It automatically scans for variables.yml and environment.yml files in your service directory to assign custom and environment variables in your service. In addition, it easily allows for stage specific overrides by loading variables.stage.yml and environment.stage.yml where stage is your deployment stage, like beta or prod.

    Serverless License NPM Total Downloads NPM Version Build Status Coverage

    Installation

    yarn add -D serverless-plugin-composed-vars

    Add serverless-plugin-composed-vars as the first plugin in your serverless.yml file:

    plugins:
      - serverless-plugin-composed-vars
      - other-serverless-plugin

    Usage

    Custom Variables

    Create a variables.yml file for default variable definitions:

    # variables.yml 
    myServiceName: Always My Service
    myEndpoint: beta.endpoint.com
     
    webpack:
      webpackConfig: 'beta-webpack.config.js'
      includeModules: true
      packager: yarn

    Create a stage specific variable file:

    # variables.prod.yml 
    myEndpoint: prod.endpoint.com
     
    webpack:
      webpackConfig: 'webpack.config.js'
      includeModules: false

    prod stage environments will result in:

    myServiceName: Always My Service
    myEndpoint: prod.endpoint.com
     
    webpack:
      webpackConfig: 'webpack.config.js'
      includeModules: false
      packager: yarn

    Environment Variables

    Create an environment.yml file for default definitions:

    # environment.yml 
    MY_ENDPOINT: ${self:custom.myEndpoint}
    STAGE: beta

    Create a stage specific environment file:

    # environment.prod.yml 
    STAGE: prod

    prod stage environments will result in:

    MY_ENDPOINT:: ${self:custom.myEndpoint}
    STAGE: prod

    Supported File Extensions

    • yml
    • yaml
    • js
    • json

    Advanced Usage

    Service File Definitions

    You can additionally define custom variables and environment variables in your service file. Note that these have the least priority and will be overridden by variables.yml and environment.yml.

    # serverless.yml 
    custom:
      googlesWebsite: www.google.com
      myEndpoint: dev.endpoint.com
     
    provider:
      environment:
        THE_ANSWER_IS: 42
        STAGE: dev

    Using the examples above, prod stage environments will result in:

    # Custom Variables 
    googlesWebsite: www.google.com
    myServiceName: Always My Service
    myEndpoint: prod.endpoint.com
     
    webpack:
      webpackConfig: 'webpack.config.js'
      includeModules: false
      packager: yarn
    # Environment Variables 
    THE_ANSWER_IS: 42
    MY_ENDPOINT:: ${self:custom.myEndpoint}
    STAGE: prod

    Alternate File Location

    If you'd like to specify a different directory or variable file name, just add a file reference for custom or environment:

    # serverless.yml 
    custom: ${file(./different/path/custom.yml)}
     
    provider:
      environment: ${file(./different/path/env.yml)}

    In this example, variables will be overridden with stage specific definitions defined in the following files:

    Custom: ./different/path/custom.stage.yml

    Environment: ./different/path/env.stage.yml

    Troubleshooting

    You can troubleshoot your variable setup by running the composed-vars merged and composed-vars computed commands. For example, npx serverless composed-vars merged will output the merged variables before any of the reference properties are computed. Whereas npx serverless composed-vars computed will output the fully computed values.

    Limitations

    serverless-plugin-composed-vars will only override custom variables and environment variables defined in main service file: serverless.yml. It does not perform an expansive search to override outside of the custom and environment definitions. Below are some examples that won't be overridden. However, with the structure of serverless-plugin-composed-vars, all of them can easily be handled by moving the definitions to the variables.yml file.

    Examples

    Functions and Resources

    # serverless.yml 
    plugins:
      - serverless-plugin-composed-vars
     
    provider:
      stackName: ${file(./another-var-file.yml):stackName}
     
    functions:
      hello:
        handler: handler.hello
        events: ${file(./hello-events.yml)}
      hi:
        handler: handler.hi
        events:
          schedule: ${file(./schedule-vars.yml):globalSchedule}
     
    resources:
      Resources:
        itemsTable: ${file(./items-table-vars.yml)}
        usersTable:
          tableName: ${file(./table-vars.yml):usersTable}

    Deep File References

    # variables.yml 
     
    tableNames: ${file(./table-names.yml)}
    # This will not be converted to table-names.stage.yml 

    Recursive/Nested Variable File Names:

    # serverless.yml 
     
    custom: ${file(./${self:service.name}.json)}

    Avoiding Limitations

    Move all of these references to the variables.yml and take advantage of stage overrides.

    # serverless.yml 
     
    plugins:
      - serverless-plugin-composed-vars
     
    provider:
      stackName: ${self:custom.stackName}
     
    functions:
      hello:
        handler: handler.hello
        events: ${self:custom.helloEvents}
      hi:
        handler: handler.hi
        events:
          schedule: ${self:custom.globalSchedule}
     
    resources:
      Resources:
        itemsTable: ${self:custom.itemsTable}
        usersTable:
          tableName: ${self:custom.tableNames.usersTable}
    # variables.yml 
     
    stackName: My Stack
     
    helloEvents:
      - http
      - schedule
     
    schedule:
      globalSchedule: 1 hour
     
    itemsTable: ${file(./items-table-vars.yml)}
     
    tableNames: ${file(./table-names.yml)}
    # variables.prod.yml 
     
    stackName: My Production Stack
     
    schedule:
      globalSchedule: 5 minutes
     
    itemsTable: ${file(./items-table-vars.prod.yml)}
     
    tableNames: ${file(./table-names.prod.yml)}

    Install

    npm i serverless-plugin-composed-vars

    DownloadsWeekly Downloads

    979

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    16.6 kB

    Total Files

    7

    Last publish

    Collaborators

    • chris.feist