permalink: 'developing/es-dev-server.html' title: ES dev server section: guides tags:

guides

Notice

Development of es-dev-server continues under a new name: web dev server. We recommend using it for new projects, and upgrading for existing projects.

We will continue to support fixing bugs for es-dev-server.

es dev server

A web server for development without bundling.

npx es-dev-server --node-resolve --watch

Quick overview

efficient browser caching for fast reloads
transform code on older browsers for compatibility
resolve bare module imports for use in the browser (--node-resolve)
auto-reload on file changes with the (--watch)
history API fallback for SPA routing (--app-index index.html)
plugin API for extensions

See all commands

Getting started

We recommend following this guide for a step by step overview of different workflows with es-dev-server.

Setup

npm i --save-dev es-dev-server

Add scripts to your package.json, modify the flags as needed:

{
  "scripts": {
    "start": "es-dev-server --app-index index.html --node-resolve --watch --open"
  }
}

Run the server:

npm run start

Node version

es-dev-server requires node v10 or higher

Command-line flags and Configuration

Server configuration

name	type	description
port	number	The port to use, uses a random free port if not set.
hostname	string	The hostname to use. Default: localhost
open	boolean/string	Opens the browser on app-index, root dir or a custom path
app-index	string	The app's index.html file, sets up history API fallback for SPA routing
root-dir	string	The root directory to serve files from. Default: working directory
base-path	string	Base path the app is served on. Example: /my-app
config	string	The file to read configuration from (JS or JSON)
cors	boolean	Enable CORS
help	none	See all options

Development help

name	type	description
watch	boolean	Reload the browser when files are edited
http2	boolean	Serve files over HTTP2. Sets up HTTPS with self-signed certificates

Code transformation

name	type	description
compatibility	string	Compatibility mode for older browsers. Can be: `auto`, `always`, `min`, `max` or `none` Default `auto`
node-resolve	boolean	Resolve bare import imports using node resolve
dedupe	boolean/array	Deduplicates all modules, or modules from specified packages if the value is an array
preserve-symlinks	boolean	Preserve symlinks when resolving modules. Set to true, if using tools that rely on symlinks, such as `npm link`. Default false.
module-dirs	string/array	Directories to resolve modules from. Used by node-resolve
babel	boolean	Transform served code through babel. Requires .babelrc
file-extensions	string/array	Extra file extensions to use when transforming code.
babel-exclude	number/array	Patterns of files to exclude from babel compilation.
babel-modern-exclude	number/array	Patterns of files to exclude from babel compilation on modern browsers.
babel-module-exclude	number/array	Patterns of files to exclude from babel compilation for modules only.
event-stream	boolean	Whether to inject event stream script. Defaults to true.

Most commands have an alias/shorthand. You can view them by using --help.

Configuration files

We pick up an es-dev-server.config.js file automatically if it is present in the current working directory. You can specify a custom config path using the config flag.

Configuration options are the same as command line flags, using their camelCased names. Example:

module.exports = {
  port: 8080,
  watch: true,
  nodeResolve: true,
  appIndex: 'demo/index.html',
  plugins: [],
  moduleDirs: ['node_modules', 'web_modules'],
};

In addition to the command-line flags, the configuration file accepts these additional options:

name	type	description
middlewares	array	Koa middlewares to add to the server. (read more below)
plugins	array	Plugins to add to the server. (read more below)
babelConfig	object	Babel config to run with the server.
polyfillsLoader	object	Configuration for the polyfills loader. (read more below)
debug	boolean	Whether to turn on debug mode on the server.

Serving files

es-dev-server is a static web server. When a request is made from the browser for /foo/bar.js it will try and find this file from the root directory. It cannot serve any files outside of your root directory because the browser has no way to request them, and the path on the file system must always be reflected in the path of the browser.

index.html in the root

The simplest setup, making sure that all files are accessible, is to place your index.html at the root of your project

Consider this example directory structure:

node_modules/...
src/...
index.html

If you run the es-dev-server command from the root of the project, you can access your app at / or /index.html in the browser.

index.html in a folder

If you move your index.html outside the root of your project, you have some different options.

Use the --open parameter for when you'd like to keep you index.html in a subfolder.

node_modules/...
src/...
src/index.html

You can access your app in the browser at /src/ or /src/index.html. You can tell es-dev-server to explicitly open at this path:

