# Generate an API Reference for a TypeScript Library With TypeDoc

Yes. An agent adds TypeDoc to your TypeScript library, builds a reference site from the types you already export, and publishes it to GitHub Pages from CI.

[Run this on Rush](https://cloud.getrush.ai/run/add-typedoc/typescript-library/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads how the package is built and what it exports before it adds a docs tool. In a library like sindresorhus/ky, `package.json` says `"type": "module"`, `engines.node` is `>=22`, `exports` points `types` at `./distribution/index.d.ts`, and `files` publishes only `distribution`. The `build` script is `del-cli distribution && tsc --project tsconfig.dist.json`; that tsconfig extends `./tsconfig` (itself extending `@sindresorhus/tsconfig` with `exactOptionalPropertyTypes`), sets `rootDir` to `./source` and `outDir` to `./distribution`. The `test` script chains `xo`, the build, a `tsc --project tsconfig.test.json` type check and `ava`. The agent reads `.gitignore` too: `distribution/` and `package-lock.json` are ignored, so the docs output must be ignored the same way and the workflow cannot rely on a lockfile.

Then it reads `source/index.ts` to learn the public surface TypeDoc will document. The default export is the `ky` instance made by `createInstance`. After it come the type exports: `KyInstance`; `Input`, `Options`, `NormalizedOptions`, `RetryOptions`, `ShouldRetryState`, `SearchParamsOption` and `Progress` from `types/options.js`; eleven hook types from `types/hooks.js`; `ResponsePromise`, the three `StandardSchemaV1` types, `KyRequest` and `KyResponse`. The value exports are seven error classes (`KyError`, `HTTPError`, `SchemaValidationError`, `NetworkError`, `TimeoutError`, `ResponseSizeError`, `ForceRetryError`), six `is*` type guards from `utils/type-guards.js` and `replaceOption`. A comment says `NonError` is deliberately not exported. The agent notes that `source/types/options.ts` already carries JSDoc on its options, which is what TypeDoc renders, and that `readme.md` has a long hand-written `## API` section (`### ky(input, options?)`, `##### retry`, `###### hooks.beforeRequest`, ...) that stays the narrative reference while the generated site becomes the exhaustive one.

The agent adds `typedoc` as a dev dependency and writes `typedoc.json`: `entryPoints` `["source/index.ts"]`, `tsconfig` `tsconfig.dist.json` so the same compiler settings apply, `out` `docs`, `readme` `readme.md` so the landing page is the existing readme, `excludeInternal` on, and `validation.notExported` on so a type that appears in a signature but is not exported from `index.ts` fails the build instead of rendering as a dead link. It adds a `docs` script (`typedoc`) and a `docs:check` script (`typedoc --emit none --treatWarningsAsErrors`) that validates without writing files and fails on any warning, appends `docs/` to `.gitignore`, and runs both in the sandbox with `npm install`. The output is checked by hand: the `Options` page should list every option the readme documents, each error class should show its `name` and the `HTTPError` page its `response` and `request` properties.

Finally it adds `.github/workflows/docs.yml`: on push to `main`, a job with `permissions: pages: write` and `id-token: write` runs `actions/checkout`, `actions/setup-node` with Node 22, `npm install`, `npm run docs`, then `actions/upload-pages-artifact` with `path: docs` and `actions/deploy-pages`. The existing `main.yml` CI gets one step, `npm run docs:check`, in its `browser` job, which the file's own comment reserves for checks that do not depend on the Node version. The agent changes nothing in `source/` and nothing in the readme beyond one line under `## API` linking to the published site.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add TypeDoc to this TypeScript library. Read package.json, the tsconfig files and the entry point first, and document exactly what the entry point exports, nothing more. Configure TypeDoc to use the distribution tsconfig, use the existing readme as the landing page, and fail on types that are referenced but not exported. Add a docs script that builds the site and a check script that validates without writing files, ignore the output directory, and add a GitHub Actions workflow that builds the site on pushes to main and deploys it to GitHub Pages. Add the check script to the existing CI workflow. Do not change any source file or the public API. Open a pull request that lists every exported symbol the site documents.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `typedoc.json` and `.github/workflows/docs.yml`, changes `package.json` (the `typedoc` dev dependency, the `docs` and `docs:check` scripts), `.gitignore` (`docs/`), `.github/workflows/main.yml` (one step) and `readme.md` (one link). Its description lists the entry point's exports as TypeDoc grouped them: the default export, the type aliases and interfaces, the classes, the type guards and `replaceOption`, and quotes the `docs:check` output from the sandbox, warnings included.

The run's record keeps every command with its output, including the `npm install` that fetched TypeDoc and the validation pass, so a reviewer can see which version was installed and that the build produced no warnings before the workflow ever runs on GitHub.

Before merging, a reviewer enables GitHub Pages with GitHub Actions as the source in the repository settings, since the workflow cannot do that, checks that the `readme` landing page renders the readme's relative image path for `media/logo.svg` (TypeDoc copies the readme but not sibling files unless told to), and decides whether `validation.notExported` should block CI or only warn while the first undocumented types are sorted out.

## Run it on every terminal hand-off

This is a one-time setup, so the natural start is from a terminal: one `POST /o/{org}/sessions` with this body and the repository in `resources`, then walk away. The run keeps going in its sandbox, and when the turn ends the sandbox parks with its disk and memory, so a follow-up (`POST /o/{org}/sessions/{id}/messages`) can ask for a different theme or output path without starting over.

A webhook on the API key reports `run.completed` with the `session_url` to read the pull request link, or the key's creator watches the live event stream at `GET /o/{org}/sessions/{id}/events`.

## Why run it on Rush?

Documentation tooling is the kind of change that is easy to half-finish: a config that documents internal helpers, a workflow that fails on the first push because Pages permissions are missing, a readme landing page with broken relative links. The agent reads the entry point and the build configuration first, so the site documents the package the way `exports` presents it, and it runs the validation in its own sandbox so unresolved references are found before the pull request opens.

The sandbox is a real computer with Node and npm, so `npm install` and `typedoc` run for real and their output is kept in the run's record. Several libraries can get the same treatment at once, each in its own sandbox, and each pull request arrives with the validation output as proof.

## Frequently asked questions

### Will TypeDoc document my internal modules?

No. With `source/index.ts` as the only entry point, TypeDoc documents what that file exports and the types those exports reference. Internal helpers such as `utils/merge.ts` appear only where an exported signature uses them, and `excludeInternal` hides anything tagged `@internal`.

### What if a type is used in a public signature but not exported?

`validation.notExported` turns that into a warning, and `typedoc --emit none --treatWarningsAsErrors` fails the check. The pull request lists each such type so you can decide whether to export it from the entry point or mark it `@internal`.

### Does it need a lockfile?

No. This library ignores `package-lock.json`, so the workflow runs `npm install` rather than `npm ci`. If your repository commits a lockfile, the agent uses `npm ci` and enables the setup-node cache instead.

### Why not generate Markdown into the readme instead?

The readme already has a curated API section with examples and prose that a generator would not produce. The site complements it with every signature, overload and property, and the readme gains one link to it. If you prefer Markdown output, a follow-up can switch to the TypeDoc Markdown plugin.

## More TypeScript library jobs

- [Write Property-Based Tests for a TypeScript Library](https://getrush.ai/run/write-property-tests/typescript-library/)
- [Add Are the Types Wrong to CI for a TypeScript Library](https://getrush.ai/run/add-attw-to-ci/typescript-library/)
- [Add a Bundle Size Check to a TypeScript Library from a Linear Issue](https://getrush.ai/run/add-bundle-size-check/typescript-library/)

## More jobs like this: Hand off a long task

- [Add a Typing Indicator to a Socket.IO Chat](https://getrush.ai/run/add-typing-indicator/socket-io/)
- [Add a Typo Check to a Docusaurus Site in CI](https://getrush.ai/run/add-typo-check/docusaurus/)
- [Add a Typo Check to an Eleventy Blog in CI](https://getrush.ai/run/add-typo-check/eleventy/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
