feat(ci): add pkg.pr.new canary releases

.github/workflows/canary.yaml

@@ -0,0 +1,48 @@
+name: Canary Release
+
+# Publishes a preview build of @raystack/apsara to pkg.pr.new on every push
+# to a pull request or to main, so changes can be installed and tested
+# before a real npm release. See https://pkg.pr.new
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions: {}
+
+# --comment=update edits a single comment per PR; cancel superseded runs so a
+# stale run can't finish after a newer one and leave outdated info behind.
+concurrency:
+  group: canary-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    name: Publish to pkg.pr.new
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm 9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.3.0
+
+      - name: Setup Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "pnpm"
+
+      - name: Install Dependencies 🔧
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Step 🔧
+        run: pnpm build:apsara
+
+      - name: Publish 🚀
+        run: pnpm exec pkg-pr-new publish ./packages/raystack --previewVersion --packageManager=pnpm --comment=update

CONTRIBUTING.md

@@ -24,6 +24,7 @@ Thank you for your interest in contributing to Apsara! This guide will help you
       - [For Maintainers](#for-maintainers)
     - [Release Workflow Details](#release-workflow-details)
     - [NPM Publishing](#npm-publishing)
+    - [Canary Releases](#canary-releases)
   - [Getting Help](#getting-help)
   - [Code of Conduct](#code-of-conduct)
 
@@ -213,6 +214,11 @@ Apsara follows an automated release process using GitHub Actions and semantic ve
    - Published to NPM with `next` tag
    - Triggered by pushing tags matching `v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+`
 
+3. **Canary Releases**:
+   - Built automatically for every pull request and every push to `main`
+   - Not published to NPM — hosted by [pkg.pr.new](https://pkg.pr.new) instead
+   - No tag or version bump needed
+
 ### Creating a Release
 
 #### For Maintainers
@@ -269,6 +275,24 @@ npm install @raystack/apsara
 pnpm add @raystack/apsara
 ```
 
+### Canary Releases
+
+Every pull request gets a preview build of `@raystack/apsara`, so you can try out changes before they're merged or released — no need to wait for a real NPM publish.
+
+The [`canary.yaml`](.github/workflows/canary.yaml) workflow builds the package and publishes it to [pkg.pr.new](https://pkg.pr.new) on every push to a PR or to `main`. pkg.pr.new then comments on the PR with an install command, for example:
+
+```bash
+pnpm add https://pkg.pr.new/raystack/apsara/@raystack/apsara@<pr-number>
+```
+
+Install that in a test project to check out the change. The preview build updates automatically as new commits are pushed to the same PR.
+
+Pushes to `main` are published the same way but don't have a PR to comment on. Install those directly using the commit SHA:
+
+```bash
+pnpm add https://pkg.pr.new/raystack/apsara/@raystack/apsara@<commit-sha>
+```
+
 ## Getting Help
 
 If you encounter issues:

apps/www/src/content/docs/(overview)/getting-started.mdx

@@ -20,6 +20,14 @@ Install the package using your preferred package manager:
 @raystack/apsara
 ```
 
+### Try a preview build
+
+Every pull request on [GitHub](https://github.com/raystack/apsara) gets a canary build, published automatically via [pkg.pr.new](https://pkg.pr.new). This lets you try out unreleased changes before they ship to npm. The PR will have a comment with an install command, for example:
+
+```bash
+pnpm add https://pkg.pr.new/raystack/apsara/@raystack/apsara@<pr-number>
+```
+
 ## Setup
 
 ### 1. Import styles

package.json

@@ -21,6 +21,7 @@
     "@turbo/gen": "^1.9.7",
     "concurrently": "^9.1.2",
     "lefthook": "^1.11.12",
+    "pkg-pr-new": "^0.0.86",
     "process": "^0.11.10",
     "turbo": "2.3.1",
     "typescript": "4.7"

packages/raystack/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@raystack/apsara?logo=npm&color=cb3837)](https://www.npmjs.com/package/@raystack/apsara)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?logo=apache)](LICENSE)
 [![Biome](https://img.shields.io/badge/Biome-60a5fa?logo=biome&logoColor=white)](https://biomejs.dev/)
+[![pkg.pr.new](https://pkg.pr.new/badge/raystack/apsara)](https://pkg.pr.new/~/raystack/apsara)
 
 Apsara is an open-source React component library for building accessible, data-heavy interfaces. It is built on [Base UI](https://base-ui.com/) primitives and written in TypeScript.
 

packages/raystack/package.json

@@ -79,6 +79,11 @@
   ],
   "author": "",
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raystack/apsara.git",
+    "directory": "packages/raystack"
+  },
   "devDependencies": {
     "@figma/code-connect": "^1.4.7",
     "@raystack/tools-config": "workspace:*",