# with app-index flag
es-dev-server --app-index src/index.html --open
# without app-index flag
es-dev-server --open src/

You can also change the root directory of the dev server:

es-dev-server --root-dir src --open

Now your index.html is accessible at / or /index.html. However, the dev server cannot serve any files outside of the root directory. So if your app uses any node modules, they will no longer because accessible.

If you want your index in a subfolder without this being visible in the browser URL, you can set up a file rewrite rule. Read more here

Monorepos

If you are using es-dev-server in a monorepo, your node modules are in two different locations. In a package's folder and at the repository root. You need to make sure that es-dev-server can serve from both directories.

For example, a typical monorepo setup looks like this:

node_modules/...
packages/my-package/node_modules/...
packages/my-package/index.html

You will need to make sure the root node_modules folder is accessible to the dev server.

If your working directory is packages/my-package you can use this command:

# with app-index (for SPA)
es-dev-server --root-dir ../../ --app-index packages/my-package/index.html --open
# without app-index
es-dev-server --root-dir ../../ --open packages/my-package/index.html

If your working directory is the root of the repository you can use this command:

# with app index (for SPA)
es-dev-server --app-index packages/my-package/index.html --open
# without app index
es-dev-server --open packages/my-package/index.html

This is the same approach as serving an index.html in a subdirectory, so the section above applies here as well.

Base Element

If you are building a single page application with client-side routing, we recommend adding a base element to set the base URL of your document.

The base URL of the document can be accessed through document.baseURI and is used by the browser to resolve relative paths (anchors, images, links, scripts, etc.). By default, it is set to the browser's URL.

You can add <base href=""> element to modify how files are resolved relatively to your index.html. This can be very useful when your index.html is not at the root of your project.

Node resolve

"Bare imports" are imports which don't specify a full path to a file:

import foo from 'bar';

The browser doesn't know where to find this file called bar. The --node-resolve flag resolves this bare import to the actual file path before serving it to the browser:

import foo from './node_modules/bar/bar.js';

Because we use es-module-lexer for blazing fast analysis to find the imports in a file without booting up a full-blown parser like babel, we can do this without a noticeable impact on performance.

For the actual resolve logic, we internally use @rollup/plugin-node-resolve so that you can keep the resolve logic in sync between development and production. When using a config file, the nodeResolve can also be an object which accepts the same options as the rollup plugin. options.

Example config

See the rollup docs for all options and what they do.

Some options like dedupe, fileExtensions, preserveSymlinks and moduleDirs are mapped to options for nodeResolve internally. You can overwrite them with your custom config.

module.exports = {
  nodeResolve: {
    jsnext: true,
    browser: true,
    // set default to false because es-dev-server always
    // runs in the browser
    preferBuiltins: true,
    // will overwrite es-dev-server's fileExtensions option
    extensions: ['.mjs', '.js'],
    // will overwrite es-dev-server's dedupe option
    dedupe: ['lit-html'],
    customResolveOptions: {
      // will overwrite es-dev-server's moduleDirs option
      moduleDirectory: ['node_modules'],
      preserveSymlinks: true,
    },
  },
};

In the future, we are hoping that import maps will make this step unnecessary.

Middleware

You can add your own middleware to es-dev-server using the middlewares property. The middleware should be a standard koa middleware. Read more about koa here.

You can use middleware to modify respond to any request from the browser, for example to rewrite a URL or proxy to another server. For serving or manipulating files it's recommended to use plugins.

Proxying requests

const proxy = require('koa-proxies');

module.exports = {
  port: 9000,
  middlewares: [
    proxy('/api', {
      target: 'http://localhost:9001',
    }),
  ],
};

Rewriting request urls

You can rewrite certain file requests using a simple middleware. This can be useful for example to serve your index.html from a different file location or to alias a module.

Serve /index.html from /src/index.html:

module.exports = {
  middlewares: [
    function rewriteIndex(context, next) {
      if (context.url === '/' || context.url === '/index.html') {
        context.url = '/src/index.html';
      }

      return next();
    },
  ],
};

Plugins

Plugins are objects with lifecycle hooks called by es-dev-server as it serves files to the browser. They can be used to serve virtual files, transform files, or resolve module imports.

Adding plugins

A plugin is just an object that you add to the plugins array in your configuration file. You can add an object directly, or create one from a function somewhere:

