{"id":10809,"library":"esbuild-server","title":"esbuild-server","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/oblador/esbuild-server","tags":["javascript","esbuild","dev-server","development","typescript"],"install":[{"cmd":"npm install esbuild-server","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for bundling and serving capabilities. Must be installed separately.","package":"esbuild","optional":false}],"imports":[{"note":"The `createServer` function is a named export. While CommonJS `require` syntax uses `require('esbuild-server').createServer`, ESM environments should use a named import.","wrong":"import esbuildServer from 'esbuild-server';\nesbuildServer.createServer();","symbol":"createServer","correct":"import { createServer } from 'esbuild-server';"},{"note":"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.","wrong":"const createServer = require('esbuild-server');\ncreateServer.createServer();","symbol":"createServer (CommonJS)","correct":"const { createServer } = require('esbuild-server');"},{"note":"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.","wrong":"createServer(esbuildOptions, serverOptions).listen();","symbol":"Server instance","correct":"const server = createServer(esbuildOptions, serverOptions);\nserver.start();"}],"quickstart":{"code":"import { createServer } from 'esbuild-server';\nimport path from 'path';\n\nconst rootDir = process.cwd();\n\ncreateServer(\n  {\n    bundle: true,\n    entryPoints: [path.join(rootDir, 'src/app.ts')],\n    outdir: path.join(rootDir, 'dist'),\n    // Example: process.env.NODE_ENV !== 'production' ? 'development' : 'production'\n    define: { 'process.env.NODE_ENV': JSON.stringify('development') }\n  },\n  {\n    static: path.join(rootDir, 'public'), // Assumes 'public' directory with 'index.html'\n    port: 8080,\n    historyApiFallback: true, // Useful for SPAs\n    injectLiveReload: true,\n    open: true, // Opens browser automatically\n    proxy: {\n      '/api': 'http://localhost:3001' // Example API proxy\n    },\n    // https: {\n    //   key: fs.readFileSync('server.key'),\n    //   cert: fs.readFileSync('server.crt'),\n    // }\n  }\n).start();\n\nconsole.log('esbuild-server started on http://localhost:8080');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Install esbuild as a development dependency: `npm install --save-dev esbuild` or `yarn add -D esbuild`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"To prevent the browser from opening, set `open: false` in your `serverOptions`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install esbuild --save-dev` or `yarn add esbuild --dev`.","cause":"The `esbuild` package, a peer dependency, has not been installed.","error":"Error: Cannot find module 'esbuild'"},{"fix":"Change the `port` option in `serverOptions` to an available port, e.g., `{ port: 3000 }`.","cause":"Another process is already using the specified port (defaulting to 8080).","error":"Error: listen EADDRINUSE: address already in use :::8080"},{"fix":"For CommonJS, use `const { createServer } = require('esbuild-server');`. For ESM, use `import { createServer } from 'esbuild-server';`.","cause":"Attempting to call `require('esbuild-server')` directly as a function, or using an incorrect import style in an ESM context.","error":"TypeError: createServer is not a function"},{"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.","cause":"The HTTPS key or certificate file specified in `https` options could not be found or read.","error":"Error: ENODATA: no such file or directory, read 'server.key'"}],"ecosystem":"npm"}