### Esbuild Plugin Setup Example

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Example of an esbuild plugin configuration file. It exports an array of plugins.

```javascript
let myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // plugin implementation
  },
};

// default export should be an array of plugins
module.exports = [myPlugin];
```

--------------------------------

### Esbuild Plugin Setup with Serverless Instance

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Example of an esbuild plugin configuration file that accepts the serverless instance. This allows access to serverless configuration within the plugin.

```javascript
module.exports = (serverless) => {
  const myPlugin = {
    name: 'my-plugin',
    setup(build) {
      // plugin implementation with `serverless` instance access
      console.log('sls custom options', serverless.service.custom);
    },
  };

  // an array of plugins must be returned
  return [myPlugin];
};
```

--------------------------------

### Esbuild Config File Example

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Example of an esbuild configuration file. It exports an object with esbuild options.

```javascript
// esbuild.config.js
module.exports = (serverless) => ({
  external: ['lodash'],
  plugins: [],
});
```

--------------------------------

### Install serverless-esbuild and esbuild

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Install the plugin and esbuild as development dependencies using npm, yarn, or pnpm.

```bash
npm install -D serverless-esbuild esbuild
```

```bash
yarn add -D serverless-esbuild esbuild
```

```bash
pnpm add -D serverless-esbuild esbuild
```

--------------------------------

### Install serverless-esbuild and esbuild

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Install the serverless-esbuild plugin and esbuild as development dependencies using yarn, npm, or pnpm.

```sh
yarn add --dev serverless-esbuild esbuild
# or
npm install -D serverless-esbuild esbuild
# or
pnpm install -D serverless-esbuild esbuild
```

--------------------------------

### Start Local Simulation with Hot-Reload

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Initiate a local development server that watches for file changes and triggers hot-reloading. The expected log output indicates esbuild compilation and the start of file watching.

```bash
# Start local simulation — esbuild watches for changes and triggers hot-reload
serverless offline start

# Expected log output:
# serverless-esbuild: Compiling to node18 bundle with esbuild...
# serverless-esbuild: Compiling completed.
# Watching files for changes...
```

--------------------------------

### Basic serverless-esbuild Configuration

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Configure the esbuild options within the custom.esbuild section of your serverless.yml file. This example enables bundling and disables minification.

```yaml
custom:
  esbuild:
    bundle: true
    minify: false
```

--------------------------------

### Configure Packager Options (Yarn)

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Configure Yarn for installing external modules. Set `noInstall: true` to skip the Yarn install step and `ignoreLockfile: false` to use `yarn --frozen-lockfile`.

```yaml
# Yarn-specific options
custom:
  esbuild:
    packager: yarn
    packagerOptions:
      noInstall: false          # set true to skip yarn install step
      ignoreLockfile: false     # use yarn --frozen-lockfile
      scripts:
        - 'yarn run postinstall-hook'
```

--------------------------------

### Full serverless.yml Configuration

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

This is a comprehensive example of a serverless.yml file demonstrating various configuration options for serverless-esbuild, including bundling, minification, sourcemaps, external dependencies, and watch patterns.

```yaml
service: complete-example

plugins:
  - serverless-esbuild
  - serverless-offline

provider:
  name: aws
  runtime: nodejs18.x

custom:
  esbuild:
    bundle: true
    minify: true
    sourcemap: true
    keepNames: true
    target: node18
    concurrency: 4
    zipConcurrency: 4
    external:
      - lodash
      - pg-native
    exclude:
      - aws-sdk
    nativeZip: false
    packager: yarn
    installExtraArgs:
      - '--legacy-peer-deps'
    packagerOptions:
      scripts:
        - 'echo "post-install hook"'
      ignoreLockfile: false
    keepOutputDirectory: false
    outputWorkFolder: '.esbuild'
    outputBuildFolder: '.build'
    outputFileExtension: '.js'
    skipBuild: false
    skipRebuild: false
    disposeContext: true
    watch:
      pattern: ['src/**/*.ts']
      ignore: ['.esbuild', 'node_modules', 'dist']
      chokidar:
        ignoreInitial: true

package:
  individually: true    # each function gets its own optimised zip

functions:
  api:
    handler: src/api/index.handler
    events:
      - http:
          path: /api
          method: any
  worker:
    handler: src/worker/index.handler
    disposeContext: false   # per-function override — keep context alive
```

--------------------------------

### Configure Esbuild Config File

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Define esbuild configuration in a separate file. This allows for more complex esbuild setups.

```yaml
custom:
  esbuild:
    config: './esbuild.config.js'
```

--------------------------------

### Local Invoke Payload Example

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Example JSON payload for local function invocation.

```json
// event.json
{
  "httpMethod": "GET",
  "path": "/hello",
  "queryStringParameters": { "name": "World" },
  "headers": {}
}
```

--------------------------------

### Configure Supported Runtimes for Scaleway

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Map Serverless runtime strings to esbuild target values for Scaleway. Example shows node20 mapping to node20.

```yaml
# Scaleway
provider:
  name: scaleway
  runtime: node20       # → target: node20
```

--------------------------------

### Configure Supported Runtimes for AWS

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Map Serverless runtime strings to esbuild target values for AWS. Example shows nodejs24.x mapping to node24.

```yaml
# AWS
provider:
  name: aws
  runtime: nodejs24.x   # → target: node24
  # nodejs22.x → node22 | nodejs20.x → node20 | nodejs18.x → node18
  # nodejs16.x → node16 | nodejs14.x → node14 | nodejs12.x → node12
```

--------------------------------

### Configure Packager Options (npm)

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Fine-tune npm's behavior during external module installation. Use `installExtraArgs` for npm v7+ peer dependency resolution and `packagerOptions.scripts` to run post-install scripts.

```yaml
custom:
  esbuild:
    packager: npm
    installExtraArgs:
      - '--legacy-peer-deps'    # npm v7+ peer dep resolution
    packagerOptions:
      ignoreLockfile: false     # use npm ci (lockfile-based install)
      scripts:
        - 'node scripts/post-install.js'
        - 'npx patch-package'
```

--------------------------------

### Minimal serverless.yml for TypeScript Lambda

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

A zero-config setup for a TypeScript Lambda function using serverless-esbuild. The esbuild target is automatically set based on the provider's runtime.

```yaml
service: minimal-example

plugins:
  - serverless-esbuild

provider:
  name: aws
  runtime: nodejs18.x   # esbuild target is auto-set to "node18"

functions:
  hello:
    handler: src/handler.handler
    events:
      - http:
          path: /hello
          method: get
```

--------------------------------

### Configure Supported Runtimes for Google Cloud Functions

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Map Serverless runtime strings to esbuild target values for Google Cloud Functions. Example shows nodejs22 mapping to node22.

```yaml
# Google Cloud Functions
provider:
  name: google
  runtime: nodejs22     # → target: node22
```

--------------------------------

### Configure Supported Runtimes for Azure Functions

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Map Serverless runtime strings to esbuild target values for Azure Functions. Example shows nodejs18 mapping to node18.

```yaml
# Azure Functions
provider:
  name: azure
  runtime: nodejs18     # → target: node18
```

--------------------------------

### Inspect esbuild Metafile with esbuild-visualizer

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

After packaging, inspect the generated metafile using esbuild-visualizer to analyze bundle composition.

```bash
# After running sls package, inspect the meta file:
cat .esbuild/.build/src/handler-meta.json | npx esbuild-visualizer --stdin
# or upload to https://esbuild.github.io/analyze/
```

--------------------------------

### Configure Serverless ESBuild, Dynamodb Local, and Offline Plugins

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Order of plugins is important. Ensure `serverless-esbuild` precedes `serverless-dynamodb-local` and `serverless-offline` for correct integration.

