create-honua-app 0.1.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "create-honua-app",
+  "version": "0.1.1",
+  "description": "Scaffold a Honua JavaScript SDK map application: Vite + TypeScript + MapLibre starters that connect and mount a source without hand-assembling peers",
+  "license": "Apache-2.0",
+  "author": "Honua",
+  "homepage": "https://honua-io.github.io/honua-sdk-js/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/honua-io/honua-sdk-js.git",
+    "directory": "packages/create-honua-app"
+  },
+  "bugs": {
+    "url": "https://github.com/honua-io/honua-sdk-js/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": ["gis", "geospatial", "maplibre", "typescript", "honua", "scaffold", "starter", "create-app"],
+  "type": "module",
+  "bin": {
+    "create-honua-app": "bin/create-honua-app.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": ["bin", "lib", "templates", "templates.manifest.json", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}

package/templates/react-ts/.stackblitzrc

@@ -0,0 +1,4 @@
+{
+  "installDependencies": true,
+  "startCommand": "npm run dev"
+}

package/templates/react-ts/README.md

@@ -0,0 +1,64 @@
+# Honua map app (React + TypeScript)
+
+A Vite + React + TypeScript starter for the [Honua JavaScript SDK](https://github.com/honua-io/honua-sdk-js). The app
+owns a plain `maplibre-gl` map and the SDK's React bridge mounts a discovered source onto it:
+
+```text
+connect → source → useMountedSource
+```
+
+## Run it
+
+```bash
+npm install
+npm run dev
+```
+
+The default lane serves a committed GeoServices fixture from the Vite dev server, so the first map needs no account,
+no API key, and no third-party network call. The same fixture is served by `npm run preview` after `npm run build`.
+
+## Point it at live data
+
+```bash
+VITE_HONUA_ENDPOINT=https://your-public-service.example/rest/services/example/FeatureServer/0 npm run dev
+```
+
+- `VITE_HONUA_ENDPOINT` — an anonymous, CORS-enabled GeoServices FeatureServer layer or OGC API Features landing page.
+- `VITE_HONUA_PROTOCOL` — `auto`, `geoservices-feature-service`, or `ogc-features` (default:
+  `geoservices-feature-service`, which matches the fixture).
+
+Do not put durable credentials in Vite environment variables: Vite embeds them in public JavaScript. Use an anonymous
+endpoint or a server-side proxy.
+
+## What to edit
+
+| File | Why |
+| --- | --- |
+| `src/App.tsx` | Connection, query, and the mounted-source hook. Change the query here. |
+| `src/main.tsx` | React root. `StrictMode` stays on: the SDK hooks are StrictMode-safe. |
+| `src/fixture-endpoint.ts` | The same-origin path the offline fixture is served on. |
+| `vite.config.ts` | The fixture service. Delete it once you point the app at a real endpoint. |
+
+`HonuaMapProvider` publishes an app-owned map to descendants when the map is created deeper in the tree; this starter
+passes the map to `useMountedSource` directly. Add `@vitejs/plugin-react` if you want React Fast Refresh — Vite
+compiles the JSX without it.
+
+## Dependencies
+
+`@honua/sdk-js`, `maplibre-gl`, and React are the packages this app calls directly. `@bufbuild/protobuf` and the two
+`@connectrpc` packages are the SDK's optional transport peers: they are installed and pinned here so the bundle builds
+without any peer-dependency assembly, and they are what a Honua-server connection uses.
+
+This starter pins **MapLibre GL JS 5.24.0**, the major the published `@honua/sdk-js` release accepts as an optional
+peer. MapLibre 6 is supported by the SDK source (`^5.0.0 || ^6.0.0`) and ships in the next release; upgrading to 6.x
+also means configuring MapLibre's ESM worker before the first map is created — under Vite, `setWorkerUrl` with
+`import maplibreWorkerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url"`.
+
+## Checks
+
+```bash
+npm run typecheck
+npm run build
+```
+
+The fixture data is synthetic demonstration data from the Honua SDK sample fixtures (Apache-2.0).

package/templates/react-ts/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.env.local
+*.log
+.DS_Store

package/templates/react-ts/fixtures/features.json

@@ -0,0 +1,46 @@
+{
+  "objectIdFieldName": "OBJECTID",
+  "geometryType": "esriGeometryPolygon",
+  "spatialReference": { "wkid": 4326 },
+  "fields": [
+    { "name": "OBJECTID", "type": "esriFieldTypeOID", "alias": "OBJECTID" },
+    { "name": "NAME", "type": "esriFieldTypeString", "alias": "Name" },
+    { "name": "STATUS", "type": "esriFieldTypeString", "alias": "Status" },
+    { "name": "CATEGORY", "type": "esriFieldTypeString", "alias": "Category" }
+  ],
+  "features": [
+    {
+      "attributes": {
+        "OBJECTID": 1,
+        "NAME": "Civic center service zone",
+        "STATUS": "Monitoring",
+        "CATEGORY": "Operations"
+      },
+      "geometry": {
+        "rings": [[[-157.866, 21.311], [-157.856, 21.311], [-157.856, 21.302], [-157.866, 21.302], [-157.866, 21.311]]]
+      }
+    },
+    {
+      "attributes": {
+        "OBJECTID": 2,
+        "NAME": "Harbor response district",
+        "STATUS": "Field review",
+        "CATEGORY": "Maritime"
+      },
+      "geometry": {
+        "rings": [[[-157.891, 21.304], [-157.879, 21.304], [-157.879, 21.294], [-157.891, 21.294], [-157.891, 21.304]]]
+      }
+    },
+    {
+      "attributes": {
+        "OBJECTID": 3,
+        "NAME": "Kakaako utility corridor",
+        "STATUS": "Ready",
+        "CATEGORY": "Infrastructure"
+      },
+      "geometry": {
+        "rings": [[[-157.87, 21.296], [-157.856, 21.296], [-157.856, 21.286], [-157.87, 21.286], [-157.87, 21.296]]]
+      }
+    }
+  ]
+}

package/templates/react-ts/fixtures/layer.json

@@ -0,0 +1,34 @@
+{
+  "currentVersion": 11.3,
+  "id": 0,
+  "name": "Honolulu operations areas",
+  "type": "Feature Layer",
+  "description": "The same three synthetic First Map polygons exposed by the OGC API Features projection.",
+  "copyrightText": "Copyright Honua contributors; synthetic demonstration data.",
+  "provenance": {
+    "source": "honua-sdk-js test/fixtures/honua-quickstart-demo",
+    "retrievedAt": "2026-07-13T00:00:00.000Z"
+  },
+  "geometryType": "esriGeometryPolygon",
+  "objectIdField": "OBJECTID",
+  "maxRecordCount": 25,
+  "advancedQueryCapabilities": {
+    "supportsPagination": true,
+    "supportsReturningQueryExtent": false,
+    "supportsStatistics": false
+  },
+  "extent": {
+    "xmin": -157.891,
+    "ymin": 21.286,
+    "xmax": -157.856,
+    "ymax": 21.311,
+    "spatialReference": { "wkid": 4326 }
+  },
+  "fields": [
+    { "name": "OBJECTID", "type": "esriFieldTypeOID", "alias": "OBJECTID" },
+    { "name": "NAME", "type": "esriFieldTypeString", "alias": "Name" },
+    { "name": "STATUS", "type": "esriFieldTypeString", "alias": "Status" },
+    { "name": "CATEGORY", "type": "esriFieldTypeString", "alias": "Category" }
+  ],
+  "capabilities": "Query"
+}

package/templates/react-ts/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Honua map app (React)</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-ts/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "honua-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.13.0",
+    "@connectrpc/connect": "2.1.2",
+    "@connectrpc/connect-web": "2.1.2",
+    "@honua/sdk-js": "0.1.2-beta.0",
+    "maplibre-gl": "5.24.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "typescript": "5.9.3",
+    "vite": "8.2.0"
+  }
+}

package/templates/react-ts/src/App.tsx

@@ -0,0 +1,153 @@
+import { createHonua } from "@honua/sdk-js";
+import type { ConnectProtocolHint, Source } from "@honua/sdk-js";
+import { useMountedSource } from "@honua/sdk-js/react";
+import * as maplibregl from "maplibre-gl";
+import type { RefObject } from "react";
+import { useEffect, useRef, useState } from "react";
+
+import { FIXTURE_LAYER_PATH } from "./fixture-endpoint.js";
+
+/** Offline basemap: the starter never fetches third-party tiles on its default lane. */
+const BASEMAP_STYLE = {
+  version: 8 as const,
+  sources: {},
+  layers: [{ id: "background", type: "background" as const, paint: { "background-color": "#0e1a17" } }],
+};
+
+const INITIAL_VIEW = { center: [-157.873, 21.2985] as [number, number], zoom: 11.4 };
+
+/** Bounded row budget. The bridge reports truncation instead of hiding it. */
+const MAX_FEATURES = 250;
+
+const QUERY = { returnGeometry: true, pagination: { limit: MAX_FEATURES } };
+
+const configuredEndpoint = import.meta.env.VITE_HONUA_ENDPOINT?.trim();
+const configuredProtocol = import.meta.env.VITE_HONUA_PROTOCOL?.trim();
+
+const ENDPOINT =
+  configuredEndpoint && configuredEndpoint.length > 0
+    ? configuredEndpoint
+    : new URL(FIXTURE_LAYER_PATH, window.location.origin).toString();
+const PROTOCOL = (
+  configuredProtocol && configuredProtocol.length > 0 ? configuredProtocol : "geoservices-feature-service"
+) as ConnectProtocolHint;
+const DATA_LANE = configuredEndpoint && configuredEndpoint.length > 0 ? "Live endpoint" : "Committed fixture";
+
+interface ConnectionState {
+  readonly source: Source | null;
+  readonly sourceId?: string;
+  readonly protocol?: string;
+  readonly error?: string;
+}
+
+/** The app owns its MapLibre map, exactly like a `@vis.gl/react-maplibre` `<Map>` would. */
+function useExternalMap(): { containerRef: RefObject<HTMLDivElement | null>; map: maplibregl.Map | null } {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [map, setMap] = useState<maplibregl.Map | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const created = new maplibregl.Map({
+      container,
+      style: BASEMAP_STYLE,
+      center: INITIAL_VIEW.center,
+      zoom: INITIAL_VIEW.zoom,
+      attributionControl: false,
+    });
+    setMap(created);
+    return () => {
+      setMap(null);
+      created.remove();
+    };
+  }, []);
+
+  return { containerRef, map };
+}
+
+/** Connect once per effect run and publish the discovered source. */
+function useHonuaSource(): ConnectionState {
+  const [state, setState] = useState<ConnectionState>({ source: null });
+
+  useEffect(() => {
+    const honua = createHonua();
+    let cancelled = false;
+    void (async () => {
+      try {
+        const connection = await honua.connect(
+          { url: ENDPOINT, protocol: PROTOCOL },
+          { authorizationScopeFingerprint: "anonymous-public" },
+        );
+        const inspection = await connection.inspect();
+        const sourceId = inspection.defaultSourceId ?? inspection.sources[0]?.descriptor.id;
+        if (!sourceId) throw new Error("The endpoint advertised no queryable source.");
+        if (cancelled) return;
+        setState({ source: connection.source(sourceId), sourceId, protocol: inspection.protocol });
+      } catch (error) {
+        if (!cancelled) setState({ source: null, error: error instanceof Error ? error.message : String(error) });
+      }
+    })();
+    return () => {
+      cancelled = true;
+      void honua.dispose();
+    };
+  }, []);
+
+  return state;
+}
+
+export function App() {
+  const { containerRef, map } = useExternalMap();
+  const connection = useHonuaSource();
+  const mounted = useMountedSource(map, connection.source, { query: QUERY, fitBounds: true });
+
+  const failure = connection.error ?? (mounted.error instanceof Error ? mounted.error.message : undefined);
+  const status = failure
+    ? `The workflow stopped: ${failure}`
+    : mounted.handle
+      ? "The queried source is mounted through the React bridge."
+      : "Connecting, discovering, and mounting…";
+
+  return (
+    <main className="app">
+      <section className="panel" aria-label="Workflow">
+        <p className="eyebrow">Honua JavaScript SDK · React</p>
+        <h1 className="title">connect → source → useMountedSource</h1>
+        <output className="status" aria-live="polite">
+          {status}
+        </output>
+        <dl className="facts">
+          <div>
+            <dt>Data lane</dt>
+            <dd>{DATA_LANE}</dd>
+          </div>
+          <div>
+            <dt>Endpoint</dt>
+            <dd>{ENDPOINT}</dd>
+          </div>
+          <div>
+            <dt>Protocol</dt>
+            <dd>{connection.protocol ?? "—"}</dd>
+          </div>
+          <div>
+            <dt>Source</dt>
+            <dd>{connection.sourceId ?? "—"}</dd>
+          </div>
+          <div>
+            <dt>Strategy</dt>
+            <dd>{mounted.diagnostics?.strategy ?? "—"}</dd>
+          </div>
+          <div>
+            <dt>Features</dt>
+            <dd id="fact-features">{mounted.diagnostics?.featureCount ?? "—"}</dd>
+          </div>
+        </dl>
+        <p className="hint">
+          Edit <code>src/App.tsx</code> to change the query, or set <code>VITE_HONUA_ENDPOINT</code> to run the same
+          components against a live public service.
+        </p>
+      </section>
+      <div className="map" ref={containerRef} role="application" aria-label="Mounted map" />
+    </main>
+  );
+}

