Installing the Honua JavaScript SDK

The Honua JavaScript SDK ships as a single npm package — @honua/sdk-js — with multiple subpath entrypoints. The core client, the Esri compatibility layer, the migration helpers, and the protocol-neutral contract are all reachable from this one install.

Generated support status

The versioned source of truth is config/support-manifest.v1.json. It projects 22 supported (documented below as stable), 26 experimental, and 18 deprecated package entrypoints. Protocol status is independent of package lifecycle: raw endpoint support, facade requirements, execution mode, and evidence are listed in the generated backend-agnostic capability matrix. The generic support projection carries explicit contracts for both honua.io and the canonical samples/catalog.v2.json inventory.

The reviewed package-root ceilings are 46 runtime exports and 172 declaration exports. The exact inventory and generated migration table come from config/root-surface.json. This guide tracks the current development branch; its package baseline can match the latest release while the branch contains unreleased work. Use the tagged release documentation for the published artifact.

Stable subpath entrypoints

Subpaths covered by the SDK's semver contract. Symbols reachable from these entrypoints are stable across minor versions.

Experimental subpath entrypoints

Subpaths marked @experimental in JSDoc. Useful today; the shape may change in any minor release prior to 1.0.0. The stable root promotes a reviewed query-planner subset: explainQuery, executeQueryPlan, hashQueryPlan, the plan errors/version constants, and the types required to name the common explain/mount workflow. The complete @honua/sdk-js/query-planner subpath remains experimental. Every other experimental subpath is subpath-only and is not re-exported from @honua/sdk-js or @honua/sdk-js/honua.

Deprecated compatibility entrypoints

These temporary @honua/sdk-js shims were introduced in 0.1.0-beta.0 when the application platform moved. They remain available throughout 0.1.x and are removed in 0.2.0; new code must import the replacement directly. A replacement's own support status is independent of the shim: promoting @honua/app-platform/scene-workspace to beta did not move the @honua/sdk-js/scene-workspace removal window.

Application-platform entrypoints (@honua/app-platform)

App-shell, app-builder, and hosted-product surfaces have moved out of the client SDK into the separate @honua/app-platform package, which versions at its own pre-1.0 cadence so @honua/sdk-js can reach a frozen 1.0 without waiting on them (see docs/decisions/scope-split-and-1.0.md).

During the transition, the deprecated imports listed above keep working through 0.1.x; they are removed in 0.2.0. Update imports to @honua/app-platform/<subpath>. The @honua/sdk-js/console entrypoint was removed outright (its projection helpers are owned by the @honua/console application) and has no shim.

Prerequisites

• Node.js 20 or later
• A Honua Server instance only for capabilities marked facade-required; standalone protocol clients do not require one

Install

npm install @honua/sdk-js

Optional peer dependencies

A few integration paths are gated behind optional peer dependencies so a Node-only or REST-only consumer never pays the install cost:

If you stay on the default REST transport with no MapLibre/Cesium scene work, no extra installs are required.

Quick Start

import { HonuaClient } from "@honua/sdk-js";

const client = new HonuaClient({
  baseUrl: "https://your-honua-server.com",
});

const compatibility = await client.checkCompatibility();
if (!compatibility.supported) {
  throw new Error(
    `Unsupported Honua server. Minimum supported version: ${HonuaClient.minimumSupportedServerVersion}. ` +
      `Reasons: ${compatibility.reasons.join("; ")}`,
  );
}

const result = await client.queryFeatures({
  serviceId: "natural-earth",
  layerId: 0,
  where: "1=1",
  returnGeometry: true,
  outFields: ["*"],
  outSr: 4326,
  resultRecordCount: 25,
});

const featureCount = result.features?.length ?? 0;
console.log(`Found ${featureCount} feature(s)`);

This quick start uses the raw GeoServices queryFeatures() request. Its where member is GeoServices SQL and is not the deprecated, source-native protocol-neutral Query.where compatibility member.

Use focused stable subpaths for advanced APIs. The generated root import migration table maps every symbol removed from the transition-era root to its supported replacement; the machine-readable source is config/root-surface.json.

checkCompatibility() reads the parsed data.compatibility contract from GET /api/v1/admin/capabilities. For a runnable browser example from this repo, including the renderable-geometry checks used by the committed MapLibre quickstart, see examples/maplibre-quickstart/README.md.

Canonical Contract And Exploration

The SDK exposes a protocol-neutral client contract and exploration state module that wrap the existing HonuaFeatureLayer / HonuaMapService / HonuaOgcFeatureCollection classes. These are reachable via the @honua/sdk-js/contract and @honua/sdk-js/exploration subpaths:

• docs/shared-client-contract.md — Dataset, Source, Capabilities, Query, Result, MapBinding, and createDataset(...).
• docs/exploration-context.md — createExplorationContext(...) with linked-view presets (globalLinked, mapDriven, gridDriven, chartDriven, decoupled).
• docs/protocol-capability-matrix.md — capability coverage per protocol (geoservices-feature-service, geoservices-map-service, geoservices-image-service, geoservices-geometry-service, geoservices-gp-service, ogc-features, ogc-tiles, ogc-maps, stac, wfs, wms, odata).
• docs/wfs.md — first-party WFS 2.0 adapter, FES filter translation, content-type negotiation, transactions, stored queries, and the Source.protocol("wfs") escape hatch.
• docs/source-binding-alignment.md — round-trip mapping between SourceDescriptor and the server SourceBinding document.
• docs/maplibre-runtime.md — loadMapPackage(...) and HonuaMapRuntime for the MapLibre GL JS-first MapPackage runtime.

Esri Migration

The migration helpers live behind the @honua/sdk-js/migration subpath. They power the same codemod that the standalone CLI runs:

import { runEsriCompatCodemod, scanArcGisUsage } from "@honua/sdk-js/migration";

const report = scanArcGisUsage("./src");
const migration = runEsriCompatCodemod({ rootDir: "./src", write: true });

Version Policy

• Documentation version: Hosted guides and API entrypoints identify their exact SDK release. Use the generated documentation version selector for tagged archived guides, compatibility ranges, and migration links.
• Pre-release (-alpha.*, -beta.*): Published to npm with @alpha / @beta dist-tags.
• Stable (1.0.0+): Published to npm as @latest.
• Semver: All releases follow Semantic Versioning. Public symbols reachable from the documented subpaths above are covered by the contract; symbols marked @experimental in JSDoc may change in any minor release.
• Cross-language alignment: Major versions are coordinated across the Honua SDK family (JavaScript, Python, .NET) so a single semver line tells you what the contract is on every platform.

Advanced packaging. Downstream packagers can also produce a three-package split (@honua/sdk / @honua/sdk-esri-compat / @honua/honua-migrate) via npm run build:split-packages. This is an opt-in build target, not the default consumer install. See docs/split-packages.md if you are integrating with a downstream registry that needs the smaller surfaces.

Maintainers can verify the artifact consumers actually install with npm run verify:packed-sdk after the library and browser builds. The gate packs the root package, installs it offline into an isolated ESM project, imports every stable and experimental subpath, typechecks every shipped declaration target, and runs the packaged honua --help command. Temporary package and consumer directories are removed after both successful and failed runs.