docs: use published SDK peers for local setup

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
         with:
           path: shieldlabs-react
           persist-credentials: false
-      # @shieldlabs-ai/js is not on npm yet, so it is built from its repository next to this one.
+      # Test against the loader built from its main branch as well as this checkout's changes.
       - uses: actions/checkout@v5
         with:
           repository: ShieldLabs-ai/shieldlabs-js

.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Check that the tag matches package.json
         run: test "v$(node -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
       - run: npm ci
-      # Fails until @shieldlabs-ai/js is on npm: publish it first, then re-run this workflow.
+      # Install a published loader version matching this package's peer dependency range.
       - name: Install the published @shieldlabs-ai/js
         run: npm install --no-save "@shieldlabs-ai/js@$(node -p "require('./package.json').peerDependencies['@shieldlabs-ai/js']")"
       - run: npm run typecheck

.npmrc

@@ -1,7 +1,6 @@
 # Development settings only: npm never includes .npmrc in the published package.
-# @shieldlabs-ai/js, a peer dependency, is not on npm yet, so npm cannot install it by itself.
-# legacy-peer-deps: npm ci and npm install leave peer dependencies to you.
-# save-dev: `npm install --no-save <tarball>` still installs a local pack of @shieldlabs-ai/js.
-# Remove this file once @shieldlabs-ai/js 1.x is published (see CONTRIBUTING.md).
+# Keep npm ci consistent with the existing lockfile. See CONTRIBUTING.md for the separate
+# published-peer install, which overrides legacy-peer-deps without changing package files.
+# Saved installs default to development dependencies.
 legacy-peer-deps=true
 save-dev=true

CHANGELOG.md

@@ -6,6 +6,11 @@ All notable changes to `@shieldlabs-ai/react` are documented in this file. The f
 
 ## [Unreleased]
 
+### Changed
+
+- Contributor and example setup uses published ShieldLabs peers from npm. Local tarballs remain
+  optional for testing changes; a checkout of another SDK is no longer required.
+
 ## [1.0.0] - 2026-09-30
 
 ### Added

CONTRIBUTING.md

@@ -4,37 +4,29 @@ Thank you for improving the ShieldLabs React bindings.
 
 ## Set up
 
-You need Node.js 20 or later. The package builds on `@shieldlabs-ai/js`, a peer dependency. Until
-`@shieldlabs-ai/js` 1.0.0 is published to npm, work with a local pack of it, built from a working copy
-of [shieldlabs-js](https://github.com/ShieldLabs-ai/shieldlabs-js) next to this repository:
+You need Node.js 20 or later. Install the development tools and the published `@shieldlabs-ai/js`
+peer dependency from this repository's root. You do not need a checkout of another SDK.
 
 ```bash
-# in shieldlabs-js
-npm ci && npm run build && npm pack
-
-# in this repository
 npm ci
-npm install --no-save ../shieldlabs-js/shieldlabs-ai-js-1.0.0.tgz
+npm install --no-save --legacy-peer-deps=false '@shieldlabs-ai/js@^1.0.0'
 ```
 
-Repeat the last command after every `npm ci`. `--no-save` leaves `package.json` and
-`package-lock.json` unchanged. Never commit a `file:` dependency or a tarball. When the pack is
-missing, `npm run typecheck`, `npm run lint` and `npm run build` stop with these instructions
-(`scripts/check-core.mjs`).
+Repeat the second command after every `npm ci`, which removes the separately installed peer.
+`--no-save` leaves `package.json` and `package-lock.json` unchanged. If a check reports that the
+loader is missing, run that command again.
 
 ### Why the repository has an `.npmrc`
 
-npm installs required peer dependencies by itself. It would try to download `@shieldlabs-ai/js` from
-the registry, where it does not exist yet, so `npm ci` would fail. The committed `.npmrc` sets
-`legacy-peer-deps=true`, so `npm ci` and `npm install` leave peer dependencies to you, and
-`save-dev=true`, so `npm install --no-save <pack>` still installs the pack. Both settings apply
-only to work in this repository: npm never publishes `.npmrc`, and `package.json` lists
-`@shieldlabs-ai/js` as a required peer dependency, so npm installs it for the users of the package.
+The lockfile was created with `legacy-peer-deps=true`; the repository keeps that setting for
+`npm ci`. The separate install uses `--legacy-peer-deps=false` to resolve the published peer.
+`save-dev=true` makes saved installs development dependencies by default; `--no-save` above avoids
+saving anything. These settings apply only to this checkout: npm does not publish `.npmrc`.
 
-Once `@shieldlabs-ai/js` 1.0.0 is on npm, `npm install --no-save @shieldlabs-ai/js` works instead of the
-pack. To tidy up later, delete `.npmrc`, add `@shieldlabs-ai/js` to `devDependencies`, run
-`npm install` to refresh `package-lock.json`, and remove the pack steps from the CI workflow and
-from this file.
+CI still builds the loader from its `main` branch and tests the packed copy. The commands above
+instead test the published 1.x loader. To test a loader change, build and pack it in its own
+checkout, then replace the package name in the second command with the path to that tarball.
+Never commit a `file:` dependency or a tarball.
 
 ## Checks
 
@@ -48,10 +40,10 @@ npm test -- --coverage   # builds first; coverage must stay at 90 % or more
 npm run build
 ```
 
-To test with React 18 locally (afterwards, `npm ci` and the pack install bring back React 19):
+To test with React 18 locally (afterwards, repeat the setup commands to restore React 19):
 
 ```bash
-npm install --no-save react@18 react-dom@18 @types/react@18 @types/react-dom@18 ../shieldlabs-js/shieldlabs-ai-js-1.0.0.tgz
+npm install --no-save --legacy-peer-deps=false react@18 react-dom@18 @types/react@18 @types/react-dom@18 '@shieldlabs-ai/js@^1.0.0'
 npm run typecheck && npm test
 ```
 
@@ -75,8 +67,8 @@ all checks against the published `@shieldlabs-ai/js`, packs the package and publ
 with provenance, using the `NPM_TOKEN` repository secret. The publish job runs in the `npm`
 environment: add required reviewers to it in the repository settings to approve each release.
 
-Re-running the workflow is safe. When it stopped because `@shieldlabs-ai/js` was not on npm yet,
-publish it and re-run the workflow; a version that is already on npm is not published again.
+Re-running the workflow is safe: a version that is already on npm is not published again. If a
+release requires a newer loader version, publish that version before re-running the workflow.
 
 ## Security
 

README.md

@@ -496,10 +496,12 @@ clean. Calling a hook outside `ShieldLabsProvider` throws an `Error` that names
 
 ## Development
 
+From the repository root, install the development tools and the published loader. No sibling
+repository is required. Repeat the loader install after each `npm ci`.
+
 ```bash
 npm ci
-# Until @shieldlabs-ai/js is on npm, install a local pack of it (see CONTRIBUTING.md):
-npm install --no-save ../shieldlabs-js/shieldlabs-ai-js-1.0.0.tgz
+npm install --no-save --legacy-peer-deps=false '@shieldlabs-ai/js@^1.0.0'
 npm run typecheck
 npm run lint
 npm test -- --coverage   # builds first, then runs the tests

examples/vite/README.md

@@ -16,6 +16,8 @@ ID for five minutes in these examples), and each one is billable. The effect's c
 
 ## Run it
 
