Bundler-Independent Node.js Dev Server

0.1.2 · active · verified Tue Apr 21

Serdev is a Node.js development server designed for complex project structures, particularly monorepos, where multiple components might have disparate build processes. It differentiates itself by being bundler-agnostic, allowing users to integrate various build tools like esbuild, Webpack, Rust's Cargo, or custom Node.js scripts. The server watches specified directories for changes, triggering rebuilds of components and serving the generated artifacts or proxying to embedded servers. It aims to streamline development workflows by consolidating diverse build and serving requirements into a single configuration. As of version 0.1.2, it is in a very early stage of development, implying potential instability and rapid evolution, without a specified regular release cadence. Its key strength lies in its flexibility to manage heterogeneous build ecosystems.

Common errors

```
Error: Command failed with exit code 1
```
cause A component's `build` or `start` script (e.g., `esbuild`, `cargo`, `node scripts/build.js`) encountered an error during execution.

fix Check the console output for detailed errors from the failing build/start script. Ensure the command is correct, dependencies are installed (e.g., `npm install` in component directories), and paths are resolved correctly.
```
Address already in use :::<port>
```
cause `serdev` or one of its configured component servers is attempting to listen on a port that is already occupied by another process.

fix Identify the process using the port (`lsof -i :<port>` on Unix/macOS or `netstat -ano | findstr :<port>` on Windows) and terminate it, or change the `port` configuration in `serdev` for the conflicting component or for `serdev`'s main listening port.
```
404 Not Found
```
cause The requested URL does not match any of the configured `routes` in `serdev`, or a component artifact specified in a route does not exist after its build step.

fix Review your `routes` configuration in `serdev.listen()` to ensure it correctly maps paths to files or components. Verify that build processes for components linked to routes successfully produce the expected output files and paths.

Warnings

breaking Serdev relies on process groups to manage and terminate child processes, which are not supported on Windows operating systems. This limitation means the server may not function correctly or reliably on Windows environments, particularly concerning the lifecycle management of spawned build tools and component servers.
Fix: Currently, there is no known workaround mentioned. Users on Windows should consider alternative development servers or use a Linux/macOS environment (e.g., WSL2) for `serdev` development.
gotcha As of version 0.1.2, `serdev` is in early development. This implies that APIs, configurations, and internal behaviors are subject to change without strict adherence to semantic versioning for minor or patch releases, potentially introducing breaking changes unexpectedly.
Fix: Pin to exact versions in `package.json` (`"serdev": "0.1.2"`) to prevent unexpected updates. Regularly review GitHub releases or changelogs for breaking changes when upgrading.
gotcha Component build scripts and server start commands run as child processes. Ensure that all necessary binaries (e.g., `esbuild`, `cargo`, `node`) are available in the system's PATH or specified with full paths within the `build` and `start` commands in the `serdev` configuration.
Fix: Verify that your `PATH` environment variable includes directories containing required executables. For `npm` installed binaries, consider using `npx` or explicit paths to `node_modules/.bin` within your build commands.

Install

npm install serdev npm
yarn add serdev yarn
pnpm add serdev pnpm

Imports

serdev
wrong:
```
const serdev = require('serdev')
```
correct:
```
import * as serdev from 'serdev'
```
The primary import pattern for accessing all serdev functionalities as a namespace. CommonJS `require` is also supported.
listen
```
import { listen } from 'serdev'
```
While `import * as serdev` is shown, `listen` is the main function and could be destructured if preferred, assuming it's a named export.

Quickstart

This example configures `serdev` to manage and serve multiple distinct components within a monorepo, including custom build steps for TypeScript, Rust/WASM, and Node.js servers, alongside static file serving and API proxying, all with automatic rebuilds on file changes.

import * as serdev from "serdev";

serdev.listen({
  env: {
    RUST_BACKTRACE: "1"
  },
  headers: {
    "Cross-Origin-Opener-Policy": "same-origin",
    "Cross-Origin-Embedder-Policy": "require-corp"
  },
  components: {
    ui: {
      dir: "./ui",
      build: "esbuild --entry-points=src/index.ts --outdir=out --bundle --write",
      watch: ["src"]
    },
    website: {
      dir: "./website",
      build: "node scripts/build.js",
      watch: ["src"],
      deps: ["ui"]
    },
    app: {
      dir: "./app",
      build: "cargo build --target=wasm32-unknown-unknown",
      watch: ["src"]
    },
    api: {
      dir: "./api",
      build: "cargo build --features=dev",
      start: "target/debug/blob",
      port: 8001,
      watch: ["src"]
    },
    cdn: {
      dir: "./cdn",
      start: "node server.js",
      port: 8002
    }
  },
  routes: {
    "/favicon.ico": "./website/favicon.ico",
    "/app.js": ["app", "./app/out/index.js"],
    "/api/*": ["api"],
    "/assets/*rest": (x) => `./assets/${x.rest}`
  }
});

view raw JSON →