Installation & NPM Authentication

@bloomsparkagency/core and its sub-packages are published privately via GitHub Packages. You must configure your package manager to authenticate with the GitHub registry before installing.

---

🔑 NPM Registry Authentication

Create or update the .npmrc file in your project root (or globally at ~/.npmrc):

@bloomsparkagency:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
always-auth=true

Authentication Modes

1. Developer Machine (Local): Generate a GitHub Fine-Grained Personal Access Token (PAT) from Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens:
   • Repository Access: Only select repositories containing the BloomSpark mapping code.
   • Permissions: Set read:packages to Access: Read-only.
   • Export it as an environment variable in your terminal (or define it in a local .env):

     export NODE_AUTH_TOKEN=github_pat_xxxxxx

2. GitHub Actions CI (Preferred): GitHub Actions automatically provides a short-lived GITHUB_TOKEN secret. You can pipe this directly in your workflow steps:

   - name: Install dependencies
     run: pnpm install --frozen-lockfile
     env:
       NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. External CI Providers (AWS CodeBuild, GitLab CI, OIDC): For external servers, configure a repository secret containing a classic/fine-grained PAT with read:packages scope, and export it as NODE_AUTH_TOKEN during the container run step.

---

📦 Package Installation

Installing the Monorepo Suite

Using pnpm (highly recommended for workspaces):

pnpm add @bloomsparkagency/core @bloomsparkagency/ui @bloomsparkagency/editor @bloomsparkagency/imdf @bloomsparkagency/rtls @bloomsparkagency/wayfinding @bloomsparkagency/pmtiles @bloomsparkagency/theme @bloomsparkagency/verticals

Using npm:

npm install @bloomsparkagency/core @bloomsparkagency/ui @bloomsparkagency/editor @bloomsparkagency/imdf @bloomsparkagency/rtls @bloomsparkagency/wayfinding @bloomsparkagency/pmtiles @bloomsparkagency/theme @bloomsparkagency/verticals

Using yarn:

yarn add @bloomsparkagency/core @bloomsparkagency/ui @bloomsparkagency/editor @bloomsparkagency/imdf @bloomsparkagency/rtls @bloomsparkagency/wayfinding @bloomsparkagency/pmtiles @bloomsparkagency/theme @bloomsparkagency/verticals

---

🧩 Peer Dependencies

The SDK relies on key front-end peer dependencies. Ensure your project has the following packages installed:

{
  "peerDependencies": {
    "react": ">=18.0.0 <20.0.0",
    "react-dom": ">=18.0.0 <20.0.0",
    "maplibre-gl": "^4.0.0 || ^5.0.0"
  }
}

Import MapLibre's styles in your application's entrypoint (e.g., main.tsx or _app.tsx):

import 'maplibre-gl/dist/maplibre-gl.css';