esbuild-azure-functions

2.0.1 verified Fri May 01 auth: no javascript

A blazingly fast builder for Azure Functions powered by esbuild, version 2.0.1. It compiles TypeScript Azure Functions into optimized bundles, reducing cold starts and deployment times. Active development as of 2023, with a focus on speed and small bundle sizes compared to traditional Azure Functions tooling. Supports watch mode and provides plugins for __dirname and require shimming. Requires esbuild v0.17.5+ as a peer dependency.

Common errors

error Error: You need to provide at least one entry point ↓

cause No entryPoints specified in the build options object.

fix

Add an 'entryPoints' array to the build options, e.g., entryPoints: ['functions/**/*.ts'].

error TypeError: esbuild_azure_functions_1.build is not a function ↓

cause Using CommonJS require() on an ESM-only module.

fix

Switch to 'import { build } from 'esbuild-azure-functions'' and ensure your project uses ESM.

error Could not resolve '@azure/functions' ↓

cause The Azure Functions npm package is not installed or is not marked as external.

fix

Add '@azure/functions' to the 'external' list in esbuild options, or install it and bundle it.

error Invalid option 'watch': expected a boolean ↓

cause watch parameter was set to a non-boolean value like a string or object.

fix

Set watch: true or watch: false explicitly.

Warnings

breaking Version 2.0.0 updated esbuild peer dependency to v0.17.5, which may break custom esbuild plugins or configurations. ↓

fix Ensure your project's esbuild version is >=0.17.5 and update any custom plugins accordingly.

breaking In v2.0.0, the package switched to ESM-only, breaking CommonJS require() calls. ↓

fix Use 'import' syntax or set 'type':'module' in package.json.

gotcha The 'watch' option expects a boolean; passing an object or string may silently fail or be ignored. ↓

fix Set watch: true to enable watch mode. Custom watchers are not supported.

gotcha The library does not automatically include Azure Functions runtime dependencies; you must bundle them explicitly or rely on the Azure Functions host. ↓

fix Define external dependencies in esbuild options (e.g., external: ['@azure/functions']) to exclude from bundle.

deprecated Version 1.x is no longer maintained and lacks ESM support. ↓

fix Upgrade to v2.0.0 or later.

Install

npm install esbuild-azure-functions

yarn add esbuild-azure-functions

pnpm add esbuild-azure-functions

Imports

build

wrong

const build = require('esbuild-azure-functions')

correct

import { build } from 'esbuild-azure-functions'

ESM-only since v2.0.0; CommonJS require will fail.

buildSync

wrong

import { buildSync } from 'esbuild'

correct

import { buildSync } from 'esbuild-azure-functions'

Synchronous build variant for simple scripts.

type BuildOptions

wrong

import { BuildOptions } from 'esbuild-azure-functions'

correct

import type { BuildOptions } from 'esbuild-azure-functions'

Use 'import type' to avoid runtime errors in TypeScript.

Version

import { version } from 'esbuild-azure-functions/package.json'

Library version is not re-exported from the main entry.

Quickstart

Shows basic build and watch mode for Azure Functions using esbuild-azure-functions.

import { build } from 'esbuild-azure-functions';

// Build all functions in the 'functions' directory
build({
  entryPoints: ['functions/**/*.ts'],
  outdir: 'dist/functions',
  platform: 'node',
  target: 'node14',
  bundle: true,
  minify: true,
  sourcemap: true,
}).catch((err) => {
  console.error('Build failed:', err);
  process.exit(1);
});

// For watch mode, pass watch: true
build({
  entryPoints: ['functions/**/*.ts'],
  outdir: 'dist/functions',
  watch: true,
}).catch((err) => {
  console.error('Build failed:', err);
  process.exit(1);
});