```yaml
plugins:
  - serverless-esbuild
  - serverless-dynamodb-local
  - serverless-offline
```

--------------------------------

### Configure Serverless ESBuild and Offline Plugins

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Order of plugins is important. Ensure `serverless-esbuild` precedes `serverless-offline` for correct integration.

```yaml
plugins: ...
  - serverless-esbuild
  ...
  - serverless-offline
  ...
```

--------------------------------

### Enable Metafile Output for Bundle Analysis

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Enable esbuild's metafile output to analyze bundle contents. Retain the build directory to inspect meta files.

```yaml
custom:
  esbuild:
    metafile: true
    keepOutputDirectory: true   # retain .esbuild folder to inspect meta files
```

--------------------------------

### Configure Watch Patterns for ESBuild

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Set up watch patterns to automatically recompile files. Use `ignore` to exclude specific directories or files from recompilation.

```yaml
custom:
  esbuild:
    watch:
      pattern: ['src/**/*.ts'] # match only typescript files in src directory
      ignore: ['temp/**/*']
```

--------------------------------

### Configure Package Patterns for Extra Files

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Use package patterns to include additional files like templates and assets into the deployment zip. Explicit exclusions can also be defined.

```yaml
package:
  patterns:
    - 'templates/**'
    - 'assets/logo.png'
    - '!secrets.env'          # explicit exclusion
  individually: false

functions:
  renderer:
    handler: src/renderer.handler
    package:
      patterns:
        - 'views/**/*.hbs'    # function-specific extra files
```

--------------------------------

### Add serverless-esbuild to serverless.yml

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Add the serverless-esbuild plugin to the plugins section of your serverless.yml file.

```yaml
plugins:
  - serverless-esbuild
```

--------------------------------

### Include External Dependencies with Packager Options

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Configure external dependencies, packager, package path, and packager options. Useful for managing dependencies and running custom scripts during packaging.

```yaml
custom:
  esbuild:
    external:
      - lodash
    packager: yarn
    packagePath: absolute/path/to/package.json
    packagerOptions:
      scripts:
        - echo 'Hello World!'
        - rm -rf node_modules
    installExtraArgs:
      - '--legacy-peer-deps'
```

--------------------------------

### Azure Functions Package Patterns for Configuration Files

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

When using with `serverless-azure-functions`, include `host.json` and `function.json` in package patterns as esbuild does not bundle them.

```yaml
plugins:
  - serverless-esbuild

provider:
  name: azure
  runtime: nodejs18

package:
  patterns:
    - 'host.json'
    - '**/function.json'

custom:
  esbuild:
    bundle: true
    minify: true

functions:
  httpTrigger:
    handler: src/httpTrigger.handler
    events:
      - http: true
```

--------------------------------

### Reuse Pre-built Artifacts with skipBuild

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Set `skipBuild: true` to reuse existing `.zip` artifacts, skipping compilation. Use `skipBuildExcludeFns` to ensure specific functions are always rebuilt.

```yaml
custom:
  esbuild:
    skipBuild: true
    skipBuildExcludeFns:
      - warmupPlugin   # this function is always freshly built

package:
  individually: true
  # place pre-built zips here for the plugin to pick up:
  # .serverless/myService.zip  (or <functionName>.zip when individually: true)
```

--------------------------------

### Per-Function esbuild Configuration

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Configure esbuild settings like bundling and minification individually for functions. External dependencies are included only if imported by the specific function.

```yaml
service: individual-example

plugins:
  - serverless-esbuild

package:
  individually: true

provider:
  name: aws
  runtime: nodejs20.x

custom:
  esbuild:
    bundle: true
    minify: true
    external:
      - lodash
      - pg

functions:
  queryUsers:
    handler: src/users/query.handler
    # Will only include lodash + pg deps that queryUsers actually imports
    events:
      - http:
          path: /users
          method: get

  sendEmail:
    handler: src/email/send.handler
    # Will only include lodash deps that sendEmail actually imports
    events:
      - http:
          path: /email
          method: post
```

