# api-typings: the TypeScript definitions for WeChat Mini Program APIs

> An official type definition package for the WeChat Mini Program runtime, generated from the API documentation so that wx calls are typed, shipped both as miniprogram-api-typings and through DefinitelyTyped, with a strict rule that API definition pull requests are not accepted.

**wechat-miniprogram/api-typings** — Type definitions for APIs of Wechat Mini Program in TypeScript

- Repository: https://github.com/wechat-miniprogram/api-typings
- Stars: 803 · Forks: 116
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/wechat-miniprogram-api-typings

## The API file is generated, which changes who owns it

The contribution section of the documentation is the most important paragraph in the repository, because it defines the division of ownership.

The API definition file, `lib.wx.api.d.ts`, is generated automatically together with the documentation. If you find an error in an API definition, the instruction is to open an issue. Pull requests about the API will not be accepted.

That single rule determines how you should use this repository. It is not a place to fix a wrong type for `wx.request` or to add an overload, because your change would be overwritten by the next generation run. It is a place to fix the hand written parts: the `Page` and `Component` interfaces and similar platform globals, where the project explicitly welcomes pull requests and issues.

The reasoning behind the rule is sound and worth stating, because it is a pattern more and more platform type packages follow. The API surface is owned by the platform vendor, the platform publishes documentation, and the type definitions are a mechanical projection of that documentation. Hand edits to the projection create a divergence between the docs and the types, which is worse than a known-wrong type that will be fixed upstream.

So the practical shape of the project is: generated types for the API surface, maintained types for the framework globals, and an issue tracker for reporting where the generated file is wrong.

## Two npm routes, and the trap of installing both

The package is published twice, and the documentation explains both routes.

As a standalone package:

```bash
npm install miniprogram-api-typings
```

And through DefinitelyTyped:

```bash
npm install @types/wechat-miniprogram
```

Both badges are present at the top of the documentation, the first for the standalone package and the second for the DefinitelyTyped publication, so both are maintained releases of the same definitions.

After installing the standalone package you wire it in in one of three ways. You can import it manually with `import 'miniprogram-api-typings';`. You can list it in the `types` array of your `tsconfig.json`, as `types: ["miniprogram-api-typings"]`. Or you can use a triple-slash directive pointing at the file, `/// <reference path="node_modules/miniprogram-api-typings/index.d.ts" />`.

The trap is that both packages declare the same global names. The Mini Program API is a global environment, `wx` is a global, and `Page` and `Component` are globals. If both `miniprogram-api-typings` and `@types/wechat-miniprogram` end up in your dependency tree, whether through a direct install or through a transitive one, you get duplicate declarations of the same identifiers. TypeScript will complain, and the fix is to make sure exactly one of them is present.

That is a real operational detail rather than a documentation nicety, because the DefinitelyTyped package can arrive unasked through another dependency.

## What is actually in the package

The published files array in package.json is short and tells you the shape of the deliverable.

There is `index.d.ts`, which is both the `main` and the `types` entry point, so importing the package gives you the ambient declarations for the Mini Program globals. There is `typings.json`, the metadata file TypeScript uses to understand a typings package, and there is a `types/` directory holding the definition files themselves, one per API area.

Alongside the type payload the package ships `LICENSE`, `CHANGELOG.md`, `README.md` and `README-en.md`, the latter being the English version of the documentation that the Chinese README points to at the top.

The repository layout shows the working parts. There is `index.d.ts` and the `types/` directory at the top level, a `test/` directory holding the type test cases, a `typings.json`, a `tsconfig.json` for the project itself, and a `pnpm-lock.yaml` with a `pnpm-workspace.yaml` alongside it, so the repository itself is a pnpm workspace even though the published package is a plain npm package. The `CHANGELOG.md` is the update log, and the documentation links to it directly.

The version is 5.2.3 in package.json, and the package is authored by the Wechat Miniprogram team with the address wx-miniprogram@qq.com.

## The test suite is tsd, which tests types rather than runtime

How this package is tested tells you what kind of correctness is being claimed.

The definitions are tested with `tsd`, the type testing tool from Sam Verschueren, and all the test cases live in the `test` directory. The package.json wires this up with a `tsd` block pointing `directory` at `test`, and the test script runs the type tests and then the linter:

```bash
npm run tsd && npm run eslint
```

That second part matters. The lint script runs ESLint with the repository's own configuration over the type definition files, so the definition files are themselves checked for style and correctness beyond just compiling. The devDependencies back this with `@typescript-eslint` at ^6.21.0, ESLint at ^8.57.1, `tsd` at ^0.32.0, and TypeScript constrained to `^5.2.2 <5.4.0`, a deliberately narrow range.

