Sourcey's npm build vendors a Go module and a Rust crate, then deletes a directory it never rebuilds
Precision documentation from OpenAPI, MCP, Doxygen, and Markdown guides. Static HTML you own.
At a glance
- What is it?
- Sourcey turns six kinds of source into one static HTML site you own, with everything rendered at build time and no runtime. The coverage is unusually wide, including a MkDocs importer, an Astro integration, and native Go and Rust documenters that can run without a JavaScript toolchain at all. The build script is where the story gets interesting: it copies two other ecosystems' source into the TypeScript package and removes one vendored directory with nothing put back.
- Who is it for?
- Sourcey is worth a look if you have to publish API reference for more than one ecosystem and you want static output on your own hosting rather than a hosted docs product. The two decisions that matter most are snapshot mode for Rust, which lets CI build on a stable toolchain instead of nightly rustdoc, and the MkDocs importer, which reads `docs_dir` and `nav` instead of asking you to rebuild your sidebar.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 8 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- sourcey/sourcey1,380 ★ · +11
| Repository | 2026-09-11 | 2026-11-22 |
|---|---|---|
| sourcey/sourcey | 1.4k | 1.4k |
11 Stars in the last 72 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The build removes `dist/core/godoc-introspect` and never puts anything back
The build script is a single long shell chain, and the interesting part is one clause:
rm -rf dist/core/sourcey-godoc dist/core/godoc-introspectTwo directories are deleted. Then only one of them is recreated:
mkdir -p dist/core/sourcey-godoc
cp -R go/sourcey-godoc/go.mod go/sourcey-godoc/doc.go go/sourcey-godoc/cmd dist/core/sourcey-godoc/So `sourcey-godoc` gets rebuilt from the repository's `go/` directory on every build, while `godoc-introspect` is removed and stays removed.
Whether that is a deliberate retirement of an older Go tool or an oversight depends on whether anything still references that path, which is not answerable from the files in view. It is checkable in one grep, and it is the kind of thing worth checking.
The same remove-then-recreate pattern runs again immediately afterwards for the Rust side, `rm -rf dist/core/sourcey-rustdoc`, `mkdir -p dist/core/sourcey-rustdoc`, then a copy of `Cargo.toml`, `Cargo.lock`, `README.md`, `src` and `tests` from `rust/sourcey-rustdoc/`.
Two ecosystems, vendored into a TypeScript package's output directory, by a script that has to delete the previous copies first or the stale files would accumulate.
`files` is `dist` and `LICENSE`, and `dist` contains Go and Rust source
The published file list is the shortest possible one. The `files` array in the manifest holds `dist` and `LICENSE`, and nothing else.
And yet the build copies a Go module's `go.mod`, its `doc.go` and its `cmd` directory into `dist/core/sourcey-godoc/`, and a Rust crate's `Cargo.toml`, `Cargo.lock`, `README.md`, `src` and `tests` into `dist/core/sourcey-rustdoc/`.
So anyone who installs Sourcey from npm receives two other language ecosystems' source code inside their `node_modules`. That is what makes the standalone binaries possible: the Go module travels inside the npm tarball and can be compiled on the consumer's machine, and the Rust crate travels with its `Cargo.lock` intact.
Two hooks keep that vendored copy honest. `prepublishOnly` runs the build, so a published tarball can never contain a stale vendored module. And `pretest` runs the build too, which is the subject of the next section.
The package is `"type": "module"` with Node 20 or newer required, one binary named `sourcey` pointing at `dist/cli.js`, and two export subpaths, `.` and `./astro`, each pairing built declarations with built JavaScript. Both resolve into `dist`, which is the same directory that holds the Go and Rust sources.
`pretest` runs the whole clean build, so no test ever runs against a stale `dist/`
Three hooks and one watch script all funnel through the same build.
"pretest": "npm run build"That is npm's lifecycle hook, so `npm test` cannot reach `vitest run` until a full clean build has finished. Given that the build starts with `rm -rf dist` and then re-vendors the Go and Rust trees, every single unit test invocation pays for a full recompile of the TypeScript plus two directory copies.
`prepublishOnly` does the same thing, so a publish can never ship a stale `dist` either. And `watch` is `npm run build && tsc --watch --preserveWatchOutput`, so the initial build happens once and then the compiler watches.
The design decision underneath is reasonable: this package has hand-written copy steps in its build, so anything that consumed `dist` without rebuilding first could see a mix of fresh and stale vendored sources. The cost is that the test loop is no longer incremental.
If you are working on this codebase, `vitest` on its own, which is what `test:watch` invokes, is the fast path. Anything that needs the vendored trees has to go through the full chain.
Four quality checks that are not TypeScript are wired as npm scripts
The Go module and the Rust crate are tested from the Node manifest rather than from their own ecosystems.
"godoc:go:test": "cd go/sourcey-godoc && go test ./..."Beside it sit `godoc:go:vet` running `go vet ./...` in the same directory, and `godoc:packages:test` pointing at a shell script, `packaging/sourcey-godoc/render-package-managers.test.sh`, whose name says it tests the packaging across package managers.
Then the one with the clearest intent:
`cpp:release-gate` runs `node scripts/check-cpp-reference-quality.mjs`.
A release gate, named as such, as a first-class script. Whatever it checks about C++ reference quality, the decision to make it a named gate rather than a lint rule means it can block a release rather than merely print.
So the Node-side surface runs `vitest`, `eslint`, `prettier` and `tsc`, and four more scripts reach into Go and into the C++ reference output. That is a lot of ecosystems for one manifest to coordinate, and it works only because every one of them is a plain command in a script.
The TypeScript side itself is `eslint src/ test/`, `prettier` over the same two trees, and `tsc --noEmit`.
Snapshot mode exists so CI never needs nightly rustdoc
The Rust story is a two-step answer to a build-stability problem. The `rustdoc()` adapter consumes nightly rustdoc JSON through a companion crate published on crates.io, and a `sourcey-rustdoc` converter alongside it. The stated payoff is that CI can build Rust API documentation from a committed snapshot while running on a stable Rust toolchain.
That is the whole trade: you give up the guarantee that the docs match the current nightly output, and you get a documentation build that does not break when nightly moves.
The Rust output is unusually thorough. Doctests are a first-class extracted view, there is an aggregated doctests index across the workspace, and parametric impl anchors are URL-encoded for deep-link parity with doc.rust-lang.org, so a link into Sourcey lands where the equivalent link lands on the official site.
Go gets the same snapshot treatment from the other direction. Beyond rendering Go modules as Sourcey tabs and generating standalone static Go docs sites, Sourcey can commit `godoc.json` snapshots, described as being for JS-only docs hosts. Go documentation is extracted from Go source via the toolchain rather than through Doxygen.
And for people with no JavaScript at all, `sourcey-godoc` ships as a separate native binary, installed with `go install`, with Homebrew, or from a Scoop bucket the project maintains.
The container installs Sourcey from npm with a `latest` default
The Dockerfile is nine meaningful lines:
FROM node:20-alpine
ARG SOURCEY_VERSION=latest
RUN npm install -g "sourcey@${SOURCEY_VERSION}" && npm cache clean --force
WORKDIR /docs
ENTRYPOINT ["sourcey"]
CMD ["build"]Four OCI labels follow, carrying the title, description, URL and source repository.
Two things are worth reading twice. The build resolves the package from npm with a build argument defaulting to `latest`, so the image contents are whatever the registry served on the day the image was built, and nothing in the Dockerfile ties them to a Sourcey revision. Anyone who needs a reproducible image has to pass `SOURCEY_VERSION` explicitly.
Second, the entry point and command combine into something friendly. Because the entrypoint is `sourcey` and the command is `build`, a bare `docker run sourcey/sourcey` documents the working directory. That is why the documented invocation is `docker run -v "$PWD":/docs sourcey/sourcey`, with the mount landing exactly on `WORKDIR /docs`.
`node:20-alpine` matches the manifest's Node 20 floor, which is the kind of small consistency worth checking for and then finding correct.
The dev path is different from the build path: `sourcey dev` serves through Vite with server-side hot reload on every component and CSS change, and spec or markdown changes trigger a refresh.
MkDocs is imported rather than replaced, and Astro can mount the docs
Two integrations are worth separating, because they solve opposite problems.
The MkDocs import is about not starting over. You point a tab at an existing `mkdocs.yml`, and Sourcey reads the `docs_dir` and `nav` keys, so a MkDocs markdown site renders with its sidebar structure intact and nobody has to hand-copy the navigation into a new format.
The Astro integration is about not running two pipelines. Instead of a separate docs CI job, Astro sites mount Sourcey directly. The integration reads the same `sourcey.config.ts` the CLI uses, derives Sourcey's public `siteUrl` and `baseUrl` from Astro's own `site` and `base` settings plus a `routeBase` argument, serves the docs during `astro dev`, and writes them into Astro's final build output.
sourcey({
config: "./sourcey.config.ts",
routeBase: "/docs",
})You can also import the config object and share one module between the CLI and Astro, which is the tidy version of the same idea.
Both integrations rest on a claim the feature list makes twice: everything renders at build time, with no dashboard, no runtime and no API calls to render your own documentation. The output is static HTML you can put on GitHub Pages, Vercel, Netlify or S3, and the same build also emits `llms.txt` and `llms-full.txt` as alternate views of the same documentation graph.
Editorial conclusion
Sourcey is worth a look if you have to publish API reference for more than one ecosystem and you want static output on your own hosting rather than a hosted docs product. The two decisions that matter most are snapshot mode for Rust, which lets CI build on a stable toolchain instead of nightly rustdoc, and the MkDocs importer, which reads `docs_dir` and `nav` instead of asking you to rebuild your sidebar. Four things to check before you depend on it. The published tarball carries a Go module and a Rust crate inside `dist/core`, and the build removes `dist/core/godoc-introspect` without recreating it. Every test run triggers a full clean build because of the `pretest` hook. The Docker image installs Sourcey from npm with a `latest` default, so it is a snapshot of the registry rather than of your revision. And the licence is AGPL-3.0, which matters if you were expecting permissive.
Frequently asked questions
How do I install Sourcey?
Four paths, all documented in one table. `npm install -g sourcey` needs Node 20 or newer, `brew tap sourcey/tap && brew install sourcey` covers macOS and Linuxbrew, `docker run -v "$PWD":/docs sourcey/sourcey` uses Docker, and `nix run github:sourcey/sourcey` uses Nix flakes. Then `sourcey init` scaffolds a project or `sourcey build` runs against an existing one. The quick start also shows `npx sourcey init`.
Do I need a JavaScript toolchain to document a Go project with Sourcey?
No. `sourcey-godoc` ships as a separate native binary for Go-only consumers without a JavaScript toolchain, producing either static Go docs sites or portable `godoc.json` snapshots. It installs with `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest`, `brew install sourcey/tap/sourcey-godoc`, or from the project's Scoop bucket.
Can Sourcey build Rust API docs on a stable Rust toolchain?
Yes, in snapshot mode. The `rustdoc()` adapter consumes nightly rustdoc JSON through the `sourcey` companion crate on crates.io and its `sourcey-rustdoc` converter, so CI can build from a committed snapshot without depending on nightly. The Rust output also treats doctests as a first-class extracted view, with an aggregated doctests index across the workspace.
What licence is Sourcey released under?
AGPL-3.0. The feature list states it directly, with self-hosting, forking and extension named as the supported uses. The package publishes under the same licence, with `LICENSE` as the only file in the tarball besides `dist`.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sourcey-sourcey)Star history chart for your README
[](https://hysenlabs.com/projects/sourcey-sourcey)Was this useful?