esbuild CloudFront Functions Plugin

1.1.2 verified Fri May 01 auth: no javascript

An esbuild plugin (v1.1.2, active development) that automatically configures bundling for AWS CloudFront Functions, supporting both v1 (ES5.1+) and v2 (ES2020+) runtimes. It sets the correct esbuild target, format (ES modules), and enables/disables features per runtime constraints. Requires Node >=18 and esbuild >=0.14.46. Differentiators: handles edge-case runtime polyfills and feature toggling that manual configs often miss, and outputs minimal ESM-compatible bundles.

Common errors

error Cannot find module 'esbuild-cf-functions-plugin' ↓

cause Package not installed or not added to devDependencies

fix

npm install -D esbuild-cf-functions-plugin

error The esbuild plugins must be an array of objects ↓

cause CloudFrontFunctionsPlugin() was called without parentheses or returned undefined

fix

Ensure you invoke the factory: plugins: [CloudFrontFunctionsPlugin()]

error Target environment is not a supported ECMAScript version ↓

cause Custom target set alongside plugin overrides

fix

Remove target from esbuild config; plugin sets correct value

Warnings

breaking Node <18 no longer supported since v1.0.0 ↓

fix Upgrade Node.js to >=18 or pin to v0.2.x

breaking esbuild peer dependency minimum raised to >=0.14.46 in v0.2.2 ↓

fix Update esbuild to >=0.14.46

gotcha Plugin overrides format and target options – custom values will be ignored ↓

fix Rely on plugin to set these correctly; do not specify format/target in esbuild config

gotcha Output format is always ESM (esmodules) – cannot output CommonJS ↓

fix Ensure CloudFront Functions runtime supports ES modules (v2) or adapt code accordingly

deprecated v1 runtime (default) may be phased out by AWS; new functions should use v2 ↓

fix Pass { runtimeVersion: 2 } to CloudFrontFunctionsPlugin for ES2020+ features

Install

npm install esbuild-cf-functions-plugin

yarn add esbuild-cf-functions-plugin

pnpm add esbuild-cf-functions-plugin

Imports

CloudFrontFunctionsPlugin

wrong

const CloudFrontFunctionsPlugin = require('esbuild-cf-functions-plugin')

correct

import { CloudFrontFunctionsPlugin } from 'esbuild-cf-functions-plugin'

The package exports a single named function. CommonJS require works in Node >=18 but defaults to ESM.

default

wrong

import CloudFrontFunctionsPlugin from 'esbuild-cf-functions-plugin'

correct

import { CloudFrontFunctionsPlugin } from 'esbuild-cf-functions-plugin'

There is no default export. Use named import.

CloudFrontFunctionsPluginOptions
```
type CloudFrontFunctionsPluginOptions = { runtimeVersion?: 1 | 2 }
```
TypeScript type available at the same path; not directly exported as value.

Quickstart

Build a CloudFront Function-compatible bundle from src/index.js using default v1 runtime.

import { build } from 'esbuild';
import { CloudFrontFunctionsPlugin } from 'esbuild-cf-functions-plugin';

build({
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  minify: true,
  plugins: [CloudFrontFunctionsPlugin()],
}).catch(() => process.exit(1));