+From this example directory, install the published packages from npm:
+
 ```bash
 npm install
 cp .env.example .env   # then set VITE_SHIELDLABS_PUBLIC_KEY
@@ -32,17 +34,19 @@ development domain to see results in the [analytics dashboard](https://app.shiel
 
 ## Build against local copies of the packages
 
-Before `@shieldlabs-ai/react` and `@shieldlabs-ai/js` are on npm, with both repositories side by side:
+Use the published loader and a tarball of this checkout to test changes to the React binding:
 
 ```bash
-# in shieldlabs-js
-npm ci && npm run build && npm pack
-
-# in shieldlabs-react
+# repository root
 npm ci
-npm install --no-save ../shieldlabs-js/shieldlabs-ai-js-1.0.0.tgz
+npm install --no-save --legacy-peer-deps=false '@shieldlabs-ai/js@^1.0.0'
 npm run build && npm pack
 cd examples/vite
-npm install --no-save --no-package-lock ../../shieldlabs-ai-react-1.0.0.tgz ../../../shieldlabs-js/shieldlabs-ai-js-1.0.0.tgz
+npm install --no-save --no-package-lock ../../shieldlabs-ai-react-1.0.0.tgz
 npm run build
 ```
+
+Adjust the tarball filename if the package version changes. To test a loader change as well,
+build and pack it in its own checkout and pass that tarball to both install commands in place of
+the published loader (include it in the example install too). Never commit a tarball or a `file:`
+dependency.

scripts/check-core.mjs

@@ -18,11 +18,9 @@ if (typeof version !== 'string' || !version.startsWith('1.')) {
   console.error(
     [
       '@shieldlabs-ai/react needs @shieldlabs-ai/js 1.x, a peer dependency. ' + found,
-      'Until @shieldlabs-ai/js is on npm, build a pack from a working copy of shieldlabs-js next to this',
-      'repository and install it (repeat the install after every npm ci):',
+      'Install the published peer from this repository root (repeat after every npm ci):',
       '',
-      '  (cd ../shieldlabs-js && npm ci && npm run build && npm pack)',
-      '  npm install --no-save ../shieldlabs-js/shieldlabs-ai-js-1.0.0.tgz',
+      "  npm install --no-save --legacy-peer-deps=false '@shieldlabs-ai/js@^1.0.0'",
       '',
       'See CONTRIBUTING.md.',
     ].join('\n'),