@pxlabz/tracey-react 0.0.1

package/README.md

@@ -0,0 +1,83 @@
+# @pxlabz/tracey-react
+
+React SDK for Tracey feedback widgets and announcements.
+
+## Distribution model
+
+- Repository stays private on GitHub.
+- SDK package is published publicly to npm as `@pxlabz/tracey-react`.
+- Only `dist/` is published (`files: ["dist"]` in `package.json`).
+
+## Publish configuration
+
+`package.json` uses:
+
+- `publishConfig.access = "public"`
+- `publishConfig.registry = "https://registry.npmjs.org/"`
+
+## Release cadence (automatic on `main`)
+
+Releases are triggered automatically on pushes to `main`.
+
+The GitHub Actions workflow is:
+
+- `.github/workflows/publish-react-sdk.yml`
+
+The workflow first checks if files under `packages/react-sdk/` changed in that push range.
+
+- If no SDK files changed, it exits without publishing.
+- If SDK files changed, it checks npm for the current package version:
+  - If that version already exists on npm, the workflow fails and asks for a version bump.
+  - If it does not exist, it runs type-check, tests, build, `npm publish --dry-run`, and `npm publish`.
+
+The change detection logic is in:
+
+- `scripts/should-publish-react-sdk.sh`
+
+### Required CI secret
+
+- `NPM_TOKEN`: npm automation token with publish access to `@pxlabz/tracey-react`.
+
+## Release checklist
+
+1. Bump `version` in `packages/react-sdk/package.json`.
+2. Run local checks:
+   - `bun run --cwd packages/react-sdk type-check`
+   - `bun run --cwd packages/react-sdk test`
+   - `bun run --cwd packages/react-sdk build`
+   - `cd packages/react-sdk && npm publish --dry-run`
+3. Commit and push to `main`.
+4. Confirm publish job succeeds in GitHub Actions.
+5. Validate install in a clean consumer app:
+   - `npm i @pxlabz/tracey-react@X.Y.Z`
+
+## Rollback strategy
+
+If a bad version is published:
+
+1. Deprecate that version:
+   - `npm deprecate @pxlabz/tracey-react@X.Y.Z "Use X.Y.Z+1 due to <reason>"`
+2. Publish a patch release with the fix.
+
+## Private distribution alternatives
+
+If private package distribution is required later, two supported options are:
+
+1. GitHub Packages (`https://npm.pkg.github.com`)
+   - Best for internal org users.
+   - Requires GitHub package auth/token and package access grants.
+   - Package scope usually needs to align with GitHub owner namespace.
+2. npm private package
+   - Better external UX than GitHub Packages for mixed audiences.
+   - Requires npm private package billing/access management.
+
+## Troubleshooting
+
+### `Cannot find module 'ajv/dist/core'` in CI
+
+This build path uses `vite-plugin-dts` and `@microsoft/api-extractor`.
+Root `devDependencies.ajv` is pinned to `8.13.0` to keep resolver output compatible in CI.
+
+Quick verification command:
+
+- `cd packages/react-sdk && node -e "require('@microsoft/api-extractor')"`