A reloading dev server for server side TypeScript projects. Compiles TypeScript real fast, on demand, using require.extensions, and restarts the server when things change. Similar to and inspired by ts-node-dev.

wds stands for Whirlwind (or web) Development Server.

After installing wds, you can use it like you might use the node command line program:

# run one script with wds compiling TS to JS as it is required
wds some-script.ts

# run one server with wds watching the files for changes, and re-running the server when they change
wds --watch some-server.ts

# run one script with node command line arguments that you'd normally pass to `node`
wds --inspect some-test.test.ts

• Builds and runs TypeScript really fast (using swc or esbuild)
• Incrementally rebuilds only what has changed in the --watch mode, and restarts the process when files change
• Supervises the node.js process with --supervise to keep incremental context around on process crash, and can restart on demand in the --commands mode
• Plays nice with node.js command line flags like --inspect or --prof
• Produces sourcemaps which Just Work™️ by default for debugging with many editors (VSCode, IntelliJ, etc)
• Monorepo aware, allowing for different configuration per package and only compiling what is actually required from the monorepo context

You deserve to get stuff done. You deserve a fast iteration loop. If you're writing TypeScript for node, you still deserve to have a fast iteration loop, but with big codebases, tsc can get quite slow. Instead, you can use a fast TS => JS transpiler like esbuild or swc to quickly reload your runtime code and get to the point where you know if your code is working as fast as possible. This means a small sacrifice: tsc no longer typechecks your code as you run it, and so you must supplement with typechecking in your editor or in CI.

This tool prioritizes rebooting a node.js TypeScript project as fast as possible. This means it doesn't typecheck. Type checking gets prohibitively slow at scale, so we recommend using this separate typechecker approach that still gives you valuable feedback out of band. That way, you don't have to wait for it to see if your change actually worked. We usually don't run anything other than VSCode's TypeScript integration locally, and then run a full tsc --noEmit in CI.

Options:
      --help       Show help                                           [boolean]
      --version    Show version number                                 [boolean]
  -c, --commands   Trigger commands by watching for them on stdin. Prevents
                   stdin from being forwarded to the process. Only command right
                   now is `rs` to restart the server. [boolean] [default: false]
  -w, --watch      Trigger restarts by watching for changes to required files
                                                       [boolean] [default: true]
  -s, --supervise  Supervise and restart the process when it exits indefinitely
                                                      [boolean] [default: false]
      --esbuild    Use esbuild for compiling files    [boolean] [default: false]

Configuration for wds is done by adding a wds.js file to your pacakge root, and optionally a .swcrc file if using swc as your compiler backend.

An wds.js file needs to export an object like so:

module.exports = {
  // which file extensions to build, defaults to .js, .jsx, .ts, .tsx extensions
  extensions: [".tsx", ".ts", ".mdx"],

  // file paths to explicitly not transform for speed, defaults to [], plus whatever the compiler backend excludes by default, which is `node_modules` for both esbuild and swc
  ignore: ["spec/integration/**/node_modules", "spec/**/*.spec.ts", "cypress/", "public/"],

  // esbuild compiler options like `target`
  esbuild: {
    target: ["node16"]
    // ...
  },
};

swc is the fastest TypeScript compiler we've found and is the default compiler wds uses. wds sets up a default swc config suitable for compiling to JS for running in Node:

{
  "env": {
    "targets": {
      "node": 16,
    },
  },
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true,
      "dynamicImport": true,
    },
    "target": "es2020",
  },
  "module": {
    "type": "commonjs",
    // turn on lazy imports for maximum reboot performance
    "lazy": true,
  },
}

Note: the above config is different than the default swc config. It's been honed to give maximum performance for server start time, but can be adjusted by creating your own .swcrc file.

Configuring swc's compiler options with with wds can be done using the wds.js file. Create a file named wds.js in the root of your repository with content like this:

// wds.js
module.exports = {
  swc: {
    env: {
      targets: {
        node: 12
      }
    }
  },
};

You can also use swc's built in configuration mechanism which is an .swcrc file. Using an .swcrc file is useful in order to share swc configuration between wds and other tools that might use swc under the hood as well, like @swc/jest. To stop using wds's default config and use the config from a .swcrc file, you must configure wds to do so using wds.js like so:

// in wds.js
module.exports = {
  swc: ".swcrc"
};

And then, you can use swc's standard syntax for the .swcrc file

// in .swcrc, these are the defaults wds uses
{
  "env": {
    "targets": {
      "node": 16,
    },
  },
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true,
      "dynamicImport": true,
    },
    "target": "es2020",
  },
  "module": {
    "type": "commonjs",
    // turn on lazy imports for maximum reboot performance
    "lazy": true,
  },
}

Refer to the SWC docs for more info.

esbuild is a very fast and generally more stable TypeScript compiler for node. To use esbuild for your project's builds, pass the --esbuild command line flag.

esbuild accepts a wide variety of options governing what kind of JS is produced. wds sets up a default set of options:

{
    platform: "node",
    format: "cjs",
    target: ["node14"],
    sourcemap: "inline",
}

If you want to override these options, you can create a wds.js file in your project root and pass options to override these like so:

// wds.js
module.exports = {
  esbuild: {
    target: ["node12"]
    // ...
  },
};

Refer to the esbuild docs for more info on the available options.

ts-node-dev (and ts-node) accomplish a similar feat but are often 5-10x slower than wds in big projects. They are loaded with features and will keep up with new TypeScript features much better as they use the mainline TypeScript compiler sources, and we think they make lots of sense! Because they use TypeScript proper for compilation though, even with --transpile-only, they are destined to be slower than esbuild. wds is for the times where you care a lot more about performance and are ok with the tradeoffs esbuild or swc makes, like not supporting const enum and being a touch behind on supporting new TypeScript releases.