esbuild-server

⚡️ Fast, lightweight and powerful development server for esbuild ⚡️

• Zero dependencies besides esbuild
• API proxy support
• Live reload
• SPA support through History API fallback
• Fully typed with TypeScript

Installation

npm install --save-dev esbuild esbuild-server

Usage

Create a new file for your dev server:

// dev-server.js
require('esbuild-server')
  .createServer(
    {
      bundle: true,
      entryPoints: ['src/app.js'],
    },
    {
      static: 'public',
    }
  )
  .start();

Assuming you have an index.html file in the public folder you can now run the server with node dev-server.js.

See example folder for examples.

API

createServer(esbuildOptions, serverOptions)

esbuildOptions

Options passed to esbuild Build API. If not specified watch defaults to true to enable continous build and live reload, and similarly if no type of output option is specified outdir is set to a temporary directory.

serverOptions

Option	Description	Default
static	Path to your static assets folder, should contain an index.html file.	None
port	Port number to listen for requests on.	8080
historyApiFallback	For Single Page Apps using the HTML5 History API, the index.html page is served instead of 404 responses.	false
injectLiveReload	Inject snippet to automatically reload the page when file changes are detected.	true
open	Open the browser after server had been started. Set to a string to open a particular path.	false
proxy	Proxy certain paths to a separate API backend when you want to serve API requests on the same domain. Pass a function for dynamic rewrites.	{}
onProxyRewrite	Callback function when a proxy rewrite happens, useful for logging or altering the response.	None
http	http options.	None
https	https options.	None

Proxying

Static

{
  proxy: {
    '/api': 'http://localhost:3000'
  }
}

A request to /api/users will now proxy the request to http://localhost:3000/api/users. If you want to rewrite the base use dynamic approach instead:

Dynamic

{
  proxy: (path) => {
    if (path.startsWith('/api')) {
      return path.replace(/^\/api/, 'http://localhost:3000');
    }
  };
}

A request to /api/users will now proxy the request to http://localhost:3000/users.

Modifying the response

{
  onProxyRewrite: (proxyRes, localUrl, proxyUrl) => {
    console.log(`Proxying ${localUrl} to ${proxyUrl}`);
    proxyRes.headers['x-my-custom-header'] = 'yep';
    return proxyRes;
  };
}

Https

{
    https: {
        key: fs.readFileSync('server.key'),
        cert: fs.readFileSync('server.crt'),
    }
}

Live reload

If you want more control over where the live reload script is injected you can place it manually with:

<script src="/esbuild-livereload.js" async></script>

License

MIT © Joel Arvidsson 2022 – present