const awesomePlugin = require('awesome-plugin');

module.exports = {
  plugins: [
    // use a plugin
    awesomePlugin({ someOption: 'someProperty' }),
    // create an inline plugin
    {
      transform(context) {
        if (context.response.is('html')) {
          return { body: context.body.replace(/<base href=".*">/, '<base href="/foo/">') };
        }
      },
    },
  ],
};

See the full type interface for all options:

import Koa, { Context } from 'koa';
import { FSWatcher } from 'chokidar';
import { Server } from 'net';
import { ParsedConfig } from './config';

type ServeResult = void | { body: string; type?: string; headers?: Record<string, string> };
type TransformResult = void | { body?: string; headers?: Record<string, string> };
type ResolveResult = void | string | Promise<void> | Promise<string>;

interface ServerArgs {
  config: ParsedConfig;
  app: Koa;
  server: Server;
  fileWatcher: FSWatcher;
}

export interface Plugin {
  serverStart?(args: ServerArgs): void | Promise<void>;
  serve?(context: Context): ServeResult | Promise<ServeResult>;
  transform?(context: Context): TransformResult | Promise<TransformResult>;
  resolveImport?(args: { source: string; context: Context }): ResolveResult;
  resolveMimeType?(context: Context): undefined | string | Promise<undefined | string>;
}

Hook: serve

The serve hook can be used to serve virtual files from the server. The first plugin to respond with a body is used. It can return a Promise.

Serve an auto generated index.html:

const indexHTML = generateIndexHTML();

module.exports = {
  plugins: [
    {
      serve(context) {
        if (context.path === '/index.html') {
          return { body: indexHTML };
        }
      },
    },
  ],
};

Serve a virtual module:

const indexHTML = generateIndexHTML();

module.exports = {
  plugins: [
    {
      serve(context) {
        if (context.path === '/messages.js') {
          return { body: 'export default "Hello world";' };
        }
      },
    },
  ],
};

The file extension is used to infer the mime type to respond with. If you are using a non-standard file extension you can use the type property to set it explicitly:

module.exports = {
  plugins: [
    {
      serve(context) {
        if (context.path === '/foo.xyz') {
          return { body: 'console.log("foo bar");', type: 'js' };
        }
      },
    },
  ],
};

Hook: resolveMimeType

Browsers don't use file extensions to know how to interpret files. Instead, they use media or MIME type which is set using the content-type header.

es-dev-server guesses the MIME type based on the file extension. When serving virtual files with non-standard file extensions, you can set the MIME type in the returned result (see the examples above). If you are transforming code from one format to another, you need to use the resolveMimeType hook.

The returned MIME type can be a file extension, this will be used to set the corresponding default MIME type. For example js resolves to application/javascript and css to text/css.

module.exports = {
  plugins: [
    {
      resolveMimeType(context) {
        // change all MD files to HTML
        if (context.response.is('md')) {
          return 'html';
        }
      },
    },
    {
      resolveMimeType(context) {
        // change all CSS files to JS, except for a specific file
        if (context.response.is('css') && context.path !== '/global.css') {
          return 'js';
        }
      },
    },
  ],
};

It is also possible to set the full mime type directly:

module.exports = {
  plugins: [
    {
      resolveMimeType(context) {
        if (context.response.is('md')) {
          return 'text/html';
        }
      },
    },
  ],
};

Hook: transform

The transform hook is called for each file and can be used to transform a file. Multiple plugins can transform a single file. It can return a Promise.

This hook is useful for small modifications, such as injecting environment variables, or for compiling files to JS before serving them to the browser.

If you are transforming non-standard file types, you may also need to include a resolveMimeType hook.

Rewrite the base path of your application for local development;

module.exports = {
  plugins: [
    {
      transform(context) {
        if (context.path === '/index.html') {
          const transformedBody = context.body.replace(/<base href=".*">/, '<base href="/foo/">');
          return { body: transformedBody };
        }
      },
    },
  ],
};

Inject a script to set global variables during local development:

module.exports = {
  plugins: [
    {
      transform(context) {
        if (context.path === '/index.html') {
          const transformedBody = context.body.replace(
            '</head>',
            '<script>window.process = { env: { NODE_ENV: "development" } }</script></head>',
          );
          return { body: transformedBody };
        }
      },
    },
  ],
};

Inject environment variables into a JS module:

