Serverless Plugin Utilities

Common errors

• Cannot resolve variable at 'provider.environment.MY_VAR': Variable 'fn:lower' not found.

  cause The `serverless-plugin-utils` plugin has not been correctly registered in your `serverless.yml` or the Serverless Framework version is incompatible.
  fix Ensure `serverless-plugin-utils` is listed under the `plugins` section in your `serverless.yml`: ```yaml plugins: - serverless-plugin-utils ``` Also, check the compatibility of the plugin with your Serverless Framework version.

• YAMLException: bad indentation of a mapping entry

  cause Incorrect YAML syntax when defining or calling a utility function within `serverless.yml`.
  fix YAML is whitespace-sensitive. Carefully review the indentation and spacing of your `serverless.yml` file, especially around utility function calls and their arguments. Use a YAML linter if available.

Warnings

• gotcha This package is at a low version (0.2.0), which historically indicates it may be in early development. While it appears stable for its advertised functionality, anticipate potential breaking changes in minor or patch versions if the project becomes more actively developed, or if Serverless Framework itself introduces breaking changes that impact plugin compatibility.
  Fix: Always pin to an exact version (`~0.2.0` or `0.2.0`) and test thoroughly before upgrading. Review the plugin's GitHub repository for any recent activity or changelogs.
• gotcha The utilities provided by this plugin are primarily designed for use within `serverless.yml` via the Serverless Framework's variable system (e.g., `${fn:lower('...')}`). Attempting to `import` or `require` these utility functions directly into your JavaScript/TypeScript Lambda code will not work as expected, as they are not exposed as standard module exports for programmatic consumption.
  Fix: Use the documented Serverless variable syntax within your `serverless.yml` configuration. If you need similar logic in your Lambda code, implement it directly in JavaScript/TypeScript using standard library functions.
• gotcha This plugin registers its utilities under a specific variable namespace (often `fn:` or implicit). Ensure that your `serverless.yml` file correctly lists `serverless-plugin-utils` in the `plugins` section. Forgetting to register the plugin or using an incorrect variable prefix will lead to 'variable not found' errors.
  Fix: Verify that `plugins: - serverless-plugin-utils` is present in your `serverless.yml`. Refer to the plugin's documentation for the exact variable prefix if it deviates from the common `fn:`.

Install

• npm install serverless-plugin-utils npm
• yarn add serverless-plugin-utils yarn
• pnpm add serverless-plugin-utils pnpm

Imports

• lower
  wrong:

  import { lower } from 'serverless-plugin-utils'

  correct:

  ${fn:lower('YourString')}

  Utility functions are exposed via the Serverless Framework's variable system, not direct JavaScript module imports. This is the correct YAML syntax.
• join
  wrong:

  require('serverless-plugin-utils').join()

  correct:

  ${fn:join(',', ['item1', 'item2'])}

  Access utility functions directly in serverless.yml using the specified variable syntax. Direct programmatic JavaScript access to these specific utilities is not the intended use case for end-users.
• ternary
  wrong:

  const ternary = require('serverless-plugin-utils').ternary;

  correct:

  ${fn:ternary(condition, 'trueValue', 'falseValue')}

  The primary interface for these utilities is through Serverless YAML variables. The plugin itself is loaded by the Serverless Framework at runtime.

Quickstart

This quickstart demonstrates how to integrate `serverless-plugin-utils` into your `serverless.yml` and use its functions to dynamically set environment variables for a Lambda function. It showcases `lower`, `capitalize`, `join`, and `ternary` utilities.

service: my-serverless-app
frameworkVersion: '3'

plugins:
  - serverless-plugin-utils

provider:
  name: aws
  runtime: nodejs18.x
  stage: ${opt:stage, 'dev'}
  environment:
    SERVICE_NAME_LOWER: ${fn:lower(self:service)}
    DEPLOY_STAGE_CAPITALIZED: ${fn:capitalize(self:provider.stage)}
    DYNAMIC_BUCKET_NAME: ${fn:join('-', [self:service, ${fn:lower(self:provider.stage)}, 'resources'])}
    IS_PROD: ${fn:ternary(${self:provider.stage} == 'prod', true, false)}

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: hello
          method: get

# handler.ts example (not directly importing utils, but using env vars)
// export const hello = async (event: any) => {
//   const serviceName = process.env.SERVICE_NAME_LOWER ?? '';
//   const stage = process.env.DEPLOY_STAGE_CAPITALIZED ?? '';
//   const isProd = process.env.IS_PROD === 'true';
//   return {
//     statusCode: 200,
//     body: JSON.stringify({
//       message: `Hello from ${serviceName} in ${stage} (Prod: ${isProd})!`,
//       input: event,
//     }),
//   };
// };