Skip to main content

Development workflow

Workspace commands​

The root is a Yarn 4 workspace. @vis.gl/dev-tools supplies the common repository commands:

yarn install       # install all workspaces once
yarn bootstrap     # install and link workspace binaries
yarn clean         # remove generated package output
yarn build         # Ocular clean, build renderer bundles, then build TangramLayer
yarn build:packages # alias for the complete package build
yarn typecheck     # check mixed JavaScript/TypeScript sources without emitting
yarn lint          # Biome plus the renderer compatibility lint
yarn lint:fix      # apply safe Biome fixes
yarn test-fast     # lint and Node tests
yarn test-browser  # Chromium-backed Vitest project
yarn test-coverage # headless Vitest coverage run (renderer source)
yarn test          # lint, Node tests, worker bundle, and Vitest browser tests

The root TypeScript configuration accepts both JavaScript and TypeScript, uses browser-oriented bundler resolution, and checks TypeScript strictly without forcing JavaScript files to become typed in the same change.

The renderer's Rollup configuration remains package-specific because Tangram ships both browser and worker bundles. The package entrypoint is generated by modules/tangram-renderer/scripts/write-package-entry.mjs after those bundles are built. This keeps the public exports reproducible without coupling the renderer to deck.gl.

Renderer output under modules/tangram-renderer/dist/ is generated and is not committed. Package builds, example start commands, website assembly, bundle-size reporting, and npm prepack all create the required artifacts from source. Do not add generated bundles or schemas to a commit.

The root build is split into an explicit build:modules stage so package builds can be migrated to ocular-build independently. The renderer still uses its worker-aware Rollup pipeline; the TangramLayer package builds its main and experimental WebXR entries with ocular-bundle. The renderer remains an external package boundary in both layer bundles.

The classic playground is also a workspace package. Its build copies the playground source and style gallery into examples/classic/dist/; the website build consumes that output. For a standalone local server, run yarn workspace @vis.gl/tangram-classic start; the command builds both the renderer and playground before serving them.

Private shared development helpers live under dev-modules/. They are not published and should stay focused on test and build infrastructure.

Renderer tests and coverage​

The renderer’s tests run through Vitest, using the node, browser, and headless projects supplied by @vis.gl/dev-tools. The historical renderer specifications are executed by the headless project with a compatibility setup so they can be migrated to native Vitest syntax incrementally without losing coverage. New tests should use native Vitest APIs and should be placed in *.node.spec.* or *.browser.spec.* files according to their runtime.

The existing Chai assertions and Sinon spies/stubs remain as compatibility helpers for the inherited suite. New tests should prefer Vitest’s expect, vi.fn, vi.spyOn, and vi.stubGlobal; the remaining helper usage can be removed incrementally without bringing back a second test runner.

The coverage command scopes instrumentation to modules/tangram-renderer/src/**/*.{js,ts}. It includes the existing renderer unit and integration suite, including the legacy specifications under Vitest, and emits text, LCOV, and JSON summary reports in coverage/.

The pull-request workflow collects separate Node and Chromium coverage blobs, merges them, and enforces these global renderer thresholds before uploading the report as a workflow artifact:

  • 30% statements;
  • 25% branches;
  • 35% functions; and
  • 30% lines.

Coverage is intentionally scoped to source rather than generated bundles, fixtures, or dependencies. The report shows untested files and keeps the threshold ratchet visible as the renderer is converted to TypeScript.

Website and examples​

Run yarn website:start for the Docusaurus site or run yarn build:modules before serving the repository root to open examples/deck/ directly. yarn website:build builds and stages the examples and package outputs into the static site before building Docusaurus.