const packageJson = require('./package.json');

module.exports = {
  plugins: [
    {
      transform(context) {
        if (context.path === '/src/environment.js') {
          return { body: `export const version = '${packageJson.version}';` };
        }
      },
    },
  ],
};

Transform markdown to HTML:

const markdownToHTML = require('markdown-to-html-library');

module.exports = {
  plugins: [
    {
      resolveMimeType(context) {
        // this ensures the browser interprets .md files as .html
        if (context.path.endsWith('.md')) {
          return 'html';
        }
      },

      async transform(context) {
        // this will transform all MD files. if you only want to transform certain MD files
        // you can check context.path
        if (context.path.endsWith('.md')) {
          const html = await markdownToHTML(body);

          return { body: html };
        }
      },
    },
  ],
};

Polyfill CSS modules in JS:

module.exports = {
  plugins: [
    {
      resolveMimeType(context) {
        if (context.path.endsWith('.css')) {
          return 'js';
        }
      },

      async transform(context) {
        if (context.path.endsWith('.css')) {
          const stylesheet = `
            const stylesheet = new CSSStyleSheet();
            stylesheet.replaceSync(${JSON.stringify(body)});
            export default stylesheet;
          `;

          return { body: stylesheet };
        }
      },
    },
  ],
};

Hook: resolveImport

The resolveImport hook is called for each module import. It can be used to resolve module imports before they reach the browser.

es-dev-server already resolves module imports when the --node-resolve flag is turned on. You can do the resolving yourself, or overwrite it for some files.

The hook receives the import string and should return the string to replace it with. This should be a browser-compatible path, not a file path.

module.exports = {
  plugins: [
    {
      async resolveImport({ source, context }) {
        const resolvedImport = fancyResolveLibrary(source);
        return resolvedImport;
      },
    },
  ],
};

Hook: serverStart

The serverStart hook is called when the server starts. It is the ideal location to boot up other servers you will proxy to. It receives the server config, which you can use if plugins need access to general information such as the rootDir or appIndex. It also receives the HTTP server, Koa app, and chokidar file watcher instance. These can be used for more advanced plugins. This hook can be async, and it awaited before actually booting the server and opening the browser.

Accessing the serverStart parameters:

function myFancyPlugin() {
  let rootDir;

  return {
    serverStart({ config, app, server, fileWatcher }) {
      // take the rootDir to access it later
      rootDir = config.rootDir;

      // register a koa middleware directly
      app.use((context, next) => {
        console.log(context.path);
        return next();
      });

      // register a file to be watched
      fileWatcher.add('/foo.md');
    },
  };
}

module.exports = {
  plugins: [myFancyPlugin()],
};

Boot up another server for proxying in serverStart:

const proxy = require('koa-proxies');

module.exports = {
  plugins: [
    {
      async serverStart({ app }) {
        // set up a proxy for certain requests
        app.use(
          proxy('/api', {
            target: 'http://localhost:9001',
          }),
        );

        // boot up the other server, because it is awaited es-dev-server will also wait for it
        await startOtherServer({ port: 9001 });
      },
    },
  ],
};

Koa Context

The plugin hooks simply receive the Koa Context object. This contains information about the server's request and response. Check the Koa documentation to learn more about this.

To transform specific kinds of files we don't recommend relying on file extensions. Other plugins may be using non-standard file extensions. Instead, you should use the server's MIME type or content-type header. You can easily check this using the context.response.is() function. This is used a lot in the examples above.

Because files can be requested with query parameters and hashes, we recommend using context.path for reading the path segment of the URL only. If you do need to access search parameters, we recommend using context.URL.searchParams.get('my-parameter').

Order of execution

The order of execution for the es-dev-server when a file request is received:

User middleware: before "next"
Serve
- Plugins: serve
- es-dev-server: static file middleware (if no plugin match)
Plugins: resolveMimeType
Plugins: transform
Resolve module imports
- Plugins: resolveModuleImport
- es-dev-server: node-resolve (if no plugin resolve)
es-dev-server: babel + compatibility transforms
es-dev-server: response cache (caches all JS files served, including plugin transforms)
User middleware: after "next"

Typescript support

Because es-dev-server doesn't do any bundling, it's easy to integrate it with typescript and doesn't require any extra tooling or plugins. Just run tsc on your code, and serve the compiled output with es-dev-server. You can run both tsc and es-dev-server in watch mode, changes will be picked up automatically.

