@vsfedorenko/next-logger 0.1.0 → 0.2.1

package/README.md

@@ -1,146 +1,96 @@
 # @vsfedorenko/next-logger
 
+[![npm version](https://img.shields.io/npm/v/@vsfedorenko/next-logger.svg)](https://www.npmjs.com/package/@vsfedorenko/next-logger)
+[![CI](https://github.com/vsfedorenko/next-logger/actions/workflows/ci.yml/badge.svg)](https://github.com/vsfedorenko/next-logger/actions/workflows/ci.yml)
+
+> Languages: **English** | [Русский](README.ru.md) | [中文](README.zh.md)
+
 A **universal logging kit for Next.js**.
 
-Monkeypatches Next.js' internal logger (`next/dist/build/output/log`) **and**
-the global `console.*` so all diagnostic output flows through a single
-level-controllable sink — [consola](https://github.com/unjs/consola) by default,
-with pluggable reporters for **Sentry**, structured **JSON**, and more — without
-a custom Next.js server.
+Wraps the global `console.*` — the same sink Next.js' own internal logger
+funnels through — so all diagnostic output flows through a single
+level-controllable [consola](https://github.com/unjs/consola) instance, with
+pluggable reporters for structured **JSON** and more. No custom server, no
+module monkey-patching (which is unreachable under Turbopack anyway).
 
 Inspired by [`sainsburys-tech/next-logger`](https://github.com/sainsburys-tech/next-logger),
 which does the same with [pino](https://getpino.io). This package swaps pino
-for consola as the default backend and adds a reporter API so logs can be
-fanned out to any integration (Sentry breadcrumbs, JSON aggregators, …).
+for consola and delivers configuration through an idiomatic `withLogger()`
+config wrapper.
 
 ## Install
 
 ```sh
-bun add @vsfedorenko/next-logger consola
-# or
 npm install @vsfedorenko/next-logger consola
+# or
+bun add @vsfedorenko/next-logger consola
 ```
 
 `consola` is a peer dependency — install it alongside this package.
 
-## Usage
+## Quick start
 
-### Option A — Instrumentation hook (recommended)
-
-```ts
-// instrumentation.ts (project root)
-export async function register() {
-  if (process.env.NEXT_RUNTIME === "nodejs") {
-    await import("@vsfedorenko/next-logger");
-  }
-}
-```
+Two steps.
 
-The default import applies both patches: Next.js' logger **and** the global
-`console.*`.
+**1. Wrap your Next.js config** (`next.config.ts`):
 
-### Option B — `-r` preload
+```ts
+import { withLogger } from "@vsfedorenko/next-logger";
 
-```sh
-node -r @vsfedorenko/next-logger server.js
+export default withLogger({ consola: { level: 4 } })({
+  // ...your other next config
+});
 ```
 
-### Patch Next only (leave `console` untouched)
+**2. Call `init()` from instrumentation** (`instrumentation.ts`, project root):
 
 ```ts
-// instrumentation.ts
 export async function register() {
   if (process.env.NEXT_RUNTIME === "nodejs") {
-    await import("@vsfedorenko/next-logger/presets/next-only");
+    const { init } = await import("@vsfedorenko/next-logger");
+    init();
   }
 }
 ```
 
-Useful when you want Next's internal logs routed through consola but prefer
-native `console.*` formatting (e.g. in development).
+Done. Every `console.*` call on the server now flows through consola. Next.js'
+own logs (build output, route compilation, etc.) are captured too — they share
+the same `console.*` sink.
 
-### Browser / Client Components
-
-The main entry (`@vsfedorenko/next-logger`) imports the patch modules, which
-depend on `require.cache` and `lilconfig` — neither exists in a browser bundle.
-For Client Components or any browser-side code, use the
-**`@vsfedorenko/next-logger/browser`** subpath:
-
-```ts
-"use client";
-import { logger } from "@vsfedorenko/next-logger/browser";
-
-export function MyComponent() {
-  logger.info("rendered");
-  logger.warn("deprecation notice");
-  return <div>…</div>;
-}
-```
-
-This entry builds a consola instance from env-driven defaults (same level
-resolution: `LOG_LEVEL` → `NEXT_PUBLIC_LOG_LEVEL` → `3`), without the
-server-side patching machinery. For build-time-inlined levels visible in the
-browser bundle, use `NEXT_PUBLIC_LOG_LEVEL`.
+> A runnable example app lives in [`examples/basic/`](examples/basic/).
 
 ## Configuration
 
-Optional config file (discovered from cwd upward via
-[lilconfig](https://github.com/antonk52/lilconfig)). Supported filenames:
-
-- `next-logger.config.ts` / `next-logger.config.js` / `next-logger.config.cjs`
-- `.next-loggerrc.ts` / `.next-loggerrc.js` / `.next-loggerrc.cjs`
-- `.next-loggerrc` (JSON)
-- `.next-loggerrc.json`
-- `next-logger` key in `package.json`
-
-**TypeScript configs** (`.ts`) are loaded via [jiti](https://github.com/unjs/jiti).
-Install it as an optional peer dependency:
-
-```sh
-bun add -d jiti   # or: npm install -D jiti
-```
-
-### Custom consola instance
-
-```ts
-// next-logger.config.ts
-import { createConsola } from "consola";
-
-export default {
-  consola: createConsola({ level: 4 }),
-};
-```
-
-### Partial options (merged with defaults)
+`withLogger(options)` serialises `options` into the `NEXT_LOGGER_CONFIG`
+environment variable via Next.js' validated `env` config key — inlined at
+build time, read back at runtime. No "Unrecognized key" warning, works under
+both webpack and Turbopack.
 
 ```ts
-import type { ConsolaOptions } from "consola";
-
-export default {
-  consola: { level: 4, formatOptions: { date: false } } satisfies Partial<ConsolaOptions>,
-};
+withLogger({
+  consola: {
+    level: 4,                          // debug
+    formatOptions: { date: false },    // consola format options
+  },
+})
 ```
 
-### Factory (receives the library defaults)
+Only serialisable consola options are supported (`level`, `formatOptions`, …).
 
-```ts
-import type { ConsolaOptions } from "consola";
-import { createConsola } from "consola";
+### Skip console patching
 
-export default {
-  consola: (defaults: Partial<ConsolaOptions>) =>
-    createConsola({ ...defaults, level: 5 }),
-};
-```
+`init({ console: false })` builds the logger without wrapping `console.*`.
+Use this if you want the configured consola instance (via `getLogger()`) for
+manual logging but prefer to leave the global `console` untouched.
 
 ## Log level
 
-Without a config file, the level resolves from (in order):
-
-1. `LOG_LEVEL` (numeric or named)
-2. `NEXT_PUBLIC_LOG_LEVEL` (numeric or named)
+The level resolves in order:
 
-Falling back to `3` (info).
+1. `consola.level` from `withLogger`
+2. `LOG_LEVEL` (numeric or named)
+3. `NEXT_PUBLIC_LOG_LEVEL` (numeric or named)
+4. `3` (info) — default
 
 Named levels: `silent` (-∞), `fatal` (0), `error` (0), `warn` (1),
 `log` (2), `info` (3), `success` (3), `debug` (4), `trace` (5), `verbose` (∞).
@@ -165,7 +115,7 @@ Newline-delimited JSON to stdout (errors → stderr), suitable for structured-lo
 aggregators (Loki, Datadog, CloudWatch, Elasticsearch). Best for production.
 
 ```json
-{"level":"error","type":"error","tag":"next.js","msg":"failed to compile","date":"2026-07-11T13:43:10.712Z"}
+{"level":"info","type":"log","tag":"console","msg":"API /api/hello hit","date":"2026-07-12T10:00:00.000Z"}
 ```
 
 Each line contains:
@@ -174,54 +124,83 @@ Each line contains:
 |---------|------------------------------------------------------------------------------|
 | `level` | Named level (`error`/`warn`/`info`/`debug`/`trace`)                          |
 | `type`  | Consola log type (e.g. `error`, `warn`, `info`, `success`, `ready`, `event`) |
-| `tag`   | The consola tag (`next.js`, `console`, `app`, …)                             |
+| `tag`   | The consola tag (`next.js`, `console`, …)                                    |
 | `msg`   | The message string (multi-arg strings joined with space)                     |
-| `date`  | ISO 8601 timestamp                                                           |
+| `date`  | ISO 8601 timestamp                                                            |
 | `args`  | Additional structured arguments (omitted when none)                          |
 
 Errors are serialised as `{ name, message, stack }`. Circular references become
 `[Circular]`. BigInts become strings.
 
-Only applies to the server entry (`@vsfedorenko/next-logger`) — the browser
-entry always uses consola's built-in browser reporter. A custom consola instance
-from a config file bypasses format selection entirely.
+## Browser / Client Components
+
+The server entry patches `console.*`, which only makes sense in Node.js. For
+Client Components or any browser-side code, use the
+**`@vsfedorenko/next-logger/browser`** subpath:
+
+```ts
+"use client";
+import { logger } from "@vsfedorenko/next-logger/browser";
+
+export function MyComponent() {
+  logger.info("rendered");
+  logger.warn("deprecation notice");
+  return <div>…</div>;
+}
+```
+
+This entry builds a consola instance from env-driven defaults (same level
+resolution: `LOG_LEVEL` → `NEXT_PUBLIC_LOG_LEVEL` → `3`), without any
+server-side patching. For build-time-inlined levels visible in the browser
+bundle, use `NEXT_PUBLIC_LOG_LEVEL`.
 
 ## How it works
 
-1. **Next.js logger patch** (`patches/next.ts`) — replaces the methods exported
-   by `next/dist/build/output/log` (`wait`, `error`, `warn`, `ready`, `info`,
-   `event`, `trace`) with bound consola methods tagged `next.js`. Preserves the
-   critical Next 13+ workaround: since Next defines these exports as
-   non-configurable accessors, the patch replaces `require.cache[...].exports`
-   with a shallow copy, then redefines each method on the copy.
+1. **Config wrapper** (`withLogger`, build time) — serialises logger options
+   into `NEXT_LOGGER_CONFIG` via Next's `env` key. Next inlines this at build
+   time, so the runtime reads it as `process.env.NEXT_LOGGER_CONFIG` with no
+   file-system or Next.js-internal imports.
 
-2. **Console patch** (`patches/console.ts`) — overwrites
-   `console.{log,debug,info,warn,error}` with bound consola methods tagged
-   `console`. `log` and `info` both map to consola `info`.
+2. **Console-sink patch** (`patches/console.ts`, runtime) — wraps
+   `console.{log,debug,info,warn,error}` so every call routes through the
+   shared consola instance. `log` and `info` both map to consola `info`.
 
-Both patches share a single consola instance built by `logger.ts`, so the log
-level is controllable from one place.
+3. **Next-log classifier** (`patches/next.ts`, runtime) — inspects each
+   `console.*` call: if the first argument carries a Next.js marker symbol
+   (`▲`, `✓`, `⚠`, `●`, `✗`, …) the line is tagged `next.js`; otherwise it's
+   tagged `console`. This works under Turbopack, where the old
+   `require.cache`-based monkeypatch is dead (Next's logger lives in a separate
+   bundled instance).
 
 ### Empty-message skipping
 
-Both patches skip printing when a message is **empty** — no arguments, or only
-`undefined`/`null`/`""` (values that carry no diagnostic value and would render
-as a bare tag line under consola). This mirrors Next.js' own behaviour, where
-`prefixedLog` drops the prefix when the message is empty.
+The patch skips printing when a message is **empty** — no arguments, or only
+`undefined`/`null`/`""` (values that carry no diagnostic value and would
+render as a bare tag line under consola). This mirrors Next.js' own behaviour,
+where `prefixedLog` drops the prefix when the message is empty.
 
 Falsy-but-present values (`0`, `false`) are **not** considered empty and are
 printed normally.
 
+### Turbopack note
+
+Next.js' **startup banner** (`▲ Next.js`, `✓ Ready`, …) prints *before* the
+instrumentation hook runs, so those specific lines are not captured. Any log
+emitted after boot — route compilation, request-time output, your own
+`console.*` calls — flows through the patch normally.
+
 ## Differences from `sainsburys-tech/next-logger`
 
 | Concern           | sainsburys-tech (pino)                        | this package (consola)                          |
 |-------------------|-----------------------------------------------|-------------------------------------------------|
 | Backend           | pino (JSON to stdout)                         | consola (pretty by default)                     |
+| Config delivery   | `next-logger.config.js` + preload             | `withLogger()` wrapper (idiomatic, type-safe)   |
+| Interception      | patches `next/dist/build/output/log`          | wraps `console.*` sink (Turbopack-safe)         |
 | Arg normalisation | custom `hooks.logMethod`                      | not needed — consola handles console-style args |
 | Child logger      | `logger.child({ name })`                      | `consola.withTag(tag)`                          |
-| Custom backend    | any logger with `.child()` (pino, winston, …) | consola instances / options only                |
 | `trace` level     | falls back to `debug` (Winston has no trace)  | native — consola has `trace`                    |
 | Default level     | hardcoded `debug`                             | env-driven (`LOG_LEVEL`)                        |
+| Turbopack         | `require.cache` patch breaks                  | console-sink — works                            |
 | Language          | plain JS (CommonJS)                           | TypeScript (CJS output)                         |
 
 ## License

package/README.ru.md

@@ -0,0 +1,210 @@
+# @vsfedorenko/next-logger
+
+[![npm version](https://img.shields.io/npm/v/@vsfedorenko/next-logger.svg)](https://www.npmjs.com/package/@vsfedorenko/next-logger)
+[![CI](https://github.com/vsfedorenko/next-logger/actions/workflows/ci.yml/badge.svg)](https://github.com/vsfedorenko/next-logger/actions/workflows/ci.yml)
+
+> Языки: [English](README.md) | **Русский** | [中文](README.zh.md)
+
+**Универсальный набор для логирования в Next.js.**
+
+Оборачивает глобальный `console.*` — тот же приёмник, через который проходит
+внутренний логгер Next.js — так что весь диагностический вывод идёт через единый
+управляемый по уровню экземпляр [consola](https://github.com/unjs/consola), с
+подключаемыми репортерами для структурированного **JSON** и др. Без кастомного
+сервера, без monkey-патчинга модулей (который под Turbopack всё равно недостижим).
+
+Вдохновлено [`sainsburys-tech/next-logger`](https://github.com/sainsburys-tech/next-logger),
+который делает то же самое на [pino](https://getpino.io). Этот пакет заменяет
+pino на consola и доставляет конфигурацию через идиоматическую обёртку
+`withLogger()`.
+
+## Установка
+
+```sh
+npm install @vsfedorenko/next-logger consola
+# или
+bun add @vsfedorenko/next-logger consola
+```
+
+`consola` — peer-зависимость, устанавливайте её вместе с пакетом.
+
+## Быстрый старт
+
+Два шага.
+
+**1. Оберните конфиг Next.js** (`next.config.ts`):
+
+```ts
+import { withLogger } from "@vsfedorenko/next-logger";
+
+export default withLogger({ consola: { level: 4 } })({
+  // ...остальной конфиг next
+});
+```
+
+**2. Вызовите `init()` из instrumentation** (`instrumentation.ts`, корень проекта):
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { init } = await import("@vsfedorenko/next-logger");
+    init();
+  }
+}
+```
+
+Готово. Каждый вызов `console.*` на сервере теперь проходит через consola.
+Собственные логи Next.js (вывод сборки, компиляция роутов и т. д.) тоже
+перехватываются — они используют тот же приёмник `console.*`.
+
+> Рабочий пример приложения — в [`examples/basic/`](examples/basic/).
+
+## Конфигурация
+
+`withLogger(options)` сериализует `options` в переменную окружения
+`NEXT_LOGGER_CONFIG` через валидируемый конфиг-ключ `env` в Next.js —
+встраивается на этапе сборки, считывается в рантайме. Без предупреждения
+«Unrecognized key», работает и под webpack, и под Turbopack.
+
+```ts
+withLogger({
+  consola: {
+    level: 4,                          // debug
+    formatOptions: { date: false },    // опции форматирования consola
+  },
+})
+```
+
+Поддерживаются только сериализуемые опции consola (`level`, `formatOptions`, …).
+
+### Пропустить патчинг консоли
+
+`init({ console: false })` создаёт логгер без обёртки `console.*`. Используйте,
+если вам нужен настроенный экземпляр consola (через `getLogger()`) для ручного
+логирования, но вы предпочитаете не трогать глобальный `console`.
+
+## Уровень логирования
+
+Уровень разрешается по порядку:
+
+1. `consola.level` из `withLogger`
+2. `LOG_LEVEL` (число или имя)
+3. `NEXT_PUBLIC_LOG_LEVEL` (число или имя)
+4. `3` (info) — по умолчанию
+
+Именованные уровни: `silent` (-∞), `fatal` (0), `error` (0), `warn` (1),
+`log` (2), `info` (3), `success` (3), `debug` (4), `trace` (5), `verbose` (∞).
+
+## Формат логов
+
+Формат серверного вывода задаётся переменной окружения:
+
+1. `LOG_FORMAT` (`text` или `json`)
+2. `NEXT_PUBLIC_LOG_FORMAT` (те же значения)
+
+По умолчанию `text` (стандартный «pretty»-репортер consola).
+
+### `text` (по умолчанию)
+
+Человекочитаемый, с цветами в TTY и временными метками — встроенный репортер
+consola. Подходит для локальной разработки.
+
+### `json`
+
+Построчный JSON в stdout (ошибки → stderr), подходит для агрегаторов
+структурированных логов (Loki, Datadog, CloudWatch, Elasticsearch). Подходит для
+production.
+
+```json
+{"level":"info","type":"log","tag":"console","msg":"API /api/hello hit","date":"2026-07-12T10:00:00.000Z"}
+```
+
+Каждая строка содержит:
+
+| Поле   | Описание                                                                      |
+|--------|-------------------------------------------------------------------------------|
+| `level`| Именованный уровень (`error`/`warn`/`info`/`debug`/`trace`)                   |
+| `type` | Тип лога consola (`error`, `warn`, `info`, `success`, `ready`, `event` и т.д.)|
+| `tag`  | Тег consola (`next.js`, `console`, …)                                         |
+| `msg`  | Строка сообщения (строковые аргументы объединяются пробелом)                  |
+| `date` | ISO 8601 временная метка                                                       |
+| `args` | Дополнительные структурированные аргументы (опускается, если их нет)          |
+
+Ошибки сериализуются как `{ name, message, stack }`. Циклические ссылки
+становятся `[Circular]`. BigInt преобразуются в строки.
+
+## Браузер / Client Components
+
+Серверный entrypoint патчит `console.*`, что имеет смысл только в Node.js. Для
+Client Components или любого браузерного кода используйте подпуть
+**`@vsfedorenko/next-logger/browser`**:
+
+```ts
+"use client";
+import { logger } from "@vsfedorenko/next-logger/browser";
+
+export function MyComponent() {
+  logger.info("отрендерено");
+  logger.warn("устаревший API");
+  return <div>…</div>;
+}
+```
+
+Этот entrypoint создаёт экземпляр consola из значений по умолчанию, управляемых
+переменными окружения (то же разрешение уровня: `LOG_LEVEL` →
+`NEXT_PUBLIC_LOG_LEVEL` → `3`), без серверных механизмов патчинга. Для значений,
+встраиваемых на этапе сборки (видимых в браузерном бандле), используйте
+`NEXT_PUBLIC_LOG_LEVEL`.
+
+## Как это работает
+
+1. **Обёртка конфига** (`withLogger`, время сборки) — сериализует опции логгера
+в `NEXT_LOGGER_CONFIG` через ключ `env` в Next. Next встраивает это на этапе
+сборки, поэтому рантайм читает значение как `process.env.NEXT_LOGGER_CONFIG`
+   без файловых или внутренних импортов Next.js.
+
+2. **Патч приёмника консоли** (`patches/console.ts`, рантайм) — обёртывает
+   `console.{log,debug,info,warn,error}`, так что каждый вызов проходит через
+   общий экземпляр consola. `log` и `info` оба мапятся в consola `info`.
+
+3. **Классификатор логов Next** (`patches/next.ts`, рантайм) — проверяет каждый
+   вызов `console.*`: если первый аргумент несёт символ-маркер Next.js
+   (`▲`, `✓`, `⚠`, `●`, `✗`, …), строка тегируется `next.js`; иначе — `console`.
+   Это работает под Turbopack, где старый monkey-патч через `require.cache`
+   мёртв (логгер Next живёт в отдельном бандле).
+
+### Пропуск пустых сообщений
+
+Патч пропускает печать, когда сообщение **пустое** — нет аргументов или только
+`undefined`/`null`/`""` (значения без диагностической ценности, которые под
+consola отрендерились бы как строка с тегом без полезной нагрузки). Это
+повторяет поведение самого Next.js, где `prefixedLog` опускает префикс при пустом
+сообщении.
+
+Ложные, но присутствующие значения (`0`, `false`) **не** считаются пустыми и
+печатаются как обычно.
+
+### Замечание про Turbopack
+
+Стартовый баннер Next.js (**`▲ Next.js`**, `✓ Ready`, …) печатается *до* того,
+как срабатывает instrumentation-хук, поэтому эти конкретные строки не
+перехватываются. Любой лог после загрузки — компиляция роутов, вывод во время
+запроса, ваши собственные вызовы `console.*` — проходит через патч как обычно.
+
+## Отличия от `sainsburys-tech/next-logger`
+
+| Аспект             | sainsburys-tech (pino)                        | этот пакет (consola)                            |
+|--------------------|-----------------------------------------------|-------------------------------------------------|
+| Бэкенд             | pino (JSON в stdout)                          | consola («pretty» по умолчанию)                 |
+| Доставка конфига   | `next-logger.config.js` + preload             | обёртка `withLogger()` (идиоматично, типобезопасно) |
+| Перехват           | патчит `next/dist/build/output/log`           | обёртка `console.*` (Turbopack-safe)            |
+| Нормализация арг.  | кастомный `hooks.logMethod`                   | не нужна — consola сам работает с console-арг.  |
+| Дочерний логгер    | `logger.child({ name })`                      | `consola.withTag(tag)`                          |
+| Уровень `trace`    | fallback на `debug` (в Winston нет trace)     | нативный — в consola есть `trace`               |
+| Уровень по умолч.  | захардкожен `debug`                           | из env (`LOG_LEVEL`)                            |
+| Turbopack          | патч `require.cache` ломается                 | console-sink — работает                         |
+| Язык               | обычный JS (CommonJS)                         | TypeScript (вывод CJS)                          |
+
+## Лицензия
+
+MIT