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:
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
Read more
Consider this example directory structure:
123
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.
Read more
Use the `--open` parameter for when you'd like to keep you index.html in a subfolder.
123
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:
1234
# with app-index flages-dev-server --app-index src/index.html --open
# without app-index flages-dev-server --open src/
You can also change the root directory of the dev server:
1
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](#rewriting-request-urls)
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.
Read more
For example, a typical monorepo setup looks like this:
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:
1234
# with app-index (for SPA)es-dev-server --root-dir ../../ --app-index packages/my-package/index.html --open
# without app-indexes-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:
1234
# with app index (for SPA)es-dev-server --app-index packages/my-package/index.html --open
# without app indexes-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
Read more
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 `` 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.
[Read more about this on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base)
Node resolve
“Bare imports” are imports which don’t specify a full path to a file:
1
importfoofrom'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:
1
importfoofrom'./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](https://github.com/rollup/plugins/tree/master/packages/node-resolve) 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.
123456789101112131415161718
module.exports={nodeResolve:{jsnext:true,browser:true,// set default to false because es-dev-server always// runs in the browserpreferBuiltins:true,// will overwrite es-dev-server's fileExtensions optionextensions:['.mjs','.js'],// will overwrite es-dev-server's dedupe optiondedupe:['lit-html'],customResolveOptions:{// will overwrite es-dev-server's moduleDirs optionmoduleDirectory:['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.
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.
Read more
Serve `/index.html` from `/src/index.html`:
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:
Read more
12345678910111213141516
constawesomePlugin=require('awesome-plugin');module.exports={plugins:[// use a pluginawesomePlugin({someOption:'someProperty'}),// create an inline plugin{transform(context){if(context.response.is('html')){return{body:context.body.replace(/<base href=".*">/,'<base href="/foo/">')};}},},],};
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:
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.
Read more
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`.
1234567891011121314151617181920
module.exports={plugins:[{resolveMimeType(context){// change all MD files to HTMLif(context.response.is('md')){return'html';}},},{resolveMimeType(context){// change all CSS files to JS, except for a specific fileif(context.response.is('css')&&context.path!=='/global.css'){return'js';}},},],};
It is also possible to set the full mime type directly:
constmarkdownToHTML=require('markdown-to-html-library');module.exports={plugins:[{resolveMimeType(context){// this ensures the browser interprets .md files as .htmlif(context.path.endsWith('.md')){return'html';}},asynctransform(context){// this will transform all MD files. if you only want to transform certain MD files// you can check context.pathif(context.path.endsWith('.md')){consthtml=awaitmarkdownToHTML(body);return{body:html};}},},],};
The resolveImport hook is called for each module import. It can be used to resolve module imports before they reach the browser.
Read more
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.
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.
Read more
Accessing the serverStart parameters:
1234567891011121314151617181920212223
functionmyFancyPlugin(){letrootDir;return{serverStart({config,app,server,fileWatcher}){// take the rootDir to access it laterrootDir=config.rootDir;// register a koa middleware directlyapp.use((context,next)=>{console.log(context.path);returnnext();});// register a file to be watchedfileWatcher.add('/foo.md');},};}module.exports={plugins:[myFancyPlugin()],};
Boot up another server for proxying in serverStart:
12345678910111213141516171819
constproxy=require('koa-proxies');module.exports={plugins:[{asyncserverStart({app}){// set up a proxy for certain requestsapp.use(proxy('/api',{target:'http://localhost:9001',}),);// boot up the other server, because it is awaited es-dev-server will also wait for itawaitstartOtherServer({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.
Read more
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](https://babeljs.io/docs/en/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](https://github.com/systemjs/systemjs).
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](https://github.com/systemjs/systemjs).
**none**
`none` disables compatibility mode entirely.
Polyfills loader
When compatibility mode is enabled, polyfills are loaded using polyfills-loader.
Read more
You can customize the polyfill loader configuration from your configuration file. Check the docs for the [polyfills-loader](https://github.com/open-wc/open-wc/tree/master/packages/polyfills-loader) for all possible options.
1234567891011121314
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:
You can use different components from es-dev-server as a library and integrate it with other tools:
Read more
### 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](#configuration-files)
### 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.
### 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.
### 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.
1234567891011121314
importKoafrom'koa';importchokidarfrom'chokidar';import{createConfig,createMiddlewares,createServer}from'es-dev-server';constconfig=createConfig({...});constfileWatcher=chokidar.watch([]);// if using createMiddlewarescreateMiddlewares(config,fileWatcher);// if using createServercreateServer(config,fileWatcher);// close filewatcher when no longer necessaryfileWatcher.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.
Returns the koa app and a node http or http2 server.