@gravity-ui/expresskit

中文文档
3.4.0发布于 2026/11/02MITTypeScriptCommonJS近 30 天下载 3.6万

Express.js wrapper for NodeKit-based apps

原始使用文档
文档目录11 节
  1. Self telemetry
  2. CSP
  3. CSRF Protection
  4. Basic Configuration
  5. Configuration Options
  6. Usage
  7. Per-Route Configuration
  8. Caching Control
  9. Global configuration
  10. Per-route configuration
  11. Validation and Response Serialization

ExpressKit

ExpressKit is a lightweight express.js wrapper that integrates with NodeKit and provides some useful features like request logging, tracing support, async controllers & middleware and verbose routes description.

Installation:

npm install --save @gravity-ui/nodekit @gravity-ui/expresskit

Basic usage:

import {ExpressKit} from '@gravity-ui/expresskit';
import {NodeKit} from '@gravity-ui/nodekit';

const nodekit = new NodeKit();

const app = new ExpressKit(nodekit, {
  'GET /': (req, res) => {
    res.send('Hello World!');
  },
});

app.run();

Self telemetry

By default, self telemetry sends the original request URL. Applications with large or high-cardinality query strings can strip query parameters before sending stats:

const config: Partial<AppConfig> = {
  appTelemetryChEnableSelfStats: true,
  appTelemetryChSelfStatsStripQueryParams: true,
};

CSP

config.ts

import type {AppConfig} from '@gravity-ui/nodekit';
import {csp} from '@gravity-ui/expresskit';

const config: Partial<AppConfig> = {
    expressCspEnable: true,
    expressCspPresets: ({getDefaultPresets}) => {
        return getDefaultPresets({defaultNone: true}).concat([
            csp.inline(),
            {csp.directives.REPORT_TO: 'my-report-group'},
        ]);
    },
    expressCspReportTo: [
        {
            group: 'my-report-group',
            max_age: 30 * 60,
            endpoints: [{ url: 'https://cspreport.com/send'}],
            include_subdomains: true,
        }
    ]
}

export default config;

CSRF Protection

ExpressKit provides built-in Cross-Site Request Forgery (CSRF) protection to secure your applications against malicious cross-origin requests. The CSRF middleware automatically generates and validates tokens for state-changing HTTP requests.

Basic Configuration

To enable CSRF protection, configure the secret key in your config:

import type {AppConfig} from '@gravity-ui/nodekit';

const config: Partial<AppConfig> = {
  // ...
  appCsrfSecret: 'your-secret-key-here',
};

export default config;

Configuration Options

OptionTypeDefaultDescription
appCsrfSecretstring | string[]-Required. Secret key(s) for HMAC token generation. Multiple secrets allow for key rotation.
appCsrfLifetimenumber2592000 (30 days)Token lifetime in seconds. Set to 0 for no expiration.
appCsrfHeaderNamestring'x-csrf-token'HTTP header name for token validation.
appCsrfMethodsstring[]['POST', 'PUT', 'DELETE', 'PATCH']HTTP methods that require CSRF validation.

Usage

Once configured, CSRF protection is automatically applied to all routes with the specified HTTP methods:

import {ExpressKit, AuthPolicy} from '@gravity-ui/expresskit';
import {NodeKit} from '@gravity-ui/nodekit';

const nodekit = new NodeKit({
  config: {
    appCsrfSecret: 'your-secret-key',
    appAuthPolicy: AuthPolicy.required,

    // Ensure that your middleware sets user id to the originalContext, otherwise CSRF token generation will fail
    appAuthHandler: yourAuthHandler,
  },
});

const app = new ExpressKit(nodekit, {
  'GET /api/form': (req, res) => {
    // Token is available in request context
    res.json({csrfToken: req.originalContext.get('csrfToken')});
  },

  'POST /api/submit': (req, res) => {
    // This route automatically validates CSRF token
    res.json({message: 'Form submitted successfully'});
  },
});

Per-Route Configuration

You can disable CSRF protection for specific routes:

const app = new ExpressKit(nodekit, {
  'POST /api/webhook': {
    authPolicy: AuthPolicy.required,
    disableCsrf: true, // Disable CSRF for this route
    handler: (req, res) => {
      res.json({message: 'Webhook processed'});
    },
  },
});

Caching Control

By default, ExpressKit sets no-cache headers on all responses. You can control this behavior globally or per-route.

Global configuration

const config: Partial<AppConfig> = {
  expressEnableCaching: true, // Allow caching by default
};

Per-route configuration

const app = new ExpressKit(nodekit, {
  'GET /api/cached': {
    enableCaching: true, // Allow caching for this route
    handler: (req, res) => res.json({data: 'cacheable'}),
  },
  'GET /api/fresh': {
    enableCaching: false, // Force no-cache
    handler: (req, res) => res.json({data: 'always fresh'}),
  },
});

Route-level enableCaching overrides the global setting. The caching state is available in req.routeInfo.enableCaching.

Validation and Response Serialization

版本与发布记录

@gravity-ui/expresskit 共发布 42 个版本,首次发布于 2023/02/22;过去 12 个月发布了 12 个版本。

版本发布日期距今
3.4.0latest2026/11/0214 天前
3.3.02026/10/2720 天前
3.2.02026/09/142 个月前
3.1.32026/05/285 个月前
3.1.22026/05/185 个月前
3.1.12026/05/136 个月前

关于 @gravity-ui/expresskit 的常见问题

@gravity-ui/expresskit 是什么?

Express.js wrapper for NodeKit-based apps

如何安装 @gravity-ui/expresskit?

在项目目录运行 npm install @gravity-ui/expresskit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@gravity-ui/nodekit(^1.6.0 || ^2.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/expresskit 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gravity-ui/expresskit 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gravity-ui/expresskit 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gravity-ui/expresskit 可以商用吗?

@gravity-ui/expresskit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/expresskit 的下载量有多少?

根据 npm 官方下载统计,@gravity-ui/expresskit 在 2026/10/17 – 2026/11/15 这 30 天内被下载 36,040 次,日均约 1,201 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ui/expresskit 还在维护吗?

最新版本 3.4.0 发布于 2026/11/02(14 天前);至今共发布 42 个版本,其中过去 12 个月发布了 12 个;首次发布于 2023/02/22。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。