--------------------------------

### Watch Configuration for serverless-offline

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Control which files trigger a rebuild when running `serverless offline`. Uses chokidar and accepts anymatch-compatible patterns for files to watch and ignore.

```yaml
plugins:
  - serverless-esbuild
  - serverless-offline

custom:
  esbuild:
    watch:
      pattern:
        - 'src/**/*.ts'
        - 'src/**/*.js'
        - 'config/**/*.json'
      ignore:
        - '.esbuild/**/*'
        - 'dist/**/*'
        - 'node_modules/**/*'
        - '.build/**/*'
      chokidar:
        ignoreInitial: true
        usePolling: false        # set true inside Docker containers
        interval: 300
```

--------------------------------

### Configure Esbuild Plugins File

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Specify a JavaScript file that exports esbuild plugins. This allows for custom esbuild transformations.

```yaml
custom:
  esbuild:
    plugins: plugins.js
```

--------------------------------

### External Configuration File for esbuild

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Use an external JS file for complex configurations or when referencing serverless runtime values. The file must export a function that accepts the Serverless instance and returns a configuration object.

```yaml
custom:
  esbuild:
    config: './esbuild.config.js'
```

```javascript
// esbuild.config.js
module.exports = (serverless) => {
  const stage = serverless.service.provider.stage;

  return {
    bundle: true,
    minify: stage === 'production',
    sourcemap: stage !== 'production',
    keepNames: true,
    packager: 'pnpm',
    external: ['lodash'],
    plugins: [
      {
        name: 'log-lodash',
        setup(build) {
          build.onResolve({ filter: /^lodash$/ }, (args) => {
            console.log('Resolved lodash from:', args.resolveDir);
          });
        },
      },
    ],
  };
};
```

--------------------------------

### Configure Mixed Runtimes with Serverless esbuild

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

The plugin automatically skips functions with non-Node.js runtimes (e.g., Python, Ruby) or container images. No explicit configuration is needed for these.

```yaml
provider:
  name: aws
  runtime: nodejs20.x

functions:
  nodeHandler:
    handler: src/index.handler        # compiled by serverless-esbuild

  pythonHandler:
    handler: scripts/process.handler
    runtime: python3.12               # automatically skipped

  imageFunction:
    image:
      uri: 123456.dkr.ecr.us-east-1.amazonaws.com/my-image:latest
                                       # automatically skipped (no handler)
```

--------------------------------

### Custom esbuild Plugins via File

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Provide custom esbuild plugins through a separate JS file. This file can export an array of plugin objects or a factory function that receives the Serverless instance.

```yaml
custom:
  esbuild:
    plugins: ./plugins.js
```

```javascript
// plugins.js — plain array export
const envPlugin = {
  name: 'inject-env',
  setup(build) {
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: 'env-ns',
    }));

    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: JSON.stringify(process.env),
      loader: 'json',
    }));
  },
};

module.exports = [envPlugin];
```

```javascript
// plugins.js — factory function export (access Serverless instance)
module.exports = (serverless) => {
  const definePlugin = {
    name: 'define-stage',
    setup(build) {
      build.initialOptions.define = {
        ...build.initialOptions.define,
        __STAGE__: JSON.stringify(serverless.service.provider.stage),
      };
    },
  };

  return [definePlugin];
};
```

--------------------------------

### Integrating esbuild-node-externals

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

When the `node-externals` plugin is detected, serverless-esbuild automatically uses your `package.json` to externalize production dependencies. An optional `allowList` can be used to specify dependencies that should still be bundled.

```yaml
custom:
  esbuild:
    plugins: ./plugins.js
    nodeExternals:
      allowList:
        - '@aws-sdk/client-s3'   # these will be bundled, not externalised
```

