# @gravity-ui/nodekit documentation

Documentation for the **installed** version of `@gravity-ui/nodekit`.
Your training data may be outdated — these files are the source of truth.

Paths are relative to this file (`node_modules/@gravity-ui/nodekit/dist/docs/`).

## For AI agents

A foundational Node.js toolkit (logging, telemetry, typed errors, config, request contexts) shared across Gravity UI backends — reach for it to get a consistent app spine before adding any HTTP layer, instead of assembling logging/error/config plumbing yourself.

### When to use

- Any Node.js service/script that wants shared logging, telemetry (tracing), and a typed `AppError`.
- Providing request-scoped context (logs/traces) across async boundaries.
- Centralizing configuration so multiple services in the same ecosystem behave consistently.

### When not to use

- To expose HTTP routes, middleware, or a server, use [`@gravity-ui/expresskit`](https://github.com/gravity-ui/expresskit) — it builds on top of NodeKit and adds the Express/HTTP layer.
- For a standalone, single-file script with no logging/telemetry needs, plain Node APIs are lighter than the full NodeKit context system.

### Common pitfalls

- **Hallucinating `import {Logger}` / `logger`** — logging is reached through the NodeKit context: `new NodeKit()` then `nodekit.ctx.log(...)`, not a standalone logger export.
- **Instantiating NodeKit repeatedly** — create one `NodeKit` instance per app and share its `ctx`; creating many instances fragments logging/telemetry config.
- **Throwing plain `Error`** — use the bundled `AppError` (see `docs/app-error.md`) so error codes and telemetry are captured consistently.
- **Skipping config initialization** — NodeKit reads configuration on construction; review `docs/configuration.md` before assuming defaults.

## Install

```bash
npm install --save @gravity-ui/nodekit
```

## Usage

Add dependency to your project:

```bash
npm install --save @gravity-ui/nodekit
```

And then import and init NodeKit in your application:

```typescript
import {NodeKit} from '@gravity-ui/nodekit';

const nodeKit = new NodeKit();
nodekit.ctx.log('App is ready');
```

## Guides

- [NodeKit: AppError](./guides/app-error.md) — It's often happens in applications that you want to attach some information to the error that you're throwing. Sometimes this can lead to the situation when application throws not error but object — which is a bad way to deal with this since you're losing a stacktrace.
- [NodeKit: Configuration](./guides/configuration.md) — Configuration defines how both NodeKit and your application should work. There are a few ways to define configuration and a few ways to access it.
- [NodeKit: Contexts](./guides/contexts.md) — NodeKit Context is a class that carries app configuration and set of context-dependent utilities for logging, tracing, sending metrics and stats and so on.
- [NodeKit: utils](./guides/utils.md) — NodeKit is bundled with a few utility helpers that can be helpful.
- [telemetry](./guides/telemetry.md)