# @gravity-ui/nodekit

> Simple toolkit for your Node.js apps and scripts

Latest version **2.21.0** (published 2026-10-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @gravity-ui/nodekit
pnpm add @gravity-ui/nodekit
yarn add @gravity-ui/nodekit
bun add @gravity-ui/nodekit
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.21.0 |
| Published | 2026-10-30 |
| First published | 2023-02-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=20 |
| Dependencies | 13 |
| Unpacked size | 106.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14 |
| Author | Gravity UI Team |
| Maintainers | resure, amje, gravity-ui-bot |

## Links

- npm: https://www.npmjs.com/package/@gravity-ui/nodekit
- Repository: https://github.com/gravity-ui/nodekit
- Homepage: https://github.com/gravity-ui/nodekit#readme
- Issues: https://github.com/gravity-ui/nodekit/issues
- npm.io page: https://npm.io/package/@gravity-ui/nodekit

## Dependencies (13)

- [pino](https://npm.io/package/pino.md) ^10.3.1
- [dotenv](https://npm.io/package/dotenv.md) ^17.4.2
- [pino-pretty](https://npm.io/package/pino-pretty.md) ^13.1.3
- [@grpc/grpc-js](https://npm.io/package/@grpc/grpc-js.md) ^1.13.3
- [@opentelemetry/api](https://npm.io/package/@opentelemetry/api.md) ^1.9.1
- [@opentelemetry/api-logs](https://npm.io/package/@opentelemetry/api-logs.md) ^0.219.0
- [@opentelemetry/sdk-logs](https://npm.io/package/@opentelemetry/sdk-logs.md) ^0.219.0
- [@opentelemetry/sdk-node](https://npm.io/package/@opentelemetry/sdk-node.md) ^0.221.0
- [@opentelemetry/propagator-jaeger](https://npm.io/package/@opentelemetry/propagator-jaeger.md) ^2.7.1
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.41.1
- [@opentelemetry/exporter-trace-otlp-grpc](https://npm.io/package/@opentelemetry/exporter-trace-otlp-grpc.md) ^0.219.0
- [@opentelemetry/exporter-trace-otlp-http](https://npm.io/package/@opentelemetry/exporter-trace-otlp-http.md) ^0.219.0
- [@opentelemetry/exporter-trace-otlp-proto](https://npm.io/package/@opentelemetry/exporter-trace-otlp-proto.md) ^0.219.0

## Recent versions

- 2.21.0 (latest) — 2026-10-30
- 2.20.1 — 2026-10-18
- 2.20.0 — 2026-10-13
- 2.19.0 — 2026-10-12
- 2.18.1 — 2026-09-17
- 2.18.0 — 2026-08-27
- 2.17.0 — 2026-08-13
- 2.16.2 — 2026-07-30
- 2.16.1 — 2026-07-27
- 2.16.0 — 2026-07-14
- 2.15.0 — 2026-07-08
- 2.14.0 — 2026-06-23
- 2.13.0 — 2026-06-12
- 2.12.1 — 2026-05-27
- 2.12.0 — 2026-05-13
- … 37 more at https://npm.io/package/@gravity-ui/nodekit/versions

## README

# NodeKit

NodeKit is a simple toolkit for your Node.js apps, scripts and libraries. It provides functionality for logging, telemetry, configuration and error handling, so you can have familiar foundation in your different projects.

## Install

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

## Getting started

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');
```

## Documentation

See `docs/` directory for additional documentation:

- [`docs/configuration.md`](https://github.com/gravity-ui/nodekit/blob/main/docs/configuration.md) specifies how you can configure both nodekit itself and your nodekit-based applications
- [`docs/contexts.md`](https://github.com/gravity-ui/nodekit/blob/main/docs/contexts.md) describes concept of NodeKit contexts, logging and tracing
- [`docs/app-error.md`](https://github.com/gravity-ui/nodekit/blob/main/docs/app-error.md) contains description of useful custom error class they NodeKit provides for your applications
- [`docs/utils.md`](https://github.com/gravity-ui/nodekit/blob/main/docs/utils.md) lists some additional helper functions that are bundled with NodeKit

## Contributing

### Getting started

Grab a copies of NodeKit repository and example applications:

```bash
git clone git@github.com:gravity-ui/nodekit
git clone git@github.com:gravity-ui/nodekit-examples
```

Link your nodekit to npm and start a compiler:

```bash
cd nodekit && npm link && npm run dev
```

Then, in another terminal, go to examples, open the one that you're interested in, link your nodekit there, then start the app:

```bash
cd nodekit-examples/basic-app && npm i && npm link @gravity-ui/nodekit
npm run dev
```

At this point you can make changes both to NodeKit and demo app, and see results in real time.

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.

## 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.

## Documentation for AI agents

Agent-readable documentation for the installed version is located in `node_modules/@gravity-ui/nodekit/dist/docs/INDEX.md`.

---
_Source: https://npm.io/package/@gravity-ui/nodekit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._