@stencil/dev-server

@stencil/dev-server

Development server for Stencil with DOM-based Hot Module Replacement (HMR).

Install

npm install --save-dev @stencil/dev-server @stencil/core

Usage

The dev server is configured via stencil.config.ts and started automatically with stencil build --dev --watch --serve.

// stencil.config.ts
import { Config } from '@stencil/core';

export const config: Config = {
  devServer: {
    port: 3333,
    openBrowser: true,
    reloadStrategy: 'pageReload', // or 'hmr'
  },
  outputTargets: [{ type: 'www' }],
};

npx stencil build --dev --watch --serve

Programmatic API

start(config, logger, watcher?) — start the dev server

import { start } from '@stencil/dev-server';
import { createNodeLogger } from '@stencil/core/sys/node';

const server = await start(
  {
    root: './www',       // directory to serve
    port: 3333,
    openBrowser: true,
    reloadStrategy: 'hmr', // 'hmr' | 'pageReload' | null
  },
  createNodeLogger(),
);

console.log(`Listening at ${server.browserUrl}`);

// Shut down when done
await server.close();

With a Stencil compiler watcher (full HMR)

Pass a CompilerWatcher to connect build output to the dev server — file changes trigger HMR or a page reload automatically.

import * as coreCompiler from '@stencil/core/compiler';
import { start } from '@stencil/dev-server';
import { createNodeLogger, createNodeSys } from '@stencil/core/sys/node';

const logger = createNodeLogger();
const sys = createNodeSys();

const { config } = await coreCompiler.loadConfig({
  configPath: './stencil.config.ts',
  logger,
  sys,
});

const compiler = await coreCompiler.createCompiler(config);
const watcher = await compiler.createWatcher();

const server = await start(
  { root: './www', port: 3333, reloadStrategy: 'hmr' },
  logger,
  watcher,
);

// Start watching — builds trigger HMR updates in the browser
await watcher.start();

// To shut down:
// await watcher.close();
// await server.close();

The returned DevServer exposes address, browserUrl, protocol, port, root, and close().

Key config options

Option	Default	Description
root	'.'	Directory to serve files from
port	3333	Port to listen on
address	'0.0.0.0'	Network interface to bind
reloadStrategy	'hmr'	'hmr', 'pageReload', or null to disable
openBrowser	false	Open browser on start
https	—	{ cert, key } to enable HTTPS
worker	true	Fork server into a child process (disable for debugging)
ssr	false	Server-side render each page on request (dev only - you must have a ssr output target setup)