{"id":14914,"library":"serverless-plugin-utils","title":"Serverless Plugin Utilities","description":"serverless-plugin-utils is a collection of essential utilities designed to augment the Serverless Framework's configuration capabilities. Currently stable at version 0.2.0, it provides a set of helper functions primarily consumed directly within `serverless.yml` files, enhancing the declarative power of serverless configurations. These utilities facilitate common operations such as string manipulation (lowercase, uppercase, capitalize, split, join), conditional logic (ternary, switch statements), and other dynamic value resolutions, which are frequently encountered when defining resources, environment variables, or other service properties. It allows developers to create more dynamic and adaptive Serverless configurations without resorting to external scripting or complex custom logic, streamlining tasks like enforcing S3 bucket naming conventions or dynamic domain construction. The package is typically installed as a development dependency and integrates seamlessly into the Serverless Framework's variable resolution system.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/icarus-sullivan/serverless-plugin-utils","tags":["javascript","serverless","plugin","utils","lower","ternary","split","join","upper"],"install":[{"cmd":"npm install serverless-plugin-utils","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-plugin-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-plugin-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for the Serverless Framework and requires it to function. It should be listed as a peer dependency.","package":"serverless","optional":false}],"imports":[{"note":"Utility functions are exposed via the Serverless Framework's variable system, not direct JavaScript module imports. This is the correct YAML syntax.","wrong":"import { lower } from 'serverless-plugin-utils'","symbol":"lower","correct":"${fn:lower('YourString')}"},{"note":"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.","wrong":"require('serverless-plugin-utils').join()","symbol":"join","correct":"${fn:join(',', ['item1', 'item2'])}"},{"note":"The primary interface for these utilities is through Serverless YAML variables. The plugin itself is loaded by the Serverless Framework at runtime.","wrong":"const ternary = require('serverless-plugin-utils').ternary;","symbol":"ternary","correct":"${fn:ternary(condition, 'trueValue', 'falseValue')}"}],"quickstart":{"code":"service: my-serverless-app\nframeworkVersion: '3'\n\nplugins:\n  - serverless-plugin-utils\n\nprovider:\n  name: aws\n  runtime: nodejs18.x\n  stage: ${opt:stage, 'dev'}\n  environment:\n    SERVICE_NAME_LOWER: ${fn:lower(self:service)}\n    DEPLOY_STAGE_CAPITALIZED: ${fn:capitalize(self:provider.stage)}\n    DYNAMIC_BUCKET_NAME: ${fn:join('-', [self:service, ${fn:lower(self:provider.stage)}, 'resources'])}\n    IS_PROD: ${fn:ternary(${self:provider.stage} == 'prod', true, false)}\n\nfunctions:\n  hello:\n    handler: handler.hello\n    events:\n      - http:\n          path: hello\n          method: get\n\n# handler.ts example (not directly importing utils, but using env vars)\n// export const hello = async (event: any) => {\n//   const serviceName = process.env.SERVICE_NAME_LOWER ?? '';\n//   const stage = process.env.DEPLOY_STAGE_CAPITALIZED ?? '';\n//   const isProd = process.env.IS_PROD === 'true';\n//   return {\n//     statusCode: 200,\n//     body: JSON.stringify({\n//       message: `Hello from ${serviceName} in ${stage} (Prod: ${isProd})!`,\n//       input: event,\n//     }),\n//   };\n// };","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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:`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `serverless-plugin-utils` is listed under the `plugins` section in your `serverless.yml`:\n```yaml\nplugins:\n  - serverless-plugin-utils\n```\nAlso, check the compatibility of the plugin with your Serverless Framework version.","cause":"The `serverless-plugin-utils` plugin has not been correctly registered in your `serverless.yml` or the Serverless Framework version is incompatible.","error":"Cannot resolve variable at 'provider.environment.MY_VAR': Variable 'fn:lower' not found."},{"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.","cause":"Incorrect YAML syntax when defining or calling a utility function within `serverless.yml`.","error":"YAMLException: bad indentation of a mapping entry"}],"ecosystem":"npm"}