`
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.

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:

`bash


with app-index flag

`bash
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

`
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:

`bash


with app-index (for SPA)

`bash


with app index (for SPA)

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

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

`js
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,
},
},
};
`

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

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

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

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

return next();
},
],
};
`

`js
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(//, '') };
}
},
},
],
};
`

`ts
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 };
type TransformResult = void | { body?: string; headers?: Record };
type ResolveResult = void | string | Promise | Promise;

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

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

Serve an auto generated index.html:

`js
const indexHTML = generateIndexHTML();

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

Serve a virtual module:

`js
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:

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

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.

`js
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:

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

`js
module.exports = {
plugins: [
{
transform(context) {
if (context.path === '/index.html') {
const transformedBody = context.body.replace(//, '');
return { body: transformedBody };
}
},
},
],
};
`

Inject a script to set global variables during local development:

`js
module.exports = {
plugins: [
{
transform(context) {
if (context.path === '/index.html') {
const transformedBody = context.body.replace(
'',
'',
);
return { body: transformedBody };
}
},
},
],
};
`

Inject environment variables into a JS module:

`js
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:

`js
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:

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

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.

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

`js
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:

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

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.

`js
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:

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

$3

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

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

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

$3

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.

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

$3

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.

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

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

$3

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.

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

$3

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.

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