package/templates/react-ts/src/fixture-endpoint.ts

@@ -0,0 +1,9 @@
+/**
+ * Same-origin path the committed fixture service answers on.
+ *
+ * `vite.config.ts` serves the fixture here in both `npm run dev` and
+ * `npm run preview`, and `src/main.ts` connects here whenever no live endpoint
+ * is configured. Keeping the path in one module is what makes the default lane
+ * work with no account, no key, and no third-party network call.
+ */
+export const FIXTURE_LAYER_PATH = "/fixture/rest/services/honua-demo/FeatureServer/0";

package/templates/react-ts/src/main.tsx

@@ -0,0 +1,18 @@
+import "maplibre-gl/dist/maplibre-gl.css";
+
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./App.js";
+import "./styles.css";
+
+const container = document.getElementById("root");
+if (!container) throw new Error("Missing #root element");
+
+// StrictMode double-invokes effects in development. The SDK's React hooks are
+// StrictMode-safe, so the mount/unmount/mount cycle never leaks a map source.
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/react-ts/src/styles.css

@@ -0,0 +1,149 @@
+:root {
+  --surface: #f6f7f5;
+  --panel: #ffffff;
+  --ink: #10201b;
+  --muted: #5c6b66;
+  --line: #d9e0dc;
+  --accent: #0f766e;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --surface: #0b1210;
+    --panel: #111a17;
+    --ink: #e8f0ec;
+    --muted: #93a49e;
+    --line: #23322c;
+    --accent: #5eead4;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--surface);
+  color: var(--ink);
+  font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+.app {
+  display: grid;
+  grid-template-columns: minmax(280px, 360px) 1fr;
+  gap: 16px;
+  padding: 16px;
+  height: 100vh;
+}
+
+@media (max-width: 820px) {
+  .app {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto minmax(320px, 1fr);
+    height: auto;
+  }
+}
+
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 20px;
+  overflow-y: auto;
+}
+
+.eyebrow {
+  margin: 0;
+  color: var(--accent);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.title {
+  margin: 6px 0 12px;
+  font-size: 18px;
+  line-height: 1.3;
+}
+
+.status {
+  margin: 0 0 16px;
+  color: var(--muted);
+}
+
+.stages {
+  list-style: none;
+  margin: 0 0 20px;
+  padding: 0;
+  display: grid;
+  gap: 6px;
+}
+
+.stages li {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  font-size: 13px;
+}
+
+.stages li[data-state="running"] {
+  border-color: var(--accent);
+}
+
+.stages li[data-state="done"] .stage-state {
+  color: var(--accent);
+}
+
+.stages li[data-state="failed"] .stage-state {
+  color: #dc2626;
+}
+
+.stage-state {
+  color: var(--muted);
+}
+
+.facts {
+  display: grid;
+  gap: 8px;
+  margin: 0 0 16px;
+}
+
+.facts div {
+  display: grid;
+  grid-template-columns: 96px 1fr;
+  gap: 10px;
+  font-size: 13px;
+}
+
+.facts dt {
+  color: var(--muted);
+}
+
+.facts dd {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.hint {
+  margin: 0;
+  color: var(--muted);
+  font-size: 13px;
+}
+
+code {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+  font-size: 12px;
+}
+
+.map {
+  min-height: 360px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  overflow: hidden;
+}

package/templates/react-ts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "allowSyntheticDefaultImports": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "vite.config.ts"]
+}

