next-speed-engine

A dependency-graph-aware compiler, watcher, incremental cache, and HMR engine for Next.js — built on clean architecture so any single piece can be swapped without touching business logic.

Why

Next.js dev mode owns the watcher, bundler, and HMR socket — but a lot of useful work (incremental SWC transforms, dependency-graph analytics, granular HMR boundaries, profiling) is hard to reach from inside the bundler. next-speed-engine is a standalone, framework-agnostic engine that does that work cleanly behind ports/adapters, then plugs into Next either as a sidecar dev process or as a next.config.js webpack plugin.

It is intentionally small, strictly typed (strict + exactOptionalPropertyTypes), and zero-magic.

Features

• Watcher — chokidar with debounced batching, atomic-write coalescing, large-tree-friendly defaults.
• AST parser — SWC-backed, extracts static + dynamic imports, exports, re-exports, and module features.
• Dependency graph — directed in-memory graph with O(V+E) SCC cycle detection and constant-time BFS for affected/downstream sets.
• Incremental cache — content-hash + producer-signature + dependency-fingerprint invalidation; memory, disk, or layered (memory L1 over disk L2).
• Compile pipeline — bounded parallel SWC transforms with cache-aware skip, per-batch results, and graceful per-module failures.
• HMR — typed WebSocket protocol, handshake, heartbeat, granular update / prune / reload envelopes, and a tree-shakable browser client with React Fast Refresh integration.
• Profiler — event-driven, lock-free counters/gauges/histograms with console + JSON reporters.
• Benchmark harness — warmup, percentiles, structured BenchmarkResult for CI gating.

Install

npm install next-speed-engine

Node 20+ required. ESM-only ("type": "module").

Quick start

As a CLI sidecar

npx next-speed

This boots the engine with defaultConfig() (project root = process.cwd()), starts the watcher and the HMR WebSocket on ws://localhost:3030.

Programmatic

import { createContainer, defaultConfig } from "next-speed-engine";

const config = defaultConfig();
const container = createContainer(config);

await container.service.start();

process.on("SIGINT", async () => {
  await container.service.stop();
  process.exit(0);
});

Browser HMR client

import { createHmrClient } from "next-speed-engine/client";

createHmrClient({
  url: "ws://localhost:3030",
  onUpdate: (u) => console.log(`hot update: ${u.patches.length} module(s)`),
}).connect();

The client lazy-resolves react-refresh/runtime and calls performReactRefresh() for .tsx/.jsx patches; non-eligible modules trigger a controlled full reload.

Documentation

| Topic | Document | |-------|----------| | Architecture — layers, ports/adapters, request flow | docs/architecture.md | | Configuration — EngineConfig reference + tuning | docs/configuration.md | | Watcher — chokidar adapter, batching, debounce | docs/watcher.md | | Dependency graph — model, traversals, cycle detection | docs/dependency-graph.md | | Cache — incremental cache, layering, invalidation | docs/cache.md | | Compile pipeline — parallel batches, dependency fingerprinting | docs/compile-pipeline.md | | HMR — wire protocol, boundary resolver, client runtime | docs/hmr.md | | Profiler — events, histograms, reporters | docs/profiler.md | | API reference — every public export | docs/api.md | | Next.js integration — sidecar vs plugin patterns | docs/integration-nextjs.md | | Contributing | CONTRIBUTING.md | | Changelog | CHANGELOG.md |

Project layout

next-speed-engine/
├── src/
│   ├── core/                Pure domain (entities, value objects, ports, errors)
│   ├── application/         Use cases, services, typed event bus
│   ├── infrastructure/      Adapters: SWC, chokidar, ws, memory/disk cache, profiler
│   ├── presentation/
│   │   ├── cli/             CLI entry (`next-speed`)
│   │   └── client/          Browser HMR runtime
│   ├── config/              EngineConfig + defaults
│   ├── shared/              Cross-cutting utils (hash, fs, concurrency)
│   ├── container/           Composition root (DI)
│   ├── client.ts            Browser barrel  → next-speed-engine/client
│   └── index.ts             Server barrel   → next-speed-engine
├── benchmarks/              Benchmark scenarios
├── tests/                   (skeleton — see tests/README.md)
└── docs/                    Long-form documentation

Scripts

| Script | What it does | |--------|-------------| | npm run build | Emit dist/ | | npm run typecheck | tsc --noEmit (strict) | | npm run dev | Run CLI via ts-node | | npm start | Run compiled CLI | | npm run bench | Run benchmark harness | | npm run clean | Remove dist/ and .cache/ |

Architecture in one diagram

┌─────────────────── presentation (CLI, browser HMR client) ───────────────────┐
│ ┌──────────────── infrastructure (SWC, chokidar, ws, fs, profiler) ────────┐ │
│ │ ┌─────────── application (use cases, services, event bus) ────────────┐  │ │
│ │ │ ┌───────────────── core (entities, ports, errors) ──────────────┐   │  │ │
│ │ │ │                       Pure TypeScript                         │   │  │ │
│ │ │ └───────────────────────────────────────────────────────────────┘   │  │ │
│ │ └─────────────────────────────────────────────────────────────────────┘  │ │
│ └─────────────────────────────────────────────────────────────────────────-─┘ │
└───────────────────────────────────────────────────────────────────────────────┘

The dependency rule is strict: outer layers depend on inner layers, never the reverse. Swap SWC for esbuild, chokidar for parcel-watcher, or ws for SSE — only container/ changes.

Status

0.x — API may evolve. Production use is supported behind a pinned version. See CHANGELOG.md for notable changes.

License

MIT