From 28661cbb069cae58d321c50082ad9da97635d20c Mon Sep 17 00:00:00 2001 From: EgorMajj <91486022+EgorMajj@users.noreply.github.com> Date: Sat, 3 Oct 2026 01:20:01 +0300 Subject: [PATCH 1/2] docs: use published packages for contributor setup --- .github/workflows/ci.yml | 2 +- .github/workflows/release.yml | 2 +- .npmrc | 7 +++--- CHANGELOG.md | 5 ++++ CONTRIBUTING.md | 44 ++++++++++++++--------------------- README.md | 6 +++-- examples/vite/README.md | 18 ++++++++------ 7 files changed, 43 insertions(+), 41 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fe1fbce..750a5ff 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e8338ab..6f8d7b4 100644 --- a/.github/workflows/release.yml +++ b/.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 diff --git a/.npmrc b/.npmrc index 45da7c1..a897053 100644 --- a/.npmrc +++ b/.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 ` 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f746a2..6ecbdc8 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f258de..7195255 100644 --- a/CONTRIBUTING.md +++ b/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 ` 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 diff --git a/README.md b/README.md index 503d76c..5330fa5 100644 --- a/README.md +++ b/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 diff --git a/examples/vite/README.md b/examples/vite/README.md index 355a331..49596f2 100644 --- a/examples/vite/README.md +++ b/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. From 88b3377515cbe2b46756557a4c7d07cbc3092fd3 Mon Sep 17 00:00:00 2001 From: EgorMajj <91486022+EgorMajj@users.noreply.github.com> Date: Sat, 3 Oct 2026 01:30:17 +0300 Subject: [PATCH 2/2] docs: use registry install in missing-peer guidance --- scripts/check-core.mjs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/scripts/check-core.mjs b/scripts/check-core.mjs index 77c7eea..448a642 100644 --- a/scripts/check-core.mjs +++ b/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'),