ES Dev Server

2.1.0 · renamed · verified Tue Apr 21

ES Dev Server (version 2.1.0, though the project itself has seen its main development move to a new name) is a development server designed for modern web applications that leverage native ES modules directly in the browser, thereby eliminating the need for a separate bundling step during development. It offers features like efficient browser caching for fast reloads, on-demand code transformation for older browser compatibility, resolution of bare module imports (`--node-resolve`), and automatic browser reloading on file changes (`--watch`). Its key differentiator lies in promoting a "no-build" development workflow. While it remains functional and receives bug fixes, new development and active feature work have moved to its successor, `@web/dev-server`. Users are generally advised to use `@web/dev-server` for new projects and consider migrating existing ones.

Common errors

```
Error: Cannot find module 'es-dev-server'
```
cause The `es-dev-server` package is not installed or the `es-dev-server` command is not accessible in your system's PATH.

fix Run `npm install --save-dev es-dev-server` to install the package. If running via CLI, ensure you use `npx es-dev-server` or define it as a script in `package.json` (e.g., `"start": "es-dev-server ..."`).
```
Address already in use :::XXXX (where XXXX is a port number)
```
cause Another process on your machine is currently using the specified or default HTTP port (e.g., 8000).

fix Change the port `es-dev-server` listens on using the `--port` flag (e.g., `es-dev-server --port 8001`) or by modifying your configuration file. Alternatively, identify and terminate the process currently occupying the port.
```
ReferenceError: require is not defined in ES module scope
```
cause You are attempting to use CommonJS `require()` syntax within a JavaScript file that is being interpreted as an ES module (e.g., a programmatic config file or a custom plugin script).

fix Rewrite the problematic file to use ES module `import` syntax instead of `require()`. Ensure your `package.json` `type` field is correctly set, or use appropriate file extensions (e.g., `.cjs` for CommonJS, `.mjs` for ESM).

Warnings

breaking The `es-dev-server` project has been renamed to `@web/dev-server` (part of Open Web Components project). New development and active feature work is focused on the new package. Users are strongly recommended to migrate to `@web/dev-server` for new projects and consider upgrading existing ones.
Fix: Migrate your project from `es-dev-server` to `@web/dev-server` following the official migration guides provided by the Open Web Components project. Ensure you update your `package.json` dependencies and server configuration.
gotcha `es-dev-server` requires Node.js v10 or higher to function correctly. Older Node.js versions may lead to unexpected errors or a failure to start the server.
Fix: Ensure your Node.js installation is version 10 or greater. Use a Node Version Manager (like `nvm`) to easily switch or update your Node.js environment.
gotcha When serving over HTTP2 (using the `--http2` flag), `es-dev-server` uses self-signed SSL certificates by default. This will cause browser security warnings (e.g., 'Your connection is not private').
Fix: Accept the self-signed certificate in your browser for local development. For more permanent solutions or different environments, you may need to configure `es-dev-server` to use trusted SSL certificates.
gotcha Misconfiguration of `--node-resolve` and `--compatibility` flags can lead to issues. For instance, `--node-resolve` is crucial for handling bare module imports (e.g., `import 'lit'`), while `--compatibility` transforms code for older browsers, which might conflict or be unnecessary if not carefully managed.
Fix: Carefully review the documentation for `node-resolve` and `compatibility` options. Enable `--node-resolve` if you are using bare module specifiers. Adjust `--compatibility` based on your target browser support matrix to avoid over-transpiling or missing necessary polyfills.

Install

npm install es-dev-server npm
yarn add es-dev-server yarn
pnpm add es-dev-server pnpm

Imports

es-dev-server CLI
wrong:
```
es-dev-server [options]
```
correct:
```
npx es-dev-server [options]
```
Primary interaction is via CLI. Using `npx` ensures the locally installed version is used.
createConfig
wrong:
```
const { createConfig } = require('es-dev-server')
```
correct:
```
import { createConfig } from 'es-dev-server'
```
For programmatic configuration in ESM environments. CommonJS `require` might lead to issues in mixed module environments.

startServer

wrong:

const { startServer } = require('es-dev-server')

correct:

import { startServer } from 'es-dev-server'

For starting the server programmatically in ESM environments.

Quickstart

Demonstrates setting up `es-dev-server` to serve a simple HTML file with native ES module imports, using `npm scripts` for easy execution and `--node-resolve` for bare module support.

{
  "name": "my-es-dev-app",
  "version": "1.0.0",
  "description": "A simple app served by es-dev-server",
  "scripts": {
    "start": "es-dev-server --app-index public/index.html --node-resolve --watch --open --root-dir public"
  },
  "devDependencies": {
    "es-dev-server": "^2.1.0",
    "lit": "^2.0.0" 
  }
}

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ES Dev Server App</title>
</head>
<body>
    <h1>Welcome to ES Dev Server!</h1>
    <script type="module">
        // This bare module import requires --node-resolve
        import { html } from 'lit'; 
        console.log('App loaded via native ES Modules.');
        document.body.innerHTML += html`<p>Lit-html import worked!</p>`;
    </script>
</body>
</html>

# To run:
# npm install --save-dev es-dev-server lit
# npm run start

view raw JSON →