{"id":26384,"library":"serverless-plugin-transpiler","title":"serverless-plugin-transpiler","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/medikoo/serverless-plugin-transpiler","tags":["javascript","serverless","plugin","lamdba","aws","transpile"],"install":[{"cmd":"npm install serverless-plugin-transpiler","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-plugin-transpiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-plugin-transpiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency; plugin hooks into Serverless v1 framework lifecycle.","package":"serverless","optional":false}],"imports":[{"note":"Registered as a Serverless plugin, not imported in code. Defined in serverless.yml under plugins.","symbol":"plugin","correct":"plugins:\n  - serverless-plugin-transpiler"},{"note":"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.","wrong":"using ES module export in a CJS context","symbol":"transpiler function","correct":"module.exports = function(content, filePath) {\n  // transpile logic\n  return transpiledContent;\n}"},{"note":"Path is relative to the service root. The plugin loads the transpiler module at runtime.","wrong":"specifying an absolute path outside the service directory","symbol":"custom.transpilerPath","correct":"custom:\n  transpilerPath: lib/transpile.js"}],"quickstart":{"code":"// transpile.js - custom transpiler module\nmodule.exports = function(content, filePath) {\n  if (!filePath.endsWith('.js')) return null; // skip non-JS files\n  return content.replace(/process\\.env\\.MY_VAR/g, '\"static_value\"'); // example\n}\n\n// serverless.yml\nservice: my-service\nprovider:\n  name: aws\n  runtime: nodejs18.x\nplugins:\n  - serverless-plugin-transpiler\ncustom:\n  transpilerPath: path/to/transpile.js\nfunctions:\n  hello:\n    handler: handler.hello\n","lang":"javascript","description":"Shows minimal setup: a transpiler module that replaces environment variables, then the serverless.yml configuration to activate the plugin and reference the transpiler path."},"warnings":[{"fix":"Ensure your transpiler returns the content correctly or returns null/undefined for no-op.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the 2.0.0 changelog on GitHub before migrating.","message":"Major version 2.0.0 may have changed internal APIs; usage patterns from v1 might break.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use with Serverless v1 only, or migrate to a Serverless v3-compatible transpilation plugin.","message":"The plugin only works with Serverless v1.x (peer dep ^1.21). It is not compatible with Serverless v2 or v3.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Plan migration to Serverless v3 and use a different transpilation plugin.","message":"Serverless Framework v1 is in maintenance mode and no longer officially supported by Serverless Inc.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"If using asynchronous operations inside the transpiler, return a Promise.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Verify the path is relative to the service root and the file exists (e.g., custom.transpilerPath: lib/transpile.js).","cause":"The transpiler path in serverless.yml is incorrect or the file does not exist.","error":"PluginError: Cannot find module 'path/to/transpile'"},{"fix":"Ensure the transpiler file uses module.exports = function(content, filePath) { ... }.","cause":"The transpiler module exports something other than a function (e.g., an object or string).","error":"TypeError: transpiler is not a function"},{"fix":"Run 'npm install serverless-plugin-transpiler' and add 'serverless-plugin-transpiler' under plugins in serverless.yml.","cause":"Plugin is not installed or not listed in serverless.yml plugins section correctly.","error":"The plugin \"serverless-plugin-transpiler\" is not recognized as a valid plugin"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}