@gqlts/runtime

中文文档
3.4.2发布于 2026/06/01MITTypeScriptESM + CJS近 30 天下载 4498

Gqlts runtime client

原始使用文档
文档目录10 节
  1. Type safe Graphql query builder
  2. @gqlts/cli
  3. @gqlts/runtime
  4. Documentation
  5. Features
  6. Example usage
  7. Packages
  8. Development
  9. Releases
  10. License




Type safe Graphql query builder

Write Graphql queries with type validation and auto-completion with batteries included



CI RELEASE

@gqlts/cli

Latest NPM version Beta NPM version Downloads UNPKG

@gqlts/runtime

Latest NPM version Beta NPM version Downloads UNPKG

This package is forked version from genql

It has been updated, fixed few bugs, actively adding features and updated dependencies and codebase to the latest packages

Read the quick start guide to generate a client locally.

Documentation

  • Docs site: quick start, examples, feature coverage, and usage guides.
  • Development guide: local setup, release workflow, and contributor commands.
  • Architecture: package map, generation flow, runtime flow, and release diagram.
  • Testing: test matrix, change checklist, and full demo procedure.
  • API flow: where API behavior coverage lives today.

Features

  • Type completion
  • Type validation
  • Easily fetch all fields in a type
  • Support subscription ( ws, graphql-ws, observable, etc )
  • Built in file upload support
  • Graphql Client built in
  • Works with any client
  • Works in node and the browser
  • Built in Axios Client, and exported to extend with interceptors.
  • Client Operation support for Axios configuration, such as headers, timeout, cancelToken, abortSignal, etc.
  • Support batching queries
  • Consistent response format { data, errors, extensions }

Find more server-client examples in the examples repo You will find multiple examples with different tools of building schema, query, mutation, websocket subscriptions and more.

Example usage

First generate your client executing

npm install -D @gqlts/cli # cli to generate the client code
npm install @gqlts/runtime graphql # runtime dependencies
npx gqlts --schema ./schema.graphql --output ./generated

Use the equivalent commands for your package manager: pnpm dlx gqlts, yarn gqlts, or bunx gqlts all work too.

Then you can use your client as follows

import { createClient, everything } from './generated';
const client = createClient();

client
  .query({
    countries: {
      name: true,
      code: true,
      nestedField: {
        ...everything, // same as __scalar: true
      },
    },
  })
  .then(console.log);

The code above will fetch the graphql query below

query {
  countries {
    name
    code
    nestedField {
      scalarField1
      scalarField2
    }
  }
}

Packages

This repo contains two published packages:

  • @gqlts/cli: reads a GraphQL schema and generates the typed client files.
  • @gqlts/runtime: powers generated clients at runtime for queries, mutations, subscriptions, batching, uploads, and custom fetchers.

Generated clients normally contain:

  • schema.graphql: schema snapshot used for generation.
  • schema.ts: generated schema, request, response, and guard types.
  • index.js / index.esm.js: generated CommonJS and ESM client entrypoints.
  • index.d.ts: generated public TypeScript declarations.
  • types.cjs.js / types.esm.js: compressed runtime type map.
  • guards.cjs.js / guards.esm.js: generated runtime type guards.

Development

Install from the repo root with Bun:

bun ci

Common commands:

bun run buildall
bun run test
bun run typecheck
bun run --cwd website build
./demo-apps/build-and-test.sh

Run ./demo-apps/build-and-test.sh before pushing generator, runtime, upload, subscription, SDK, or Next.js changes. It runs the backend demo, SDK generation, standalone browser bundle, Next.js dev and production tests, and integration tests.

More details are in DEVELOPMENT.md, docs/architecture.md, and docs/testing.md.

Releases

Gqlts uses semantic-release for coordinated releases of @gqlts/runtime and @gqlts/cli.

  • develop and beta publish beta prereleases like x.y.z-beta.n to npm beta.
  • alpha publishes alpha prereleases like x.y.z-alpha.n to npm alpha.
  • master and main publish stable releases like x.y.z to npm latest.
  • one semantic-release run computes the version for the whole repo.
  • release:stamp writes that exact version into the root, runtime, and CLI manifests.
  • release:publish publishes @gqlts/runtime first, then @gqlts/cli, both at the same version.

Useful commands:

bun run release:verify
bun run release:dry
bun run release:local 3.5.0-beta.1 --dry-run --tag beta

Normal flow:

  1. Use conventional commits. feat, fix, perf, refactor, and revert create releases; docs, test, ci, build, style, and chore do not.
  2. Merge to develop or beta to publish the next beta.
  3. Merge to alpha to publish the next alpha.
  4. Merge to master or main to publish the next stable release.

The release workflow validates first, then lets semantic-release stamp, build, tag, create the GitHub release, and publish both npm packages from the same computed version.


License

This is licensed under an MIT License. See details

版本与发布记录

@gqlts/runtime 共发布 503 个版本,首次发布于 2022/05/29;过去 12 个月发布了 7 个版本。

版本发布日期距今
3.4.2latest2026/06/015 个月前
3.5.0-beta.1beta2026/06/015 个月前
3.4.2-beta.12026/06/015 个月前
3.4.12026/05/315 个月前
3.4.1-beta.12026/05/315 个月前
3.4.02026/04/236 个月前

其他发布通道:develop → 3.2.11-beta.2,beta → 3.5.0-beta.1。

关于 @gqlts/runtime 的常见问题

@gqlts/runtime 是什么?

Gqlts runtime client

如何安装 @gqlts/runtime?

在项目目录运行 npm install @gqlts/runtime,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:graphql(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gqlts/runtime 支持 TypeScript 吗?

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

@gqlts/runtime 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gqlts/runtime 可以商用吗?

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

@gqlts/runtime 的下载量有多少?

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

@gqlts/runtime 还在维护吗?

最新版本 3.4.2 发布于 2026/06/01(5 个月前);至今共发布 503 个版本,其中过去 12 个月发布了 7 个;首次发布于 2022/05/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。