To run the tests yourself, the instructions are to clone the project, complete `npm install --save-dev`, and run `npm test`. The documentation also invites contributions of test cases: both test cases that cannot pass the automated checks and strong test cases that do are welcome, with the former routed to a pull request or an issue.

That last point is worth a moment. A tsd test is a snippet of TypeScript that is expected to produce a specific compile error or a specific type. Writing a failing one is a way of pinning down a wrong definition so the fix has a target, which is a sensible way to contribute to a generated type file without editing the generated file.

## Where the typings stop, and what they cannot tell you

There are two limits to any type definition package for a platform like this, and both matter for a Mini Program project.

The first is that the types describe the shape of the API, not its behaviour or its timing. The definitions tell you that a call takes certain parameters and returns a certain object. They do not tell you that a particular permission prompt appears, that a particular call fails silently in a particular base library version, or that the platform has deprecated a field. For that you still read the platform documentation, which is also where the generation source lives.

The second is version skew in both directions. The Mini Program platform ships new base library versions continuously, and the typings move at the pace of the documentation generation. A developer on the newest base library can hit an API that is not yet in the type file, and a developer on an older base library can be blocked by a type that requires a newer one. Neither is visible from the typings alone.

The TypeScript version range makes the second point concrete. The package pins TypeScript to `^5.2.2 <5.4.0`, which is a narrow window for a definition package, and the project also ships a `.node-version` file. That is a deliberate choice, and it means the package is tested against a specific compiler generation rather than the latest.

There is also a documentation quality caveat that the project itself acknowledges: if you find an error in an API definition, it is an issue for them to fix, not a pull request from you. That means the feedback loop for a wrong generated type runs through the issue tracker and a regeneration cycle, rather than through a patch you could apply today.

## Choosing between this package and hand written declarations

The alternative to adopting the package is to write your own ambient declarations for the subset of the Mini Program API you use.

The difference in approach is where the truth comes from. Hand written declarations encode what your team has needed so far, which means they are small, readable, and perfectly matched to your project. They are also wrong the moment the platform changes, and there is one more copy per repository to maintain.

This package encodes what the platform documents, which means it is complete and consistent with the vendor's own view of the API, at the cost of covering far more surface than most projects use and being tied to the platform's release cadence rather than yours.

There is a middle path worth considering, and the project supports it structurally. Because the API file is generated and the framework globals are maintained by hand, a team can rely on the package for the API surface and layer its own narrow ambient declarations on top for anything it needs that the generated file has not caught up with. The duplicate identifier problem that comes from installing two copies of the same typings is precisely the risk in that arrangement, so the layering has to be done in a way that does not redeclare the same globals.

For a team already on TypeScript, the practical recommendation is to install the package, keep the TypeScript version inside the pinned range, and treat the issue tracker as the route for anything the definitions get wrong rather than forking the file.

## Conclusion

Adopt miniprogram-api-typings if you write WeChat Mini Program code in TypeScript and want typed wx calls, and prefer it over hand written declarations because the API file is generated from the official documentation. Do not use it as a place to correct the platform API, because the definitions are regenerated and pull requests for API changes are not accepted; report those as issues instead. Verify first which installation route fits your project, the standalone package or the DefinitelyTyped one, since having both installed puts the same global names in scope twice, and confirm your TypeScript version matches the range the package pins.

## FAQ

### How do I install the WeChat Mini Program TypeScript definitions?

Either `npm install miniprogram-api-typings` for the standalone package or `npm install @types/wechat-miniprogram` for the DefinitelyTyped publication. Make sure only one of them is present, since both declare the same globals.

### How do I reference the mini program typings in a TypeScript project?

Import them with `import 'miniprogram-api-typings';`, add `types: ["miniprogram-api-typings"]` to your tsconfig.json, or use a triple-slash reference to node_modules/miniprogram-api-typings/index.d.ts.

### Why are pull requests changing the API definitions not accepted?

Because the API definition file lib.wx.api.d.ts is generated automatically together with the documentation, so a hand edit would be overwritten. The instructions are to report API definition errors as issues, while pull requests are welcome for the Page and Component interfaces and similar.

### How is the mini program typings package tested?

The definitions are tested with tsd, with all test cases in the test directory, and the test script runs the type tests and then ESLint over the types directory. Running the suite yourself means cloning the project, running npm install --save-dev and then npm test.

## Sources

- [Issues](https://github.com/wechat-miniprogram/api-typings/issues)
- [License: MIT](https://github.com/wechat-miniprogram/api-typings/blob/master/LICENSE)
- [README](https://github.com/wechat-miniprogram/api-typings/blob/master/README.md)
- [wechat-miniprogram/api-typings on GitHub](https://github.com/wechat-miniprogram/api-typings)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wechat-miniprogram-api-typings