```javascript
// plugins.js
const { nodeExternalsPlugin } = require('esbuild-node-externals');

module.exports = [
  nodeExternalsPlugin({
    allowList: ['@aws-sdk/client-s3'],
  }),
];
```

--------------------------------

### Output File Extension for ESM Bundles

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Configure the output file extension to `.mjs` for native ESM bundles, suitable for Node.js 18+ Lambda runtimes. Note that `format: 'esm'` cannot be combined with `outputFileExtension: '.cjs'`.

```yaml
# Native ESM Lambda (Node 18+)
custom:
  esbuild:
    format: esm
    outputFileExtension: '.mjs'
    platform: node
    bundle: true
    # Note: format 'esm' cannot be combined with outputFileExtension '.cjs'
```

--------------------------------

### Output File Extension for CommonJS Bundles

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Set the output file extension to `.cjs` to produce explicit CommonJS bundles, which can be useful for compatibility layers or older Node.js runtimes.

```yaml
# Explicit CommonJS (e.g. for compatibility layers)
custom:
  esbuild:
    format: cjs
    outputFileExtension: '.cjs'
```

--------------------------------

### Mark Individual Packages as External

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Specify individual packages to be treated as external dependencies. This prevents them from being bundled.

```yaml
custom:
  esbuild:
    external:
      - 'my-package-name'
      - 'another-package-name'
```

--------------------------------

### Basic TypeScript Lambda Handler

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

A simple TypeScript handler function for an AWS Lambda.

```typescript
// src/handler.ts
export async function handler(event: AWSLambda.APIGatewayEvent) {
  return { statusCode: 200, body: JSON.stringify({ message: 'Hello!' }) };
}
```

--------------------------------

### Specify Custom Entrypoint for Function

Source: https://github.com/floydspace/serverless-esbuild/blob/master/README.md

Define a custom entrypoint for a function using the `esbuildEntrypoint` field. This is useful when the handler is not directly the entrypoint.

```typescript
export const myLambdaFunction = {
  handler: '/opt/nodejs/node_modules/my_custom_extension/handler.handler',
  esbuildEntrypoint: './handler.main',
};
```

--------------------------------

### Override esbuild Entrypoint Per Function

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Use `esbuildEntrypoint` to specify a different entry point for esbuild compilation than the function's handler path. This is useful when the deployed handler differs from the source file.

```typescript
// serverless.ts (TypeScript config)
import type { AWS } from '@serverless/typescript';

const config: AWS = {
  service: 'my-service',
  provider: { name: 'aws', runtime: 'nodejs20.x' },
  functions:
    myFunction: {
      handler: '/opt/nodejs/node_modules/my_extension/handler.handler',
      // @ts-ignore — esbuildEntrypoint is a serverless-esbuild extension
      esbuildEntrypoint: './src/handler.main',
    },
};

export = config;
```

```yaml
# serverless.yml equivalent
functions:
  myFunction:
    handler: /opt/nodejs/node_modules/my_extension/handler.handler
    esbuildEntrypoint: ./src/handler.main
```

--------------------------------

### Invoke Local Function Compilation and Execution

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Intercepts `sls invoke local` to compile functions before execution. Rewires the service path to the build directory for correct module resolution.

```bash
# Compile and invoke a function locally with a JSON payload
serverless invoke local --function myFunction --data '{"key":"value"}'

# With a payload file
serverless invoke local --function myFunction --path event.json
```

--------------------------------

### Skip esbuild Compilation Per Function

Source: https://context7.com/floydspace/serverless-esbuild/llms.txt

Use `skipEsbuild: true` to exclude a function from esbuild compilation, useful for functions with pre-built artifacts managed by other plugins.

```yaml
functions:
  warmup:
    handler: .warmup/index.handler
    skipEsbuild: true          # this function is managed by serverless-plugin-warmup
    package:
      artifact: .warmup/warmup.zip

  api:
    handler: src/api.handler   # compiled normally by serverless-esbuild
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.