FilOzone · hugomrdias · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
@@ -0,0 +1,20 @@
+name: Pkg PR New
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+      - name: Use Node.js lts/*
+        uses: actions/setup-node@v7
+        with:
+          node-version: lts/*
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build
+        run: pnpm build
+      - run: pnpm exec pkg-pr-new publish --pnpm './packages/*'
@@ -21,6 +21,7 @@ export default defineConfig({
     '/developer-guides/storage/split-operations/': '/developer-guides/storage/upload-pipeline/',
     '/developer-guides/react-integration/': '/developer-guides/synapse-react/',
     '/developer-guides/devnet/': '/resources/devnet/',
+    '/getting-started/preview-packages/': '/developer-guides/preview-packages/',
   },
   markdown: {
     // rehype-external-links attaches to the unified processor Starlight runs.

@@ -0,0 +1,120 @@
+---
+title: Preview Packages
+description: Install unreleased Synapse packages from pull requests, commits, and master using pkg.pr.new.
+sidebar:
+  order: 8
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+This repository publishes a preview of every package on each pull request, commit, and push to `master`. Previews are not published to npm. They are served from [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) as npm-compatible tarball URLs, so you can try a fix or feature before it is released.
+
+## Setup
+
+Preview publishing follows the [pkg.pr.new setup](https://github.com/stackblitz-labs/pkg.pr.new#setup):
+
+1. The [pkg-pr-new GitHub App](https://github.com/apps/pkg-pr-new) is installed on [FilOzone/synapse-sdk](https://github.com/FilOzone/synapse-sdk).
+2. The [Pkg PR New workflow](https://github.com/FilOzone/synapse-sdk/blob/master/.github/workflows/pkg-pr-new.yml) builds the workspace, then publishes every package under `packages/*` with:
+
+   ```sh
+   pnpm exec pkg-pr-new publish --pnpm './packages/*'
+   ```
+
+The workflow runs on `push` and `pull_request`. On pull requests, the bot comments with install commands for that PR. Publishing only happens in GitHub Actions, not on your local machine.
+
+See the [pkg.pr.new setup guide](https://github.com/stackblitz-labs/pkg.pr.new#setup) for CLI flags, compact vs long-form URLs, and other options.
+
+## Install URLs
+
+Preview URLs use this compact form:
+
+```text
+https://pkg.pr.new/@filoz/<package>@<ref>
+```
+
+`<package>` is `synapse-sdk`, `synapse-core`, or `synapse-react`. `<ref>` is a pull request number, a commit SHA, or a branch name such as `master`.
+
+If a compact URL is unavailable, use the long form:
+
+```text
+https://pkg.pr.new/FilOzone/synapse-sdk/@filoz/<package>@<ref>
+```
+
+Peer dependencies such as `viem` are still required. Install them the same way you would for a published release.
+
+:::caution[Unreleased code]
+Preview packages track git, not npm versions. APIs can change, and a later npm release of the same version string can collide with a lockfile entry. Prefer a commit SHA when you need a reproducible install.
+:::
+
+### Pull request
+
+Use the pull request number. The pkg.pr.new bot also posts these commands on the PR.
+
+```sh
+npm i https://pkg.pr.new/@filoz/synapse-sdk@123
+```
+
+Replace `123` with the PR number, and swap the package name for `@filoz/synapse-core` or `@filoz/synapse-react` as needed.
+
+### Commit
+
+Use the abbreviated commit SHA (the same short hash shown in the bot comment, for example `a832a55`). This is the most precise ref: it always points at that exact build.
+
+```sh
+npm i https://pkg.pr.new/@filoz/synapse-sdk@a832a55
+```
+
+### master
+
+After the workflow has run on `master`, `@master` resolves to the latest published commit on that branch:
+
+```sh
+npm i https://pkg.pr.new/@filoz/synapse-sdk@master
+```
+
+The same pattern works for other in-repo branches once the workflow has published them (`@branch-name`).
+
+## Package managers
+
+<Tabs syncKey="pkg">
+  <TabItem label="npm" icon="seti:npm">
+    ```bash
+    npm i https://pkg.pr.new/@filoz/synapse-sdk@master
+    npm i https://pkg.pr.new/@filoz/synapse-core@master
+    npm i https://pkg.pr.new/@filoz/synapse-react@master
+    ```
+  </TabItem>
+  <TabItem label="pnpm" icon="pnpm">
+    ```bash
+    pnpm add https://pkg.pr.new/@filoz/synapse-sdk@master
+    pnpm add https://pkg.pr.new/@filoz/synapse-core@master
+    pnpm add https://pkg.pr.new/@filoz/synapse-react@master
+    ```
+  </TabItem>
+  <TabItem label="yarn" icon="seti:yarn">
+    ```bash
+    yarn add https://pkg.pr.new/@filoz/synapse-sdk@master
+    yarn add https://pkg.pr.new/@filoz/synapse-core@master
+    yarn add https://pkg.pr.new/@filoz/synapse-react@master
+    ```
+  </TabItem>
+  <TabItem label="bun" icon="bun">
+    ```bash
+    bun add https://pkg.pr.new/@filoz/synapse-sdk@master
+    bun add https://pkg.pr.new/@filoz/synapse-core@master
+    bun add https://pkg.pr.new/@filoz/synapse-react@master
+    ```
+  </TabItem>
+</Tabs>
+
+Replace `@master` with a PR number or commit SHA when you want a specific change instead of the latest `master` build.
+
+## Packages
+
+| Package | Compact URL |
+| --- | --- |
+| [@filoz/synapse-sdk](/developer-guides/synapse/) | `https://pkg.pr.new/@filoz/synapse-sdk@<ref>` |
+| [@filoz/synapse-core](/developer-guides/synapse-core/) | `https://pkg.pr.new/@filoz/synapse-core@<ref>` |
+| [@filoz/synapse-react](/developer-guides/synapse-react/) | `https://pkg.pr.new/@filoz/synapse-react@<ref>` |
+
+Published previews for this repository are listed at [pkg.pr.new/~/FilOzone/synapse-sdk](https://pkg.pr.new/~/FilOzone/synapse-sdk).
@@ -41,6 +41,10 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 Synapse Core requires [viem](https://viem.sh) 2.x as a peer dependency.
 
+:::tip[Trying an unreleased version?]
+Install a preview build from a pull request, commit, or `master`. See [Preview Packages](/developer-guides/preview-packages/).
+:::
+
 **Client setup:**
 
 All Synapse Core functions accept a viem `Client` as their first argument. Create one using viem's standard client factories:

@@ -41,6 +41,10 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 - Connected Web3 wallet
 - Supported networks: Filecoin Mainnet, Filecoin Calibration
 
+:::tip[Trying an unreleased version?]
+Install a preview build from a pull request, commit, or `master`. See [Preview Packages](/developer-guides/preview-packages/).
+:::
+
 **Wagmi config:**
 
 ```tsx twoslash

@@ -50,6 +50,10 @@ The Synapse SDK works in **Node.js** and **the browser**. Install it with your p
 
 `viem` is a peer dependency and must be installed separately.
 
+:::tip[Trying an unreleased version?]
+Every pull request, commit, and push to `master` publishes a preview package. See [Preview Packages](/developer-guides/preview-packages/) for the install URLs.
+:::
+
 :::tip[Other Languages?]
 Looking for Python or Go? Check out [Community Projects](/resources/community-projects/) for community-maintained SDKs.
 :::
@@ -213,6 +217,7 @@ Now let's break down each step...
 
 You've just stored and retrieved data on Filecoin. See the [Developer Guides](/developer-guides/) overview to find the right approach for your application, then dive into specific topics:
 
+- [Preview Packages](/developer-guides/preview-packages/) - Install unreleased builds from a PR, commit, or `master`
 - [Upload Pipeline](/developer-guides/storage/upload-pipeline/) - From simple one-liner to manual store, pull, and commit control
 - [Storage Operations](/developer-guides/storage/storage-operations/) - Data set management, retrieval, and lifecycle
 - [Payment Operations](/developer-guides/payments/payment-operations/) - Fund your account and manage storage payments

@@ -26,6 +26,7 @@
     "@biomejs/biome": "catalog:",
     "knip": "6.32.2",
     "markdownlint-cli2": "0.23.2",
+    "pkg-pr-new": "^0.0.88",
     "typescript": "catalog:",
     "wireit": "0.14.13"
   },