Make sure to configure tsc to output real ES modules.

Compatibility mode

Compatibility mode enables bundle-free development using modern browsers features on older browsers. Automatic compatibility mode is enabled by default.

Compatibility mode can be configured using the --compatibility flag. The possible options are auto, min, max, and none. The default is mode is auto.

auto auto compatibility looks at the current browser to determine the level of compatibility to enable. On the latest 2 versions of the major browsers, it doesn't do any work. This keeps the server as fast as possible in the general case.

On older browsers, the server uses the browser's user agent and @babel/preset-env to do a targeted transformation for that specific browser and version. @babel/preset-env only works with stage 4 javascript features, they should become an official standard before they can be used.

If the browser does not support es module scripts, dynamic imports or import.meta.url es modules are transformed to system-js.

This works down to at least IE11. Depending on what browser features you are using, it might work with an earlier version too but this is not tested.

always always compatibility is the same as auto, except that it doesn't skip compiling on the latest 2 versions of the major browsers. This makes it a bit slower on modern browsers but allows you to use new features before they are implemented in the browser.

min min compatibility forces the same level of compatibility on all browsers. It makes code compatible with the latest two versions of the major browsers and does not transform es modules.

max max compatibility forces the same level of compatibility on all browsers. It compiles everything to es5 and system-js.

none none disables compatibility mode entirely.

Polyfills loader

When compatibility mode is enabled, polyfills are loaded using polyfills-loader.

You can customize the polyfill loader configuration from your configuration file. Check the docs for the polyfills-loader for all possible options.

module.exports = {
  polyfillsLoader: {
    polyfills: {
      fetch: false,
      custom: [
        {
          name: 'my-feature-polyfill',
          path: require.resolve('my-feature-polyfill'),
          test: "!('myFeature' in window)",
        },
      ],
    },
  },
};

By default, es-dev-server wraps all scripts and are deferred until polyfills are loaded. Loading order of scripts are preserved, but this can create problems if you rely on a script being executed before HTML is parsed. You can configure es-dev-server to exclude certain types of scripts:

module.exports = {
  polyfillsLoader: {
    exclude: {
      jsModules: true,
      inlineJsModules: true,
      jsScripts: true,
      inlineJsScripts: true,
    },
  },
};

Using es-dev-server programmatically

You can use different components from es-dev-server as a library and integrate it with other tools:

createConfig

When using the server from javascript you are going to need a config object to tell the server what options to turn on and off. It's best to use createConfig for this as this converts the public API to an internal config structure and sets up default values.

By default, all options besides static file serving are turned off, so it's easy to configure based on your requirements.

The config structure is the same as the configuration explained in the configuration files section

import { createConfig } from 'es-dev-server';

const config = createConfig({
  http2: true,
  babel: true,
  open: true,
});

createMiddlewares

createMiddlewares creates the dev server's middlewares based on your configuration. You can use this to hook them up to your koa server.

Returns an array of koa middleware functions.

import Koa from 'koa';
import { createConfig, createMiddlewares } from 'es-dev-server';

const config = createConfig({});
const middlewares = createMiddlewares(config);

const app = new Koa();
middlewares.forEach(middleware => {
  app.use(middleware);
});

createServer

createServer creates an instance of the dev server including all middlewares, but without starting the server. This is useful if you want to be in control of starting the server yourself.

Returns the koa app and a node http or http2 server.

import Koa from 'koa';
import { createConfig, createServer } from 'es-dev-server';

const config = createConfig({ ... });
const { app, server } = createServer(config);
server.listen(3000);

watch mode

createMiddlewares and createServer requires a chokidar fileWatcher if watch mode is enabled. You need to pass this separately because the watcher nees-dev-server to be killed explicitly when the server closes.

import Koa from 'koa';
import chokidar from 'chokidar';
import { createConfig, createMiddlewares, createServer } from 'es-dev-server';

const config = createConfig({ ... });
const fileWatcher = chokidar.watch([]);

// if using createMiddlewares
createMiddlewares(config, fileWatcher);
// if using createServer
createServer(config, fileWatcher);

// close filewatcher when no longer necessary
fileWatcher.close();

startServer

startServer asynchronously creates and starts the server, listening on the configured port. It opens the browser if configured and logs a startup message.