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

Development help

Code transformation

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:

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

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

index.html in a folder

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

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

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

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

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.

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

# 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

# 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

Base Element

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.

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.

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.

const indexHTML = generateIndexHTML();

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

const indexHTML = generateIndexHTML();

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

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.

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';
        }
      },
    },
  ],
};

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.

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

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 };
        }
      },
    },
  ],
};

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

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

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 };
        }
      },
    },
  ],
};

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.

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.

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()],
};

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:

1. User middleware: before "next"
2. Serve
   • Plugins: serve
   • es-dev-server: static file middleware (if no plugin match)
3. Plugins: resolveMimeType
4. Plugins: transform
5. Resolve module imports
   • Plugins: resolveModuleImport
   • es-dev-server: node-resolve (if no plugin resolve)
6. es-dev-server: babel + compatibility transforms
7. es-dev-server: response cache (caches all JS files served, including plugin transforms)
8. 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.

Polyfills loader

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

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

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:

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

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

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

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

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

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

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

async function main() {
  const config = createConfig({ ... });
  const { app, server } = await startServer(config, fileWatcher);
}

main();