How webpack/webpack-dev-middleware works
Project type and purpose
• This is an open‑source Node.js middleware package (“webpack‑dev‑middleware”) that plugs into HTTP server frameworks (Express, Koa, Fastify, Hapi, etc.) to serve Webpack bundles directly from memory during development. It acts as an adapter between an HTTP server and the Webpack Compiler API.
File structure
• Top‑level:
• src/ — core implementation
– index.js: exports the middleware factory and framework wrappers
– middleware.js: primary request handler, hooks into compiler
– utils/: helper modules (getFilenameFromUrl, etag, ready, setupHooks, setupOutputFileSystem, escapeHtml, etc.)
– options.json: default option values
• types/: TypeScript definitions mirroring src/
• scripts/: test setup and global initialization
• test/: fixtures, helpers, unit tests for each utility and middleware behavior
• Configuration files: jest.config.js, babel.config.js, eslint, husky, commitlint, tsconfig.json
• Key patterns:
• Middleware/adapter pattern to integrate with multiple servers
• Observer pattern: subscribe to Webpack Compiler hooks (compile, done, invalid)
• In‑memory filesystem abstraction (memfs) with adapter methods (join, mkdirp)
• Optional disk‑write adapter for writeToDisk feature
README for additional insights
• Purpose: serve compiled assets from memory, delay requests during recompilation, support HMR, optional server‑side rendering.
• Usage: compiler → middleware(compiler, options) → app.use(…).
• API: instance methods (close, invalidate, waitUntilValid, getFilenameFromUrl), server‑side render mode writing stats & outputFileSystem to res.locals.
Components
a. External HTTP Server Frameworks
• Express, Koa, Fastify, Hapi (each uses a thin wrapper: koaWrapper, hapiPlugin, honoWrapper, etc.)
b. webpack‑dev‑middleware Core
• Factory (index.js) → returns instance with middleware(req, res, next)
• Internal Modules: middleware.js, setupHooks, ready, getFilenameFromUrl, setupOutputFileSystem, modifyResponseData
c. Webpack Compiler Instance
• Emits events (compile, invalid, done)
d. In‑Memory File System
• Default: memfs adapter (join, mkdirp)
• Optional: real disk FS when writeToDisk enabled
e. Client & Browser
• HTTP requests for assets (GET, HEAD) → middleware → served from memory FS or queued until compile finishes
f. (Optional) Server‑Side Rendering Path
• res.locals.webpack.devMiddleware.stats + outputFileSystem → render HTML on server
Relationships & interactions
• Server receives HTTP request → passes to webpack‑dev‑middleware
→ middleware uses getFilenameFromUrl to map URL to an asset path
→ if compile in progress, queue the request until “done”
→ once ready, read file data from in‑memory FS (or disk if writeToDisk)
→ optionally apply modifyResponseData callback → set headers (etag, cache‑control) → send response
• On middleware initialization: setupHooks attaches to compiler (invalid, done), sets up outputFileSystem, registers ready promise
• Instance methods (invalidate(), close(), waitUntilValid()) call compiler API and internal state
Architectural patterns & design principles
• Adapter/Middleware Pattern: abstracts framework differences, exposes a uniform Express‑style interface
• Observer/Event‑Driven: listens to Webpack Compiler lifecycle events to coordinate request handling
• Separation of Concerns: core request flow in middleware.js; utilities factored into small modules
• Pluggable Filesystem Abstraction: default in-memory (memfs) with optional disk writes