Install from GitHub

The SDK lives in the Molecule OS monorepo (packages/sdk) and is meant to be consumed from other SaaSLabs repos — the ServiceAgent site, Helpwise, a demo app. There are two GitHub-native ways to do that; this page covers both and the sharp edges of each.

Option A — GitHub Packages (recommended)

GitHub Packages is a private npm registry attached to the repo. A release workflow builds the SDK and publishes it; consuming repos install it like any scoped package.

1. Publish (in this repo)

A tag-triggered GitHub Actions workflow builds dist/ and publishes. It already exists at .github/workflows/publish-sdk.yml:

name: Publish SDK
on:
  push:
    tags: ["sdk-v*"]        # e.g. git tag sdk-v0.1.0 && git push --tags
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write        # lets GITHUB_TOKEN publish to GitHub Packages
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://npm.pkg.github.com
      - run: pnpm install --frozen-lockfile
      - run: pnpm -F @molecule/sdk build
      - run: pnpm -F @molecule/sdk publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Cut a release by tagging: git tag sdk-v0.1.0 && git push origin sdk-v0.1.0.

2. Consume (in the other repo)

Add an .npmrc that routes the scope to GitHub and supplies a token with read:packages:

@molecule:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then install:

export GITHUB_TOKEN=ghp_your_read_packages_token
pnpm add @molecule/sdk

export GITHUB_TOKEN=ghp_your_read_packages_token
npm install @molecule/sdk

export GITHUB_TOKEN=ghp_your_read_packages_token
yarn add @molecule/sdk

Option B — git dependency (single-repo shortcut)

If you don't want a registry, you can depend on the built package over git — but only because the SDK is self-contained (no workspace:* deps) and ships compiled JS + .d.ts. The catch from the warning above still holds: a plain git URL installs the repo root, not packages/sdk. Two ways around it:

• gitpkg — resolves a subdirectory of a git repo into an installable tarball:

  {
    "dependencies": {
      "@molecule/sdk": "https://gitpkg.now.sh/prateekjain98/molecule-os/packages/sdk?main"
    }
  }

  The referenced commit must contain a built packages/sdk/dist/ (the tag workflow's artifact, or commit dist/ on a release branch).

• Split repo / mirror — publish just packages/sdk to its own repo (e.g. with git subtree split), then pnpm add github:saaslabs/molecule-sdk#v0.1.0. Cleanest for a git-only flow, at the cost of a second repo to keep in sync.

For a team that ships regularly, Option A is less friction — versioned, cacheable, and no build artifacts committed to git.

Why not raw .ts from the monorepo?

The other workspace packages export ./src/index.ts directly and rely on the monorepo's allowImportingTsExtensions / .ts-rewriting tsconfig. That does not survive being imported by a foreign repo. @molecule/sdk is deliberately different: a single self-contained source file, compiled to dist/ with declarations, so consumers get plain ESM + types and none of the monorepo's build assumptions leak out.