package/templates/react-ts/vite.config.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { fileURLToPath } from "node:url";
+
+import { type Plugin, defineConfig } from "vite";
+
+import { FIXTURE_LAYER_PATH } from "./src/fixture-endpoint.js";
+
+function fixtureDocument(name: string): string {
+  return readFileSync(fileURLToPath(new URL(`./fixtures/${name}`, import.meta.url)), "utf8");
+}
+
+/**
+ * Deterministic, offline GeoServices FeatureServer fixture.
+ *
+ * The starter's green path must never depend on a third-party endpoint, so the
+ * dev and preview servers answer the two routes the SDK's GeoServices adapter
+ * needs: the layer description and its bounded query. Point
+ * `VITE_HONUA_ENDPOINT` at a real service to run the same code against live data.
+ */
+function honuaFixtureService(): Plugin {
+  const layer = fixtureDocument("layer.json");
+  const features = fixtureDocument("features.json");
+  const middleware = (request: IncomingMessage, response: ServerResponse, next: () => void): void => {
+    const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+    let body: string | undefined;
+    if (pathname === FIXTURE_LAYER_PATH) body = layer;
+    else if (pathname === `${FIXTURE_LAYER_PATH}/query`) body = features;
+    if (body === undefined) {
+      next();
+      return;
+    }
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.setHeader("cache-control", "no-store");
+    response.end(body);
+  };
+  return {
+    name: "honua-fixture-service",
+    configureServer(server) {
+      server.middlewares.use(middleware);
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use(middleware);
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [honuaFixtureService()],
+});

package/templates/vanilla-ts/.stackblitzrc

@@ -0,0 +1,4 @@
+{
+  "installDependencies": true,
+  "startCommand": "npm run dev"
+}