You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d2c90b4
Browse filesBrowse the repository at this point in the historyBrowse files
**Cipher Logger** is a lightweight, production-ready HTTP request logging library for Node.js. It captures every request in your app — **Express**, **Next.js**, and more frameworks on the way — with full control over which fields get logged.
26
+
**Cipher Logger** is a lightweight, production-ready HTTP request logging library for Node.js. It captures every request with adapters for **Express**, **Next.js**, **Fastify**, **Hono**, **NestJS**, and **Nuxt**, with full control over which fields get logged.
Full documentation — configuration reference, framework guides (Express, Next.js, and upcoming adapters), log schema, API reference, and architecture — lives on the docs site:
63
+
Full documentation — configuration reference, framework guides, log schema, API reference, and architecture — lives on the docs site:
CipherLogger is split into a framework-agnostic **core** and thin, per-framework **adapters**. This keeps the dependency footprint small — you only pull in the adapter for the framework you actually use — and keeps the logging logic itself easy to test in isolation.
3
+
CipherLogger is split into a framework-agnostic **core** and thin, per-framework **adapters**. Adapters ship as separate entry points so importing the core package does not load Express, Next.js, or other peers.
4
4
5
5
## Package layout
6
6
7
7
```text
8
8
cipher-logger/
9
9
├── src/
10
-
│ ├── core/ # Core — field config & log building
11
-
│ │ ├── logger.ts
12
-
│ │ ├── types.ts
13
-
│ │ ├── build-request-log.ts
14
-
│ │ └── create-cipher-logger.ts
15
-
│ ├── express/ # Express adapter
16
-
│ │ └── middleware.ts
17
-
│ ├── next/ # Next.js adapter
18
-
│ │ └── middleware.ts
19
-
│ └── index.ts # Public entry point
10
+
│ ├── core/ # Field config, Logger, createCipherLogger
11
+
│ ├── adapters/
12
+
│ │ ├── express/
13
+
│ │ ├── next/
14
+
│ │ ├── nuxt/
15
+
│ │ ├── fastify/
16
+
│ │ ├── nest/
17
+
│ │ └── hono/
18
+
│ ├── index.ts # Public core entry
19
+
│ ├── express.ts # Subpath: cipher-logger/express
20
+
│ ├── next.ts # Subpath: cipher-logger/next
21
+
│ └── … # Other adapter entries
22
+
└── dist/ # Built CJS + ESM + types
20
23
```
21
24
22
25
## Data flow
@@ -25,22 +28,33 @@ cipher-logger/
25
28
flowchart TB
26
29
A[fields config] --> B[buildRequestLog]
27
30
B --> C{Adapter}
28
-
C --> D[Express middleware]
31
+
C --> D[Express / Nest]
29
32
C --> E[Next.js middleware]
30
-
D --> F[res.finish → accurate status/duration]
31
-
E --> G[middleware execution → see timing caveat]
33
+
C --> F[withCipherLogger route handler]
34
+
C --> G[Fastify / Hono / Nuxt]
35
+
D --> H[res.finish → accurate status/duration]
36
+
F --> I[real Response status/duration]
37
+
E --> J[middleware timing caveat]
32
38
```
33
39
34
-
1.**Core** owns the `fields` configuration and `buildRequestLog`, which assembles a `RequestLog` object from raw request/response data and whatever optional fields are enabled.
35
-
2.**Adapters**are responsible only for extracting framework-specific data (headers, timing hooks, request/response objects) and handing it to core in a normalized shape.
36
-
3.Each adapter decides *when* logging happens — Express logs on `res.finish` (after the real response), while the Next.js adapter currently logs during middleware execution (see the [timing caveat](../guide/nextjs.md#timing-caveat)).
40
+
1.**Core** owns `fields` configuration and `buildRequestLog`.
41
+
2.**Adapters**extract framework-specific data and call `cipher.logRequest(...)`.
42
+
3.Convenience methods like `cipher.express()` lazy-load the matching `dist/<adapter>` chunk at call time so unused peers are never required.
37
43
38
44
## Why this split?
39
45
40
-
-**Small surface area per adapter.** Adding a new framework (Fastify, Hono, NestJS, Nuxt — see the [Roadmap](roadmap.md)) means writing a thin file that maps that framework's request lifecycle onto core, not reimplementing field logic.
41
-
-**Zero unnecessary dependencies.**`express` and `next` are optional peer dependencies — installing CipherLogger doesn't pull in either unless you import that adapter.
42
-
-**Testable core.**`buildRequestLog` and `Logger` have no framework dependencies, so they're covered by plain unit tests independent of any HTTP server.
43
-
44
-
## Public entry point
45
-
46
-
`src/index.ts` re-exports everything documented in the [API Reference](../reference/api.md): `createCipherLogger`, `Logger`, and every public type. Adapters are not imported eagerly — `cipher.express()` and `cipher.next()` are resolved lazily so that, for example, requiring `next` doesn't happen in a pure-Express project.
46
+
-**Small surface area per adapter.** Adding a framework means a thin adapter file plus a subpath entry.
47
+
-**Optional peers stay optional.**`require("cipher-logger")` / `import "cipher-logger"` does not load `next` or `express`.
48
+
-**Typed imports when you need them.** Prefer `import { createExpressMiddleware } from "cipher-logger/express"` for full framework types.
Today, the Next.js adapter logs during middleware execution, so `status` and `duration` don't reflect the final route response (full explanation in the [Next.js guide](../guide/nextjs.md#timing-caveat)). Route-handler wrappers that log the *actual* final response are planned, mirroring how the Express adapter already works via `res.finish`.
A restructure of `src/` into clearer `core/` and `adapters/` directories is planned, so that adding a new framework adapter is a self-contained addition rather than a change scattered across the package. Subpath exports (e.g. `cipher-logger/express`, `cipher-logger/next`) are also being considered, so importing one adapter doesn't pull in code for frameworks you don't use.
18
+
Core and adapters live under `src/core/` and `src/adapters/`. Subpath exports (`cipher-logger/express`, `cipher-logger/next`, …) keep peer framework code out of the main entry until you import (or call) that adapter.
23
19
24
20
## Contributing to the roadmap
25
21
26
-
Have a framework you'd like supported, or a field you think should be built in? Open an issue on [GitHub](https://github.com/cipherunits/CipherLogger/issues) — see the [Contributing](../index.md) section of the README for the process.
22
+
Have a framework you'd like supported, or a field you think should be built in? Open an issue on [GitHub](https://github.com/cipherunits/CipherLogger/issues).
Copy file name to clipboardExpand all lines: docs/faq.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ Not really — they solve different problems. Winston and Pino are general-purpo
6
6
7
7
## Why is `duration` wrong in my Next.js logs?
8
8
9
-
This is expected with the current Next.js adapter — see the [timing caveat](guide/nextjs.md#timing-caveat). Middleware runs before your route handler, so the adapter can only measure its own execution time, not the full response. A fix (route-handler wrappers) is on the [Roadmap](advanced/roadmap.md).
9
+
This is expected with `createNextMiddleware` / `cipher.next()`— see the [timing caveat](guide/nextjs.md#timing-caveat). Middleware runs before your route handler. Use [`withCipherLogger`](guide/nextjs.md#accurate-route-handler-logging)on App Router handlers for accurate status/duration.
10
10
11
11
## Can I use CipherLogger without Express or Next.js?
12
12
@@ -22,7 +22,7 @@ Each enabled field does a small amount of extra work per request (header read, q
22
22
23
23
## Is CommonJS supported, or only ESM?
24
24
25
-
Both. CipherLogger ships dual ESM/CJS builds, so `import` and `require` both work out of the box.
25
+
Both. CipherLogger ships dual ESM/CJS builds with an `exports` map, so `import` and `require` both resolve correctly — including subpaths like `cipher-logger/express`.
26
26
27
27
## Where do I report a bug or request a framework adapter?
Copy file name to clipboardExpand all lines: docs/getting-started/installation.md
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@
22
22
23
23
## Peer dependencies
24
24
25
-
CipherLogger only requires the framework you actually use — everything else stays out of your `node_modules`.
25
+
CipherLogger only requires the framework you actually use — everything else stays out of your `node_modules`. Import the matching subpath (for example `cipher-logger/express`) or call the lazy convenience method (`cipher.express()`).
26
26
27
27
=== "Express"
28
28
@@ -36,14 +36,20 @@ CipherLogger only requires the framework you actually use — everything else st
36
36
npm install next
37
37
```
38
38
39
+
=== "Fastify / Hono / Nest / Nuxt"
40
+
41
+
```bash
42
+
npm install fastify # or hono / @nestjs/common / nuxt
43
+
```
44
+
39
45
If you only use the framework-agnostic [`Logger`](../reference/api.md#logger) class, no peer dependency is required at all.
40
46
41
47
## Requirements
42
48
43
49
| Requirement | Version |
44
50
| ----------- | ------- |
45
51
| Node.js | 18 or later |
46
-
| TypeScript | 5.x (optional — CipherLogger ships its own `.d.ts` files) |
52
+
| TypeScript | 5.x or 6.x (optional — CipherLogger ships its own `.d.ts` files) |
47
53
| Module system | ESM and CommonJS both supported |
0 commit comments