esbuild-server

0.3.0 · active · verified Sun Apr 19

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.

Common errors

```
Error: Cannot find module 'esbuild'
```
cause 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
```
cause 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
```
cause 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'
```
cause 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.

Warnings

breaking esbuild-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.
gotcha Using 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.
gotcha The `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`.
gotcha By 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`.

Install

npm install esbuild-server npm
yarn add esbuild-server yarn
pnpm add esbuild-server pnpm

Imports

createServer
wrong:
```
import esbuildServer from 'esbuild-server';
esbuildServer.createServer();
```
correct:
```
import { createServer } from 'esbuild-server';
```
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)
wrong:
```
const createServer = require('esbuild-server');
createServer.createServer();
```
correct:
```
const { createServer } = require('esbuild-server');
```
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
wrong:
```
createServer(esbuildOptions, serverOptions).listen();
```
correct:
```
const server = createServer(esbuildOptions, serverOptions);
server.start();
```
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.

Quickstart

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');

view raw JSON →