feat!: initial v2 with export (#416)

Initial stab at packaging things correctly for use in downstreams.
Heavily constructed by Claude.

Author: gadomski

.env.example

@@ -1,6 +1,3 @@
-# STAC Natural Query API endpoint
-VITE_STAC_NATURAL_QUERY_API=https://api.stac-semantic-search.k8s.labs.ds.io
-
 # Base URL for STAC Browser external links
 # Default: https://radiantearth.github.io/stac-browser/#/external/
 VITE_STAC_BROWSER_URL="https://radiantearth.github.io/stac-browser/#/external/"

.github/workflows/release.yaml

@@ -22,7 +22,7 @@ jobs:
           cache: yarn
       - run: yarn install
       - run: yarn playwright install
-      - run: yarn build
       - run: yarn test
+      - run: yarn build:lib
       - name: Read version and publish
         run: npm publish --access public

README.md

@@ -19,6 +19,63 @@ Includes:
 </picture>
 <!-- markdownlint-enable MD033 -->
 
+## Deploying
+
+There's two ways to deploy your own version of **stac-map**:
+
+- [Build-time configuration](#build-time-configuration)
+- [React component](#react-component)
+
+### Build-time configuration
+
+If you only need to customize a few things (default href or auth), you can simply clone this repository and configure the app with environment variables.
+See [deploy.yaml](./.github/workflows/deploy.yaml) for a (drop-dead simple) example of deploying this application as a static site via Github Pages.
+The environment variables are:
+
+| Variable              | Description                        | Default            |
+| --------------------- | ---------------------------------- | ------------------ |
+| `VITE_BASE_PATH`      | URL path prefix (e.g., `/my-app/`) | `/stac-map/`       |
+| `VITE_DEFAULT_HREF`   | STAC resource to load on startup   | None (shows intro) |
+| `VITE_AUTH_AUTHORITY` | The OIDC authority to use for auth | None               |
+| `VITE_AUTH_CLIENT_ID` | The OIDC client id to use for auth | None               |
+
+Example:
+
+```shell
+VITE_BASE_PATH=/ VITE_DEFAULT_HREF=https://my-stac-api.com yarn build
+```
+
+Or create a `.env` file:
+
+```shell
+VITE_BASE_PATH=/
+VITE_DEFAULT_HREF=https://my-stac-api.com
+```
+
+Then run `yarn build` and deploy the `dist/` directory to your static hosting provider.
+
+### React component
+
+For more flexible configuration, we provide a `StacMap` React component via [@developmentseed/stac-map](https://www.npmjs.com/package/@developmentseed/stac-map).
+To use it:
+
+```javascript
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { StacMap } from "@development-seed/stac-map";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <StacMap />
+  </StrictMode>
+);
+```
+
+See [src/main.tsx](./src/main.tsx) for a real-world example of using the component (it's what drives https://developmentseed.org/stac-map).
+
+> [!NOTE]
+> We plan to provide JSDocs for all available properties before releasing v2 of **stac-map**
+
 ## Development
 
 Get [yarn](https://yarnpkg.com/), then:
@@ -53,34 +110,3 @@ We use Github [Pull Requests](https://github.com/developmentseed/stac-map/pulls)
 
 We use [release-please](https://github.com/googleapis/release-please) to create [releases](https://github.com/developmentseed/stac-map/releases).
 This requires our commit messages to conform to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
-
-## Deploying
-
-See [deploy.yaml](./.github/workflows/deploy.yaml) for a (drop-dead simple) example of deploying this application as a static site via Github Pages.
-
-### White-label deployment
-
-You can deploy your own customized version of stac-map using environment variables:
-
-| Variable              | Description                        | Default            |
-| --------------------- | ---------------------------------- | ------------------ |
-| `VITE_BASE_PATH`      | URL path prefix (e.g., `/my-app/`) | `/stac-map/`       |
-| `VITE_DEFAULT_HREF`   | STAC resource to load on startup   | None (shows intro) |
-| `VITE_AUTH_AUTHORITY` | The OIDC authority to use for auth | None               |
-| `VITE_AUTH_CLIENT_ID` | The OIDC client id to use for auth | None               |
-
-Example:
-
-```shell
-VITE_BASE_PATH=/ VITE_DEFAULT_HREF=https://my-stac-api.com yarn build
-```
-
-Or create a `.env` file:
-
-```shell
-VITE_BASE_PATH=/
-VITE_DEFAULT_HREF=https://my-stac-api.com
-```
-
-Then run `yarn build` and deploy the `dist/` directory to your static hosting provider.
-For an example of white-labeling **stac-map**, see https://github.com/gadomski/eoapi.stac-map.io.

package.json

@@ -27,6 +27,8 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "build-preview": "tsc -b && vite build --base=/",
+    "build:lib": "vite build --config vite.lib.config.ts",
+    "prepublishOnly": "yarn build:lib",
     "lint": "eslint .",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
@@ -35,18 +37,15 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.3.5",
-    "@chakra-ui/react": "^3.35.0",
     "@deck.gl/core": "^9.3.1",
     "@deck.gl/layers": "^9.3.1",
     "@deck.gl/mapbox": "^9.3.1",
     "@developmentseed/deck.gl-geotiff": "^0.5.0",
     "@developmentseed/proj": "^0.5.0",
     "@devseed-ui/collecticons-chakra": "^4.0.0",
     "@duckdb/duckdb-wasm": "^1.32.0",
-    "@emotion/react": "^11.13.5",
     "@geoarrow/deck.gl-layers": "^0.3.2",
     "@geoarrow/geoarrow-js": "github:smohiudd/geoarrow-js#feature/wkb",
-    "@tanstack/react-query": "^5.100.5",
     "@turf/bbox": "^7.3.5",
     "@turf/bbox-polygon": "^7.3.5",
     "@turf/boolean-valid": "^7.3.5",
@@ -55,26 +54,24 @@
     "deck.gl": "^9.3.1",
     "duckdb-wasm-kit": "^0.1.38",
     "geotiff-geokeys-to-proj4": "^2024.4.13",
-    "maplibre-gl": "^5.24.0",
     "next-themes": "^0.4.3",
-    "oidc-client-ts": "^3.5.0",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
     "react-error-boundary": "^6.1.1",
     "react-icons": "^5.6.0",
-    "react-map-gl": "^8.1.1",
     "react-markdown": "^10.1.0",
-    "react-oidc-context": "^3.3.1",
     "shiki": "^4.0.2",
     "stac-ts": "^1.0.5",
     "stac-wasm": "^0.1.0",
     "zustand": "^5.0.12"
   },
   "devDependencies": {
+    "@chakra-ui/react": "^3.35.0",
+    "@emotion/react": "^11.13.5",
     "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.58.7",
+    "@tanstack/react-query": "^5.100.5",
     "@types/geojson": "^7946.0.16",
     "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.1.2",
+    "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/browser": "^4.1.5",
     "@vitest/browser-playwright": "^4.1.5",
@@ -84,21 +81,62 @@
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^17.5.0",
+    "maplibre-gl": "^5.24.0",
+    "oidc-client-ts": "^3.5.0",
     "playwright": "^1.59.1",
     "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "^4.1.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-map-gl": "^8.1.1",
+    "react-oidc-context": "^3.3.1",
     "rollup": "^4.60.2",
     "semantic-release": "^25.0.3",
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.59.1",
     "vite": "^8.0.10",
+    "vite-plugin-dts": "^5.0.0",
     "vite-plugin-top-level-await": "^1.5.0",
     "vite-plugin-wasm": "^3.6.0",
     "vitest": "^4.1.5",
     "vitest-browser-react": "^2.2.0"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
-  "main": "eslint.config.js",
+  "main": "./dist/lib.js",
+  "module": "./dist/lib.js",
+  "types": "./dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "peerDependencies": {
+    "@chakra-ui/react": "^3.35.0",
+    "@emotion/react": "^11.13.5",
+    "@tanstack/react-query": "^5.100.5",
+    "maplibre-gl": "^5.24.0",
+    "oidc-client-ts": "^3.5.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-map-gl": "^8.1.1",
+    "react-oidc-context": "^3.3.1"
+  },
+  "peerDependenciesMeta": {
+    "oidc-client-ts": {
+      "optional": true
+    },
+    "react-oidc-context": {
+      "optional": true
+    }
+  },
   "directories": {
     "doc": "docs",
     "test": "tests"

release-please-config.json

@@ -3,7 +3,9 @@
     ".": {
       "changelog-path": "CHANGELOG.md",
       "release-type": "node",
-      "include-component-in-tag": false
+      "include-component-in-tag": false,
+      "prerelease": true,
+      "prerelease-type": "alpha"
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

src/app.tsx

@@ -1,8 +1,7 @@
 import { AbsoluteCenter, Box, Center, FileUpload } from "@chakra-ui/react";
 import { useDuckDb } from "duckdb-wasm-kit";
-import { useEffect } from "react";
+import { type ReactNode, useEffect } from "react";
 import { ErrorBoundary } from "react-error-boundary";
-import Footer from "./components/footer";
 import Map from "./components/map";
 import Overlay from "./components/overlay";
 import { ErrorBoundaryAlert } from "./components/ui/error-alert";
@@ -27,28 +26,11 @@ function OverlayFallback({ error }: { error: unknown }) {
   );
 }
 
-export default function App() {
-  const href = useStore((state) => state.href);
-  const setHref = useStore((state) => state.setHref);
+export default function App({ footer }: { footer?: ReactNode }) {
   const setUploadedFile = useStore((state) => state.setUploadedFile);
   const setConnection = useStore((state) => state.setConnection);
   const { db } = useDuckDb();
 
-  useEffect(() => {
-    if (href && new URLSearchParams(location.search).get("href") !== href)
-      history.pushState(null, "", "?href=" + href);
-    else history.replaceState(null, "", null);
-  }, [href]);
-
-  useEffect(() => {
-    function handlePopState() {
-      setHref(new URLSearchParams(location.search).get("href"));
-    }
-    window.addEventListener("popstate", handlePopState);
-
-    return () => window.removeEventListener("popstate", handlePopState);
-  }, [setHref]);
-
   useEffect(() => {
     if (db) {
       (async () => {
@@ -92,7 +74,7 @@ export default function App() {
       <ErrorBoundary FallbackComponent={OverlayFallback}>
         <Overlay />
       </ErrorBoundary>
-      <Footer />
+      {footer}
     </>
   );
 }

src/components/footer.tsx

@@ -3,10 +3,13 @@ import { CloseButton, Dialog, HStack, Link, Portal } from "@chakra-ui/react";
 import { CollecticonBrandDevelopmentSeed2 } from "@devseed-ui/collecticons-chakra";
 import { LuGithub, LuHeart } from "react-icons/lu";
 import Markdown from "react-markdown";
-import changelog from "../../CHANGELOG.md?raw";
-import { version } from "../../package.json";
 
-export default function Footer() {
+export interface FooterProps {
+  version: string;
+  changelog?: string;
+}
+
+export default function Footer({ version, changelog }: FooterProps) {
   return (
     <HStack
       position={"absolute"}
@@ -35,11 +38,13 @@ export default function Footer() {
                   </Link>
                 </Dialog.Title>
               </Dialog.Header>
-              <Dialog.Body>
-                <Prose>
-                  <Markdown>{changelog}</Markdown>
-                </Prose>
-              </Dialog.Body>
+              {changelog && (
+                <Dialog.Body>
+                  <Prose>
+                    <Markdown>{changelog}</Markdown>
+                  </Prose>
+                </Dialog.Body>
+              )}
               <Dialog.CloseTrigger asChild>
                 <CloseButton size="sm" />
               </Dialog.CloseTrigger>

src/components/header.tsx

@@ -1,12 +1,14 @@
 import { Button, HStack } from "@chakra-ui/react";
+import { useAuthEnabled } from "../contexts/auth-enabled";
 import { Examples } from "./examples";
 import HrefInput from "./href-input";
-import { authConfig, UserButton } from "./ui/auth";
+import { UserButton } from "./ui/auth";
 import { ColorModeButton } from "./ui/color-mode";
 import { ProjectionButton } from "./ui/projection";
 import { SettingsButton } from "./ui/settings";
 
 export default function Header() {
+  const authEnabled = useAuthEnabled();
   return (
     <HStack pointerEvents={"auto"}>
       <HrefInput />
@@ -18,7 +20,7 @@ export default function Header() {
       <ProjectionButton variant={"surface"} />
       <ColorModeButton variant={"surface"} />
       <SettingsButton variant={"surface"} />
-      {authConfig && <UserButton variant={"surface"} />}
+      {authEnabled && <UserButton variant={"surface"} />}
     </HStack>
   );
 }