wds

0.24.2 verified Fri May 01 auth: no javascript

A fast reloading dev server for server-side TypeScript projects, version 0.24.2. Uses swc for on-demand compilation via ESM loaders and require.extensions. Prioritizes fast reboot over type checking, recommending out-of-band type checking. Key differentiators: incremental rebuilds in --watch mode, ESM and CJS support, monorepo awareness, disk caching, and IPC support. Inspired by ts-node-dev and tsx but with a focus on speed and simplicity. Maintained by Gadget Inc., with active releases.

Common errors

error Error: Cannot find module 'typescript' ↓

cause wds does not require TypeScript as a peer dependency, but some projects expect it.

fix

Install TypeScript: npm install --save-dev typescript

error TypeError: The 'superCtor' argument must be of type function. ↓

cause Attempting to import/require wds as a module.

fix

Use wds as a CLI tool: npx wds ...

error wds: command not found ↓

cause wds is not installed globally or in PATH.

fix

Run npx wds or install with npm install -g wds

Warnings

gotcha wds does NOT type-check your code. Rely on editor or CI for type checks. ↓

fix Run tsc --noEmit separately in CI or use editor integration.

breaking ESM-only from v0.21.0 onwards. CJS projects must upgrade or pin older version. ↓

fix Ensure package.json has 'type': 'module' or use .mjs extensions.

gotcha The --supervise flag will restart the process indefinitely even on non-code exit (e.g., process.exit(0)). ↓

fix Use --watch for file change restarts unless you need process supervision.

deprecated Old configuration via .swcrc is now secondary; wds.js is the primary config file. ↓

fix Migrate config to wds.js file per documentation.

Install

npm install wds

yarn add wds

pnpm add wds

Imports

wds
wrong
```
Using require('wds') or import wds from 'wds'
```
correct
```
npx wds script.ts
```
wds is a CLI tool, not a library. Do not import it programmatically.

config

wrong

import config from 'wds' or using .wdsrc

correct

// wds.js file in project root
module.exports = { extensions: ['.ts', '.tsx'] }

Configuration is done via wds.js file exporting an object, not via package.json or direct imports.

types
wrong
```
import { WdsOptions } from 'wds'
```
correct
```
npx wds --help
```
TypeScript types are for internal use; use CLI flags for usage.

Quickstart

Runs a TypeScript server in watch mode, restarting on file changes.

npx wds@0.24.2 --watch server.ts