@domstack/sync

@domstack/sync

A modern, dependency-minimized live-reload dev server. A love letter to browser-sync: ESM-only, Fastify, native WebSocket, and a server-rendered HTMX UI panel.

Install

npm install @domstack/sync

CLI

# Serve current directory, watch CSS and HTML
domstack-sync --server . --files '**/*.css' '**/*.html'

# Serve current directory and watch the served root
domstack-sync --server . --watch

# Watch files without serving (snippet-injection mode)
domstack-sync --files '**/*.css'

# Short alias
dss --server . --files '**/*'

# Disable the UI panel
domstack-sync --server . --no-ui

# Write a starter ESM config file
domstack-sync init

# Trigger a reload from another terminal
domstack-sync reload --port 3000

CLI flags

Flag	Default	Description
--server, -s	—	Directory to serve
--files, -f	—	Glob patterns to watch (repeatable)
--watch, -w	—	Watch server roots in addition to --files
--ignore	—	Ignore patterns for file watchers (repeatable)
--port	3000	Port to listen on
--no-ui	—	Disable the UI panel
--no-notify	—	Disable the notification overlay
--no-ghost-mode	—	Disable scroll/click/location/form sync
--cors	—	Enable CORS headers
--log-level	info	Pino log level, for example silent, trace, debug, info, warn, error, or fatal
--log-connections	—	Log browser connection events at info level
--help, -h	—	Show help text
--version, -v	—	Show version

domstack-sync init writes domstack-sync.config.mjs using export default. On startup, the CLI loads the first config file it finds in this order: domstack-sync.config.mjs, .mts, .js, then .ts. TypeScript config files rely on Node's built-in type stripping.

API

import { createServer, parseOptions } from '@domstack/sync'

const sync = await createServer({
  server: './public',
  files: ['public/**/*.css', 'public/**/*.html'],
  port: 3000,
})

console.log(sync.url)    // http://localhost:3000
console.log(sync.uiUrl)  // http://localhost:3001

// Trigger a full reload
sync.reload()

// CSS-inject a specific file (falls back to full reload if not matched)
sync.reload(['styles/main.css'])

// Show a notification overlay in connected browsers
sync.notify('Build complete')

// Stream integration — pipe any { path } objects through to trigger reloads
someReadableStream.pipe(sync.stream())

// Listen for server-side events
sync.events.on('client:connect', (info) => console.log('connected', info.ua))
sync.events.on('client:disconnect', (id) => console.log('disconnected', id))
sync.events.on('file:change', (evt) => console.log('changed', evt.path))

// Pause / resume watcher-triggered reloads (e.g. during a build)
sync.pause()
sync.resume()

// Graceful shutdown
await sync.exit()

Logging

Standalone usage creates a pretty Pino logger automatically. When embedding @domstack/sync in another tool, pass a raw Pino logger and keep formatting ownership in the parent process:

import pino from 'pino'
import { createLogger, createServer, logAccessUrls } from '@domstack/sync'

// Standalone helper: returns a regular pino.Logger with domstack-sync's pretty formatter.
const standaloneLogger = createLogger('info')

// Embedded/library usage: pass your own raw pino.Logger.
const ownerLogger = pino({ level: 'info' })
const sync = await createServer({
  server: './public',
  files: ['public/**/*.css', 'public/**/*.html'],
  logger: ownerLogger.child({ component: 'sync', logPrefix: '[domstack-sync]' }),
})

logAccessUrls(standaloneLogger, {
  local: sync.url,
  ui: sync.uiUrl,
})

logAccessUrls(logger, urls) is exported for callers that want the same access-URL table with their own Pino logger.

Options

Option	Type	Default	Description
port	number	3000	Port to listen on (falls back to OS-assigned if taken)
server	string | boolean | string[] | object	false	Directory or directories to serve statically
files	string | string[] | object[]	[]	Glob patterns or chokidar watch objects to watch for changes
ghostMode	boolean | { scroll, clicks, location, forms }	all true	Sync interactions across connected browsers
logger	pino.Logger	—	Raw Pino logger supplied by an embedding owner; when omitted, sync creates its own standalone pretty logger
logLevel	Pino log level string	'info'	Log verbosity used by the standalone logger when logger is omitted
logConnections	boolean	false	Log browser connection events at info level
ui	boolean | { port: number }	true	UI panel — false disables, { port } pins the port
notify	boolean	true	Show notification overlay in connected browsers
cors	boolean	false	Add CORS headers to all responses
injectChanges	boolean	true	Inject matching file changes instead of full reload
injectFileTypes	string[]	['css', 'png', 'jpg', 'jpeg', 'svg', 'gif', 'webp', 'map']	Extensions eligible for file injection
tagNames	Record<string, string>	built-in asset tag map	Element tag names used for non-CSS file injection
codeSync	boolean	true	Broadcast reload and file-injection messages
reloadDebounce	number	500	Milliseconds to debounce file-change reloads
reloadDelay	number	0	Milliseconds to delay reload after a change
reloadThrottle	number	0	Minimum milliseconds between reload broadcasts
scrollThrottle	number	0	Minimum milliseconds between scroll sync messages
scrollElements	string[]	[]	CSS selectors eligible for element scroll sync
scrollElementMapping	string[]	[]	Selector mapping for scroll sync between different layouts
scrollProportionally	boolean	true	Sync scroll position proportionally instead of raw pixels
watch	boolean	false	Add server roots and routes to watched files
ignore	string | string[]	—	Ignore patterns merged into watcher options
watchOptions	object	{}	Options passed through to chokidar
watchEvents	string[]	['change']	Chokidar event names that trigger reloads
snippet	boolean	true	Inject the browser client snippet into HTML responses
snippetOptions	object	{}	Whitelist, blacklist, ignore paths, or custom injection rule
rewriteRules	object[]	[]	HTML rewrite rules applied before snippet injection
plugins	array	[]	BrowserSync-compatible plugin entries
cwd	string	process.cwd()	Working directory for resolving server and files

TypeScript

All types are exported:

import type { AccessUrls, BsInstance, BsOptions, BsOptionsInput, LoggerOptions, LoggerStreams } from '@domstack/sync'
import type { ServerToClientMessage, ClientToServerMessage } from '@domstack/sync'

How it works

• Script injection — an IIFE <script> tag is injected immediately after the opening <body> tag (or appended if there is no <body>) in every HTML response. The injected script connects to the WebSocket server.
• File injection — when a watched injectable file changes and injectChanges: true, matching DOM assets are cache-busted in place without a full page reload. CSS stylesheets, imported stylesheets, images, inline image URLs, and configured asset tags are supported. Falls back to a full reload if no matching asset is found.
• Ghost mode — scroll position, clicks, location changes, and form input changes in one browser are relayed to all other connected browsers via the WebSocket server. Disable with ghostMode: false or --no-ghost-mode.
• UI panel — a separate Fastify server on an auto-detected port shows connected browsers, file-change history, and server URLs. Disable with ui: false or --no-ui.
• Port selection — the requested port is tried first. If it is already in use, the OS assigns a free ephemeral port automatically.

License

MIT