f2e-server esbuild middleware

0.11.3 verified Fri May 01 auth: no javascript

f2e-middle-esbuild is a plugin-middleware for the f2e-server framework that integrates esbuild for fast JavaScript/TypeScript bundling and transpilation. Version 0.11.3 is the latest stable release. It allows configuring esbuild build options via an `.esbuildrc.js` file, supports external module splitting for faster dev builds, and provides a bundle size analyzer endpoint. Compared to standalone esbuild usage, it seamlessly integrates with f2e-server's middleware pipeline, lifecycle events, and file watching. The package ships TypeScript type definitions.

Common errors

error Error: Cannot find module 'f2e-server' ↓

cause f2e-middle-esbuild requires f2e-server as a peer dependency. It is not installed automatically.

fix

Run npm install f2e-server --save-dev (or save) to install the peer dependency.

error Error: ENOENT: no such file or directory, open '.esbuildrc.js' ↓

cause The middleware expects an .esbuildrc.js file in the project root, but it doesn't exist.

fix

Copy the default config from node_modules: cp ./node_modules/f2e-middle-esbuild/.esbuildrc.js ./ or create your own.

error TypeError: f2eMiddleware is not a function ↓

cause When using require('f2e-middle-esbuild') in CJS, the default export is the middleware function, but using .default may result in undefined.

fix

Use const esbuildMiddleware = require('f2e-middle-esbuild'); without .default.

Warnings

gotcha The .esbuildrc.js file must be copied from node_modules initially: `cp ./node_modules/f2e-middle-esbuild/.esbuildrc.js ./`. Otherwise the middleware will not find the default config. ↓

fix Run the copy command as documented, or create your own config file with the correct structure.

deprecated The option `ignore_external` is a custom parameter (not esbuild's). Its behavior may change in future versions. ↓

fix Avoid relying on custom options unless necessary; check changelog for updates.

gotcha Bundle size analyzer is accessed via /static/index.js.html (or based on entry name). This endpoint is only available in development mode and may not exist if the middleware configuration differs. ↓

fix Ensure the middleware is configured properly and the entry point name matches.

breaking Version 0.10.0 changed the configuration format from a single object to an array of BuildOptions (multiple configurations). Old single-object configs will break. ↓

fix Wrap your config in an array even if you have only one configuration.

gotcha The external_splits feature requires `ignore_external` to be false and `external` array to be non-empty. If either condition isn't met, external_splits is silently ignored. ↓

fix Set `ignore_external: false` and provide at least one entry in `external`.

Install

npm install f2e-middle-esbuild

yarn add f2e-middle-esbuild

pnpm add f2e-middle-esbuild

Imports

BuildOptions
wrong
```
const { BuildOptions } = require('f2e-middle-esbuild')
```
correct
```
import type { BuildOptions } from 'f2e-middle-esbuild'
```
BuildOptions is a TypeScript type export. Use type import to avoid runtime issues. The package is ESM and CJS compatible but types are only for TS.
default
wrong
```
const esbuildMiddleware = require('f2e-middle-esbuild').default
```
correct
```
import esbuildMiddleware from 'f2e-middle-esbuild'
```
Default export is the middleware factory function. In CJS, require returns the default directly; .default is not needed.

EsbuildMiddlewareOptions

wrong

const { EsbuildMiddlewareOptions } = require('f2e-middle-esbuild')

correct

import type { EsbuildMiddlewareOptions } from 'f2e-middle-esbuild'

EsbuildMiddlewareOptions is a TypeScript type for the middleware config object.

Quickstart

Shows minimum configuration for TypeScript bundling with f2e-middle-esbuild in a f2e-server project.

// .f2econfig.js
module.exports = {
  middleware: [
    {
      middleware: 'esbuild',
      watches: [/\.[jet]?sx?$/]
    }
  ]
};

// .esbuildrc.js (created by copy from node_modules)
/** @type { import('f2e-middle-esbuild').BuildOptions[] } */
let config = [
  {
    entryPoints: { index: 'src/index.tsx' },
    bundle: true,
    format: 'iife',
    loader: { '.tsx': 'tsx', '.ts': 'ts' },
    sourcemap: true,
    target: 'chrome70'
  }
];
module.exports = config;

// index.html
<script src="src/index.tsx"></script>