barely-a-dev-server

0.8.3 verified Fri May 01 auth: no javascript

A thin, opinionated wrapper for esbuild that watches and serves TypeScript files as ESM. Current stable version: 0.8.3. Release cadence: irregular, with multiple minor releases in 2024. Key differentiators: minimal codebase (<200 lines), zero runtime dependencies beyond esbuild, automatic source maps, and integrated dev server that maps entry .ts files to .js. Unlike esbuild's own --servedir, this directly serves compiled output with live rebuilds. No CLI, no live reload, no non-TS transformations. Requires Node >=19 or Bun >=1.0.30.

Common errors

error Error: Cannot find module 'barely-a-dev-server' ↓

cause Trying to use CommonJS require() on an ESM-only package.

fix

Use import syntax: import { barelyServe } from 'barely-a-dev-server'

error TypeError: barelyServe is not a function ↓

cause Using default import instead of named import.

fix

Correct import: import { barelyServe } from 'barely-a-dev-server'

error Failed to resolve entry point "src/index.ts" ↓

cause Entry root contains .ts files that esbuild cannot resolve; possibly wrong path or missing file.

fix

Ensure entryRoot is relative to current working directory and contains .ts files.

Warnings

breaking v0.6.0 changed file globbing to rely on esbuild, which may break builds expecting custom pattern matching. ↓

fix If you relied on custom glob patterns, update your entry points to match esbuild's built-in resolution.

gotcha All .ts files under entryRoot are treated as entry points, potentially generating many output files. ↓

fix Place library files outside entryRoot; only keep actual entry scripts inside.

deprecated v0.7.0 introduced bundleCSS option; prior versions do not support CSS bundling. ↓

fix Upgrade to >=0.7.0 and use bundleCSS option if CSS bundling is needed.

gotcha HTML files must reference .js output, not .ts source; the 'href' attribute is not processed by the server. ↓

fix In <script> tags, set src='./index.js' (not .ts). The href attribute is informational only.

breaking v0.8.0 uses @cubing/dev-config/esbuild/es2022 under the hood, which may change build defaults (e.g., target). ↓

fix Check your code for ES2022 compatibility; override esbuildOptions.target if needed.

breaking v0.6.1 removed a workaround for Bun; Bun >=1.0.30 is now required. ↓

fix Update Bun to >=1.0.30 or use Node >=19.

gotcha No CLI; you must import and call barelyServe manually or use node -e. ↓

fix Write a small script calling barelyServe() or run: node -e 'import("barely-a-dev-server").then(s => s.barelyServe({entryRoot: "src"}))'

Install

npm install barely-a-dev-server

yarn add barely-a-dev-server

pnpm add barely-a-dev-server

Imports

barelyServe

wrong

const barelyServe = require('barely-a-dev-server')

correct

import { barelyServe } from 'barely-a-dev-server'

ESM-only package; CommonJS require() will fail. Named export, not default.

barelyServe

wrong

import barelyServe from 'barely-a-dev-server'

correct

import { barelyServe } from 'barely-a-dev-server'

Default import is incorrect; use named import with braces.

Quickstart

Starts a dev server on port 3333 that watches and serves TypeScript files from the 'src' directory as ESM with source maps.

// script/build.js
import { barelyServe } from 'barely-a-dev-server';

barelyServe({
  entryRoot: 'src',
  dev: true,
  port: 3333,
  esbuildOptions: {
    target: 'esnext',
  },
});