Skip to content

esbuild define constants not respected when using serverless offline start #1856

@ue-noma

Description

@ue-noma

Bug Report

Current Behavior

When using serverless-offline with serverless framework v4 and esbuild to define constants using the define option in serverless.yml, the constants are not correctly replaced when running the command serverless offline start, which results in a ReferenceError at runtime due to the undefined constant. However, the constants are properly replaced when using serverless offline.

Sample Code

  • file: serverless.yml
service: my-api
frameworkVersion: '4'

provider:
  name: aws
  runtime: nodejs22.x
  
functions:
  root:
    handler: handler.hello
    events:
      - http:
          path: /
          method: get

plugins:
  - serverless-offline

build:
  esbuild:
    bundle: true
    minify: true
    sourcemap: true
    exclude: ['aws-sdk']
    target: node22
    platform: node
    define:
      SERVICE_NAME: '"my-api4-${sls:stage}"'
  • file: handler.ts
import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';

declare const SERVICE_NAME: string;

export const hello = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  return {
    statusCode: 200,
    body: JSON.stringify(
      {
        message: 'Hello from root path!',
        serviceName: SERVICE_NAME,
      }
    )
  };
};

Expected behavior/code

When running serverless offline start, the constant SERVICE_NAME should be replaced correctly, and the handler should return a response like the following:

{"message":"Hello from root path!","serviceName":"my-api4-dev"}

Environment

  • serverless version: 4.14.3
  • serverless-offline version: 14.4.0
  • esbuild version: 0.25.3
  • node.js version: 22.15.0
  • OS: macOS 15.3

Possible Solution

N/A

Additional context/Screenshots

When invoking the API after running serverless offline start, the constant SERVICE_NAME is not replaced, and the following error occurs:

✖ Unhandled exception in handler 'root'.
✖ ReferenceError: SERVICE_NAME is not defined
    at hello (/sls/ts-sls/sls-2/handler.ts:13:22)
    at InProcessRunner.run (file:///sls/ts-sls/sls-2/node_modules/serverless-offline/src/lambda/handler-runner/in-process-runner/InProcessRunner.js:87:20)
    at async MessagePort.<anonymous> (file:///sls/ts-sls/sls-2/node_modules/serverless-offline/src/lambda/handler-runner/worker-thread-runner/workerThreadHelper.js:24:14)
✖ SERVICE_NAME is not defined

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions