Registry / web-framework / esbuild-server

esbuild-server

library0.3.0jsnpmunverified

esbuild-server is a development server specifically designed to integrate with esbuild for rapid, lightweight asset bundling and serving. It features zero runtime dependencies beyond esbuild itself, providing live reload, API proxying with dynamic rewrite capabilities, SPA support via History API fallback, and static asset serving. The current stable version is `0.3.0`, with a release cadence that addresses bug fixes and introduces new features like HTTPS support. It differentiates itself by tightly coupling with esbuild's build process, offering a minimal setup, and being fully typed for TypeScript environments, making it an efficient choice for projects already leveraging esbuild.

web-framework devops

npm install esbuild-server

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-SERVER

esbuild-server

web-frameworkjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createServer

✓ import { createServer } from 'esbuild-server';

✗ import esbuildServer from 'esbuild-server'; esbuildServer.createServer();

The `createServer` function is a named export. While CommonJS `require` syntax uses `require('esbuild-server').createServer`, ESM environments should use a named import.

createServer (CommonJS)

✓ const { createServer } = require('esbuild-server');

✗ const createServer = require('esbuild-server'); createServer.createServer();

For CommonJS modules, `createServer` is available as a named property on the module export. Direct `require('esbuild-server')` returns an object, not the function itself.

Server instance

✓ const server = createServer(esbuildOptions, serverOptions); server.start();

✗ createServer(esbuildOptions, serverOptions).listen();

The `createServer` function returns a server instance with a `.start()` method. Do not use `.listen()` directly, as the internal server setup includes live reload and proxy configurations.

This quickstart demonstrates how to set up `esbuild-server` with TypeScript, bundling `src/app.ts` into a `dist` directory, serving static files from `public`, enabling live reload, history API fallback, and an example API proxy. It also shows how to define environment variables.

import { createServer } from 'esbuild-server'; import path from 'path'; const rootDir = process.cwd(); createServer( { bundle: true, entryPoints: [path.join(rootDir, 'src/app.ts')], outdir: path.join(rootDir, 'dist'), // Example: process.env.NODE_ENV !== 'production' ? 'development' : 'production' define: { 'process.env.NODE_ENV': JSON.stringify('development') } }, { static: path.join(rootDir, 'public'), // Assumes 'public' directory with 'index.html' port: 8080, historyApiFallback: true, // Useful for SPAs injectLiveReload: true, open: true, // Opens browser automatically proxy: { '/api': 'http://localhost:3001' // Example API proxy }, // https: { // key: fs.readFileSync('server.key'), // cert: fs.readFileSync('server.crt'), // } } ).start(); console.log('esbuild-server started on http://localhost:8080');

esbuild-server --version

Debug

Known issues

breakingesbuild-server versions prior to `0.2.0` are not compatible with esbuild `0.17.0` and newer due to API changes in esbuild. Attempting to use older esbuild-server with modern esbuild will likely result in build failures.

fix

Upgrade `esbuild-server` to version `0.2.0` or higher to ensure compatibility with `esbuild 0.17+`. Ensure your `esbuild` peer dependency matches the recommended version range.

affects: <0.2.0

gotchaUsing the `https` option requires providing valid SSL key and certificate files. Without correctly formatted and accessible files (e.g., using `fs.readFileSync`), the server will fail to start with HTTPS enabled.

fix

Ensure `server.key` and `server.crt` (or your chosen key/cert files) are present, correctly formatted, and readable by the Node.js process. They typically contain PEM-encoded data. Consult OpenSSL documentation for generating self-signed certificates for local development.

affects: >=0.3.0

gotchaThe `esbuild` package is a peer dependency of `esbuild-server` and must be installed explicitly. Failing to install `esbuild` will result in a 'Cannot find module' error when `esbuild-server` attempts to initialize.

fix

Install esbuild as a development dependency: `npm install --save-dev esbuild` or `yarn add -D esbuild`.

affects: >=0.1.0

gotchaBy default, `esbuild-server` attempts to open a browser window upon starting the server if `open: true` is set in `serverOptions`. This can be disruptive in CI/CD environments or headless setups.

fix

To prevent the browser from opening, set `open: false` in your `serverOptions`.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'esbuild'

The `esbuild` package, a peer dependency, has not been installed.

fix

Run `npm install esbuild --save-dev` or `yarn add esbuild --dev`.

Error: listen EADDRINUSE: address already in use :::8080

Another process is already using the specified port (defaulting to 8080).

fix

Change the `port` option in `serverOptions` to an available port, e.g., `{ port: 3000 }`.

TypeError: createServer is not a function

Attempting to call `require('esbuild-server')` directly as a function, or using an incorrect import style in an ESM context.

fix

For CommonJS, use `const { createServer } = require('esbuild-server');`. For ESM, use `import { createServer } from 'esbuild-server';`.

Error: ENODATA: no such file or directory, read 'server.key'

The HTTPS key or certificate file specified in `https` options could not be found or read.

fix

Verify that the paths to `key` and `cert` files are correct and that the Node.js process has read permissions for these files. Ensure the files actually exist at the specified location.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

esbuildrequiredRequired peer dependency for bundling and serving capabilities. Must be installed separately.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/oblador/esbuild-server ↗

packagehttps://www.npmjs.com/package/esbuild-server ↗