Observable Framework: a TypeScript project whose npm tarball ships no type declarations

The README is five links and the docs site is built by the tool

The whole README runs to a little over a hundred words and is mostly pointers: a documentation link to observablehq.com/framework, an examples link to the examples directory in this repository, a releases link standing in for the changelog, a help section that asks you to open a discussion and also to search existing issues, and a contributing link back to the documentation site. The one number-bearing element is a daily downloads badge that renders a chart from oss-analytics rather than printing a figure. The repository builds that documentation site with its own tool: the docs build script points the CLI at its own source entry, `src/bin/observable.ts`, and the dev watcher explicitly ignores the `docs` directory so editing documentation does not restart the server.

The published files list is JavaScript, CSS and templates

The package manifest names itself `@observablehq/framework`, version 1.13.4, license ISC, module type, and public publish access. What it publishes is defined by a files array of three patterns: `dist/**/*.js`, `dist/**/*.css` and `templates`. The build that produces that directory runs from `build.js` and excludes declaration files with an ignore pattern for `**/*.d.ts`. So a TypeScript-first project whose tree carries `tsconfig.json`, `.eslintrc.json` and a Prettier configuration publishes a tarball with no `.d.ts` in it, which means a TypeScript consumer sees the module as untyped unless types are supplied elsewhere. The binary the package installs is named `observable`, mapped to `dist/bin/observable.js`, and the templates directory ships alongside it as scaffolding.

The lockfile is yarn's and the test entry point says npm

The repository ships a `yarn.lock` and no `package-lock.json`, and several scripts call yarn directly, including the coverage script running `yarn test:mocha:all`. The main test script is the exception: it is `concurrently npm:test:mocha npm:test:tsc npm:test:lint npm:test:prettier`, four npm-prefixed aliases rather than yarn invocations, and the build test sets a version through cross-env using the `npm_package_version` environment variable that npm populates. A yarn-only install will still run these because modern yarn resolves the aliases, but the project is mixing two package-manager conventions in the same scripts block, and the test path is where that mix is densest.

Tests pin a timezone, a timeout and a telemetry switch

Both mocha entries run with the same environment: telemetry disabled through `OBSERVABLE_TELEMETRY_DISABLE=1`, the timezone forced to America/Los_Angeles, and a 30000 millisecond timeout. That the CLI reports telemetry at all is worth noticing in a generator whose selling point is that dashboards load instantly with no server, and the switch exists so the test suite does not phone home. A separate annotate script sets `OBSERVABLE_ANNOTATE_FILES=true` and runs a different set of files, so annotation behaviour is tested on its own path rather than inside the main suite. Coverage is enforced per file rather than in aggregate: the coverage script runs c8 with a check-coverage flag at 80 percent lines, per file, over the serial mocha run.

Data loaders decide what runs at build time

The single technical claim in the README is that data loaders precompute static snapshots of data at build time, which is what lets a dashboard load instantly, and the examples directory is the catalogue of what that means in practice. There is one example per data source: `loader-airtable`, `loader-arrow`, `loader-census`, `loader-databricks`, `loader-duckdb`, `loader-elasticsearch`, `loader-github`, `loader-google-analytics` and `loader-canvas-to-png`, the last producing an image file rather than rows. Beside them sit projects that fetch from HTTP APIs, `api` and `datawrapper-api`, and two worked datasets, `eia` for energy data and `hotel-bookings`. The columnar entries, DuckDB and Arrow, are the ones that let a large table be computed once and shipped as a static file.

The examples carry their own lint config and their own gitignore

The examples directory is not a loose folder of demos. It has its own `.eslintrc.json` and its own `.gitignore` next to a README, sitting alongside the repository level `.eslintrc.json`, `.eslintignore`, `.prettierrc` and `.prettierignore`, so lint rules are defined twice at two levels. The front-end half of the framework is visible in the example names: `codemirror` for an embedded editor, `custom-input-2d` for a hand-written input component, `input-select-file`, `custom-stylesheet` for overriding the generated page, and `intersection-observer`, which is a lazy-loading pattern that only makes sense in a framework whose pages are static and whose components hydrate as they scroll into view. `chess` and `hello-world` are the scale endpoints of that range.

One point thirteen point four has been out since March

The release line has slowed in a way worth planning around. Version 1.13.2 published on 23 January 2025, 1.13.3 on 16 April 2025, and 1.13.4 on 2 March 2026, so the last two gaps are about eleven months each where the earlier ones were under three. The last commit to the default branch is dated 15 May 2026, more than two months after that release, which means the branch carries work that is not in any published version. Repository counters sit at 3,655 stars and 181 open issues, and the help route the README offers is a discussion plus a search of existing issues, with contributing handled through a guide on the documentation site rather than a file in the tree.

Editorial conclusion

Framework fits teams who want a dashboard or report that is a static site rather than a running service, and who are willing to move the data work into build-time loaders. Check three things before committing. If your project is TypeScript, know that the published package lists built JavaScript, CSS and templates only, so you are consuming untyped JavaScript. If your data lives behind an API or a warehouse, the loader examples show the shape of the work: Airtable, Census, Databricks, DuckDB, Elasticsearch, GitHub, Google Analytics, plus Arrow and canvas output, all resolved at build time rather than in the browser. And if you need a maintained release line, note that 1.13.4 shipped on 2 March 2026 while commits continued to 15 May 2026, so plan for a slow cadence and read the changelog before pinning.

Frequently asked questions

Official sources

1. License: ISC
2. observablehq/framework on GitHub
3. Project website
4. README
5. Releases