serverless-plugin-transpiler

2.0.0 verified Fri May 01 auth: no javascript

A Serverless Framework plugin (v1.x compatible) that transpiles lambda function files during the packaging step. Version 2.0.0 allows you to define a custom transpiler function—either sync or async—that receives file contents and path, and returns transpiled code or null to skip. It is maintained by medikoo and designed to integrate any transpiler (e.g., Babel, TypeScript) into the Serverless packaging flow. The plugin relies on the serverless peer dependency (^1.21) and is configured via serverless.yml with a custom transpiler path. Compared to other transpilation plugins, it provides a flexible, low-level interface where the user controls the transpilation logic entirely.

Common errors

error PluginError: Cannot find module 'path/to/transpile' ↓

cause The transpiler path in serverless.yml is incorrect or the file does not exist.

fix

Verify the path is relative to the service root and the file exists (e.g., custom.transpilerPath: lib/transpile.js).

error TypeError: transpiler is not a function ↓

cause The transpiler module exports something other than a function (e.g., an object or string).

fix

Ensure the transpiler file uses module.exports = function(content, filePath) { ... }.

error The plugin "serverless-plugin-transpiler" is not recognized as a valid plugin ↓

cause Plugin is not installed or not listed in serverless.yml plugins section correctly.

fix

Run 'npm install serverless-plugin-transpiler' and add 'serverless-plugin-transpiler' under plugins in serverless.yml.

Warnings

gotcha Transpiler must return exactly the transpiled content as a string; if null/undefined, original content is used. Returning an empty string will produce empty output. ↓

fix Ensure your transpiler returns the content correctly or returns null/undefined for no-op.

breaking Major version 2.0.0 may have changed internal APIs; usage patterns from v1 might break. ↓

fix Review the 2.0.0 changelog on GitHub before migrating.

gotcha The plugin only works with Serverless v1.x (peer dep ^1.21). It is not compatible with Serverless v2 or v3. ↓

fix Use with Serverless v1 only, or migrate to a Serverless v3-compatible transpilation plugin.

deprecated Serverless Framework v1 is in maintenance mode and no longer officially supported by Serverless Inc. ↓

fix Plan migration to Serverless v3 and use a different transpilation plugin.

gotcha The transpiler function is called synchronously or asynchronously; the plugin uses async/await internally. If your transpiler returns a value without promise but does async I/O internally, it may not wait. ↓

fix If using asynchronous operations inside the transpiler, return a Promise.

Install

npm install serverless-plugin-transpiler

yarn add serverless-plugin-transpiler

pnpm add serverless-plugin-transpiler

Imports

plugin
```
plugins:
  - serverless-plugin-transpiler
```
Registered as a Serverless plugin, not imported in code. Defined in serverless.yml under plugins.
transpiler function
wrong
```
using ES module export in a CJS context
```
correct
```
module.exports = function(content, filePath) {
  // transpile logic
  return transpiledContent;
}
```
Transpiler module must be a CommonJS module exporting a function. The function can be sync or async, and should return null/undefined for files not to transpile.
custom.transpilerPath
wrong
```
specifying an absolute path outside the service directory
```
correct
```
custom:
  transpilerPath: lib/transpile.js
```
Path is relative to the service root. The plugin loads the transpiler module at runtime.

Quickstart

Shows minimal setup: a transpiler module that replaces environment variables, then the serverless.yml configuration to activate the plugin and reference the transpiler path.

// transpile.js - custom transpiler module
module.exports = function(content, filePath) {
  if (!filePath.endsWith('.js')) return null; // skip non-JS files
  return content.replace(/process\.env\.MY_VAR/g, '"static_value"'); // example
}

// serverless.yml
service: my-service
provider:
  name: aws
  runtime: nodejs18.x
plugins:
  - serverless-plugin-transpiler
custom:
  transpilerPath: path/to/transpile.js
functions:
  hello:
    handler: handler.hello