OpenWeather Maps SDK v0.0.0 docs
Resources

Release & Versioning

Status

Stable 0.1.0 is the first non-prerelease; the earlier 0.1.0-beta.* line stays on npm under the beta dist-tag. All six @openweather/maps-* packages are versioned together as a fixed set in Changesets — one version number across all of them (see .changeset/config.json) — so a breaking change in any single package bumps every package's version, rather than cascading independently. This trades independent versioning for a much simpler support story ("all @openweather/maps-* at 0.2.0 interoperate"), appropriate for packages already this tightly coupled by their dependency graph.

Install with a plain pnpm add @openweather/maps-maplibre (the latest tag). Check npm view <pkg> dist-tags after every release to confirm latest points at the new version.

0.1.0-beta.3 also fixes a real installability bug found while verifying the first releases: the maplibre-gl peer range was >=5.0.0 with no ceiling, so a fresh install could resolve to maplibre-gl@6, which dropped the default export @openweather/maps-gl and @openweather/maps-maplibre import — breaking the build for anyone who didn't already have maplibre-gl pinned. The range is now ^5.0.0 everywhere it appears; pin maplibre-gl@^5 explicitly until a maplibre-gl@6 support pass is done.

Safe to run today

These prove the tarballs are well-formed before publishing anything, and are wired into CI:

pnpm build
pnpm publint            # exports/types map is publish-correct
pnpm attw                # types resolve under node10/node16/bundler resolution
pnpm release:dry-run     # pnpm -r publish --dry-run, no network write

The real publish flow (manual for now)

The first release was published by hand, in dependency-graph order (leaves first), rather than via pnpm changeset version — with no prior tags or CHANGELOGs to build from, hand-setting all six package.json versions was simpler than backfilling a changeset history.

Use pnpm pack, then npm publish <tarball> — not a bare npm publish from inside the package directory. Every inter-package dependency is workspace:* in source; only pnpm's own packing step rewrites that to the real resolved version before the tarball is built. A plain npm publish run inside packages/<name> does not do this rewrite — it ships the literal string "workspace:*" as the dependency version, which is meaningless (and unresolvable) outside this monorepo. This actually happened twice during the first release (0.1.0-beta.0 and 0.1.0-beta.1 both shipped broken this way) before landing on the flow below, which was verified byte-for-byte (grep the packed package.json for the literal string workspace: — it must find nothing) before publishing:

# from each packages/<name> directory, in order:
#   maps-core, maps-gl -> maps-ui-core -> maps-maplibre -> maps-ui, maps-react
pnpm pack --pack-destination /some/scratch/dir
# then, per tarball, from anywhere:
npm publish /some/scratch/dir/openweather-<name>-<version>.tgz --access public

pnpm publish (run directly, rather than pnpm pack + npm publish as two steps) should do the same rewrite in principle — pack first and inspect the tarball regardless, since the two beta releases above were the "should be fine" case failing in practice for reasons never fully diagnosed on the publishing machine.

After any publish, check latest — a prerelease publish (--tag beta) only ever moves the beta tag; latest still points at whatever the very first publish set it to (0.1.0-beta.0, the broken build with unresolved workspace:*, for all six packages as of this writing) until someone runs npm dist-tag add <pkg>@<version> latest for each package. Don't assume latest and beta agree — check npm view <pkg> dist-tags after every release.

This is not yet wired into CI — every publish today is a manual step from a maintainer's machine, requiring npm 2FA. A CI release stage (most likely changeset version + changeset publish from a GitLab runner, gated behind a protected NPM_TOKEN CI/CD variable) is a planned follow-up, not yet built.

Public API conventions

  • Packages: @openweather/maps-core, @openweather/maps-gl, @openweather/maps-maplibre, @openweather/maps-ui-core, @openweather/maps-ui, @openweather/maps-react.
  • Public vs. internal: each package's main barrel is the versioned public surface. Plumbing only sibling SDK packages need (tile/mercator math, multi-tile canvas assembly, the HEAD-probe pipeline) lives behind a /internal subpath and is explicitly not part of the semver contract — see @openweather/maps-core.
  • Deprecations: a superseded method (e.g. setRadarModel(), replaced by setLayerModel('radar', modelId)) stays in the public surface with a @deprecated tag until a major version removes it — it's never silently deleted without a version bump.

Full naming/error/event conventions live in the repo's docs/API_CONVENTIONS.md.