Architecture
Last updated
This page shows, in one overview diagram, how the layers of node-image-server relate and what each one owns.
System Overview
graph TB
Client[Client] --> Worker[Cloudflare Worker · worker/index.js]
Client --> Nginx[Nginx · config/nginx/nodejs.conf]
Worker --> Nginx
Nginx -->|/c/img/| App[Express cluster · app/app.ts]
Nginx -->|/upload/ · /del/ · /| App
App --> MW[Middlewares · app/src/middlewares]
MW --> Router[Router · app/src/router]
Router --> GET[GetFromPath · sharp]
Router --> POST[PostToPath · multer]
Router --> DEL[DeleteFromPath]
GET --> Upload[(storage/image/upload)]
GET --> Cache[(storage/image/cache)]
POST --> Upload
DEL --> Trash[(upload/.trash/YYYY-MM-DD)]- graph TB
- Client[Client] --> Worker[Cloudflare Worker · worker/index.js]
- Client --> Nginx[Nginx · config/nginx/nodejs.conf]
- Worker --> Nginx
- Nginx -->|/c/img/| App[Express cluster · app/app.ts]
- Nginx -->|/upload/ · /del/ · /| App
- App --> MW[Middlewares · app/src/middlewares]
- MW --> Router[Router · app/src/router]
- Router --> GET[GetFromPath · sharp]
- Router --> POST[PostToPath · multer]
- Router --> DEL[DeleteFromPath]
- GET --> Upload[(storage/image/upload)]
- GET --> Cache[(storage/image/cache)]
- POST --> Upload
- DEL --> Trash[(upload/.trash/YYYY-MM-DD)]
Layers
| Layer | Location | Responsibility |
|---|---|---|
| CDN | worker/index.js | Caches for 7 days keyed on URL plus query string; forwards to the origin on a miss |
| Reverse proxy | config/nginx/nodejs.conf | proxy_cache for /c/img/, security headers, dotfile denial, HTTP method and upload size limits |
| Process management | app/app.json, app/app.ts | PM2 loads via ts-node; the primary forks workers and respawns them on exit |
| Middleware | app/src/middlewares/ | Parsing, CORS, request logging, HTML minification, dropping requests without User-Agent |
| Routing | app/src/router/ | Dispatches by HTTP method to the GET / POST / DELETE sub-routers |
| Handlers | GetFromPath, PostToPath, DeleteFromPath | Conversion and caching, upload, moving to trash |
| Storage | app/storage/image/ | upload/ originals, cache/ conversions, upload/.trash/ deleted items |
Cross-Cutting Principles
| Principle | Implementation |
|---|---|
| Process once | Conversions are written as cache files, and the edge layers cache on top |
| Never hard-delete | Deletion always renameSyncs into today's trash |
| Never upscale | Every size parameter is capped at the original dimensions |
Where It Fits
node-image-server is built on sharp, the libvips-based Node.js image processing library, and wraps it in an HTTP image server with its own storage. unjs/ipx is also a sharp-based image optimizer: it serves a directory or a list of allowed domains and puts modifiers in the URL path (
/w_512,f_webp/...). jimmynicol/image-resizer is an Express app that sits as a CDN custom origin and pulls originals from sources such as S3. node-image-server keeps originals on its own disk instead: clients upload through POST /upload, read variants through query parameters on GET /c/img, and delete into a dated trash, while each variant is written once as a cache file behind the shipped Nginx proxy_cache and Cloudflare Worker configs.Further Reading
- Per-module flows and sequence diagrams: doc/architecture.md
- Cache keys and invalidation: Caching Layers
- Read path: Image Pipeline