How Does This Not Exist?

Whenever I have an idea for something, my first instinct is "someone must have already solved this." Imposter syndrome, maybe. Or maybe there's a reason it doesn't exist.

I inherited 10+ packages with documentation that ranged from outdated to nonexistent. My job was to fix it — turn it into something digestible, complete, actually useful.

TypeDoc was already in place in some cases. But generic HTML output didn't match our brand, overwhelming with data and impossible to navigate. It was technically "documentation" but nobody could use it effectively.

Managing this manually wasn't going to work. I needed something that could start from source code, extract the details, and let me build custom views on top. Not a docs site — a spec.

To be fair — the existing tools get close. TypeDoc is really good for generating docs, but it's more of a document than a spec. Type refs don't resolve, destructured params lose structure, generics flatten into strings. API Extractor is closer to an API surface spec, but the DX is a big turnoff and comes with more features than I need.

REST APIs have OpenAPI. GraphQL has introspection. What does TypeScript have?

No standard for "here's every export, its signature, its types, its JSDoc." No way to diff versions to measure breaking changes. No structured output you can feed to an LLM or build tooling around.

A package spec should be simple: list every public export, capture full type information, output JSON, work standalone. One command. No build pipeline required.

So I'm building it.

Introducing OpenPKG - an OpenAPI-style spec for TypeScript packages.

/** Creates a new client */
export function createClient(config: { baseUrl: string }): void {}

npx @openpkg-ts/cli snapshot src/index.ts

1
{
2
  "openpkg": "0.4.0",
3
  "exports": [
4
    {
5
      "name": "createClient",
6
      "kind": "function",
7
      "description": "Creates a new client",
8
      "signatures": [
9
        {
10
          "parameters": [
11
            {
12
              "name": "config",
13
              "schema": {
14
                "type": "object",
15
                "properties": {
16
                  "baseUrl": { "type": "string" }
17
                }
18
              }
19
            }
20
          ]
21
        }
22
      ]
23
    }
24
  ]
25
}

One command. Structured JSON Schema (2020-12). Every export, every signature, every type,every JSDoc — referenced and extracted and ready for whatever you want to build on top.