Isolate `demos` folder #784

LucDeCaf · 2025-11-26T10:01:41Z

Currently, the demos in the demos folder use pnpm's workspace feature to link to workspace packages. This is convenient for testing changes to workspace packages, as demos will automatically use the local version - however, it causes issues for other users of the demos, as they are required to install all demos and all packages' dependencies in order to run even a single demo. Also, copying demos out of the monorepo requires one to figure out the correct package versions manually.

This PR replaces the @powersync/* package versions from workspace:* to the latest published releases and adds a pnpm-workspace.yaml file to each demo. This isolates the demos from the rest of the workspace and ensures that each demo can run independently from the powersync-js repo's context. For convenience, this PR also adds a set of scripts for re-linking the @powersync/* packages to the workspace (for ease of development and testing) and for upgrading @powersync/* package versions across demos.

Importantly, this PR also includes a partial rewrite of the react-native-supabase-group-chat demo, which was using old packages and failing to build on my system. The PR which made these changes was merged into this branch, since it also used published PowerSync package versions instead of workspace versions.

changeset-bot · 2025-11-26T10:01:45Z

⚠️ No Changeset found

Latest commit: 21fbf58

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

…dling

simolus3 · 2025-12-11T11:35:23Z

Can we add demo lockfiles to .gitignore? I imagine they make up the bulk of this PR, and I'm not sure they're that helpful (we should definitely keep the root lockfile to ensure we're all using the same version of tools).

demos/django-react-native-todolist/metro.config.js

demos/angular-supabase-todolist/package.json

demos/example-capacitor/package.json

demos/example-electron/package.json

demos/react-multi-client/package.json

demos/react-native-supabase-todolist/package.json

demos/react-native-web-supabase-todolist/package.json

demos/react-supabase-todolist-optional-sync/package.json

Chriztiaan

Last bit of reverting version drops, then it can go in.

LucDeCaf

Yep, fixed the misversioned packages

Chriztiaan · 2025-12-12T13:12:21Z

Happy with the changes.

stevensJourney

I can see a lot of hard work has gone into this. This is already a large improvement from the previous setup.
I added some comments for some potential improvements to make it potentially even better.

stevensJourney · 2025-12-15T09:15:56Z

demos/angular-supabase-todolist/package.json

    "@angular/service-worker": "^19.2.4",
    "@journeyapps/wa-sqlite": "^1.4.0",
-    "@powersync/web": "workspace:*",
+    "@powersync/web": "^1.29.1",


There appears to be some inconsistency between demos. E.g. here the version is specified as ^1.29.1, while the example-capacitor demo has ^1.30.0. Should the script be executed again here?

stevensJourney · 2025-12-15T09:17:49Z

demos/django-react-native-todolist/package.json

-    "@powersync/common": "workspace:*",
-    "@powersync/react": "workspace:*",
-    "@powersync/react-native": "workspace:*",
+    "@powersync/common": "^1.43.1",


I see it was here before, but, do we need the @powersync/common dependency here? I'd hope it would be resolved by @powersync/react-native

stevensJourney · 2025-12-15T09:22:10Z

demos/example-electron-node/src/types.d.ts

@@ -0,0 +1 @@
+declare module 'better-sqlite3';


Could we use @types/better-sqlite3 for this?

Currently, it looks like we need to use "moduleResolution": "bundler" in tsconfig.json, which causes the following error when trying to run the project (even when installing @types/better-sqlite3:

stevensJourney · 2025-12-15T09:25:17Z

demos/react-native-barebones-opsqlite/package.json

+    "@powersync/op-sqlite": "^0.7.16",
+    "@powersync/react": "^1.8.2",
+    "@powersync/react-native": "^1.27.1",
+    "@powersync/common": "^1.43.1",


I suppose we should remove this as a dependency from all demos that might not require it directly.

stevensJourney · 2025-12-15T09:28:52Z

demos/react-native-supabase-group-chat/src/providers/AuthProvider.tsx

+    () => {
+      if (!session) getSession();
+    },
+    // [session, user]


For my context: Why is the user dependency commented out here?

I simply forgot to delete it after testing if it worked.

stevensJourney · 2025-12-15T09:41:27Z

scripts/demos-use-workspace.ts

+const workspacePackages = await findWorkspacePackages(path.resolve('.'));
+
+// Function to split user-provided demos into found and not found demos
+const filterDemos = (allDemos: string[], providedDemos: string[]): [string[], string[]] => {


A bit of a nit: The tuple result here, could be in my opinion, a bit neater if we returned a keyed object e.g. {found: string[], notFound: string[]}

stevensJourney · 2025-12-15T09:45:33Z

scripts/demos-use-workspace.ts

+  };
+
+  for (const arg of process.argv.slice(2)) {
+    if (arg === '--no-install') {


Just mentioning again, something like Commander would provide details and documentation for the supported arguments if a user executed this script with --help or provided an invalid value.

stevensJourney · 2025-12-15T09:48:39Z

scripts/demos-use-workspace.ts

+  const allDemos = fs.readdirSync(demosDir);
+  let demoNames: string[];
+
+  if (args.length > 0) {


Nit: One could perhaps use something like https://www.npmjs.com/package/inquirer for an optional interactive selection (for those of us who are too lazy to type the full demo name).

stevensJourney · 2025-12-15T10:27:06Z

scripts/demos-use-workspace.ts

+    process.exit(0);
+  }
+
+  console.log('\nInstalling packages...');


I got this error when running the script locally

Updating packages... - @powersync/react: '^1.8.2' => 'workspace:*' - @powersync/web: '^1.29.1' => 'workspace:*' Linking tsconfig.demo.json - Added '{"path":"../../tsconfig.demo.json"}' Done. Installing packages... Scope: all 18 workspace projects Lockfile is up to date, resolution step is skipped Packages: -374 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Progress: resolved 0, reused 201, downloaded 0, added 0, done ╭ Warning ────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ Ignored build scripts: @journeyapps/wa-sqlite, @swc/core, core-js, core-js-pure, detox, esbuild, swiftlint. │ │ Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts. │ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ Done in 2.5s using pnpm v10.8.0 Done. undefined:1 /* To learn more about this file see: https://angular.io/config/tsconfig. */ ^ SyntaxError: Unexpected token '/', "/* To lear"... is not valid JSON at JSON.parse (<anonymous>) at linkDemo (file:///Users/stevenontong/Documents/platform_code/powersync/powersync-react-native-sdk/scripts/dist/demos-use-workspace.js:69:31) at main (file:///Users/stevenontong/Documents/platform_code/powersync/powersync-react-native-sdk/scripts/dist/demos-use-workspace.js:127:9) at file:///Users/stevenontong/Documents/platform_code/powersync/powersync-react-native-sdk/scripts/dist/demos-use-workspace.js:143:1 Node.js v20.9.0

It might be related to this JSON in a demo's tsconfig.json

Could you also please give some context for how this script works.

I'm a bit confused by the current structure. Where:

The demos have their own pnpm-workspace.yaml file which defines the demo folder as its own monorepo (in order to avoid issues from nested workspaces I presume)

The monorepo root now does not include the demos folder as part of its workspace (and we don't change that with this script)

This script updates the demo's package.json dependencies to use workspace:* for packages defined in the root workspace

If I run the script for a single demo like the react-supabase-todolist demo. The @powersync/web package is indeed located in the demos/react-supabase-todolist/node_modules folder - I'm not sure why this happens, since we execute a pnpm install command in the repo root which does not include the demos folder in the workspace. However, if I clear my node modules for the entire repo with rm -rf **/node_modules and do pnpm install in the root, then the web sdk is not present in the demo's node_modules folder. If I try to run pnpm install in the demo, I get the following (expected) error

❯ pnpm install ERR_PNPM_WORKSPACE_PKG_NOT_FOUND In : "@powersync/react@workspace:*" is in the dependencies but no package named "@powersync/react" is present in the workspace

This could be problematic, if for example a dev wants to even install or update a different dependency in a demo while developing.

Furthermore. This method of updating the Git tracked package.json files with workspace:* dependencies would result in changes which are hard to avoid committing during development. For this reason alone, I can say I would not use this script in my personal development.

I would rather use the npm link command inside the demo, e.g.

npm link # in packages/web npm link @powersync/web # in demo

Note the above uses NPM (not PNPM) since PNPM has historically been tricky with linking. PNPM links will also modify tracked Git files. There might be some issues for using NPM with the local PNPM workspace (haven't thoroughly tested this myself)

That being said, if one wants to use PNPM and have linking without modifying tracked source files, it is also possible by using dynamic overrides in a pnpmfile

Update: After typing this comment, I noticed there are instructions for adding the demos folder to the root workspace and using git restore to clear changes to tracked files. This is probably personal preference, but I still would not want to run git restore each time before committing during development.

To clarify on .pnpmfile.cjs - is the idea to have a development script that generates a .pnpmfile.cjs in each demo which intercepts the installation of '@powersync/*' packages by linking to the local versions instead of the published versions?

On a high-level, that is what would be done. There are a few options to actually implement this.

The .pnpmfile.cjs could contain the relevant dependency overrides in the file, or it could read the overrides from another file - e.g. a json file which contains a Map of package names and paths to each package to be overriden.

Generally, I think having a standard pnpmfile.cjs implementation which reads the overrides dynamically from a JSON file is cleaner - that way one does not need to edit JavaScript files to configure which packages are to be linked.

The linking script could create the pnpmfile in the demo folder, or the file could always be present. I don't really have a strong opinion on this.

stevensJourney · 2025-12-15T10:30:45Z

scripts/bump-demo-packages.ts

+  return result;
+};
+
+const main = () => {


We should add this script to the changeset:version script. This would ensure that the demos are updated as part of the release process.

For added peace-of-mind, once could also do a changeset version in the Test Isolated Demos action, before running the Verdaccio publishing. This could help catch versioning and package issues sooner.

LucDeCaf added 3 commits November 26, 2025 11:33

create scripts for managing demos

3f45e44

add demos/**/package.json.bak to gitignore

810d3d8

fix spelling

5bc741a

LucDeCaf self-assigned this Nov 26, 2025

LucDeCaf added 4 commits November 26, 2025 12:59

apply scripts to react-supabase-todolist + add tsconfig override

f0b5c13

remove references from react-supabase-todolist/tsconfig.json

b5e39dc

run use latest on react supabase todolist

d368c11

add script to split references out of tsconfig

18a900f

LucDeCaf removed their assignment Nov 26, 2025

LucDeCaf added 20 commits November 26, 2025 15:52

cleanup

74dd68b

isolate example-node

95f2bc5

add gitignore to example-node

db5f592

isolate example-vite and example-vite-encryption

c5d22c9

isolate react-supabase-todolist family of demos

7f664ee

gen overrides for react-supabase-todolist demos

8db8d07

isolate example-webpack

f0b6324

isolate example-vue

ddbbb94

update scripts to work better with workspaces

45f3b42

update tsconfigs and package.jsons

84d8c85

fix rn bundling not working properly

34296fd

fix react package test

3fc0d6e

actually fix react test

cb00fed

further debugging of this project

c373280

update lockfiles and demo test script

181ecbb

update script with more error logging

d217a1d

update scripts + update django demo + fix tsconfig.workspace.json han…

b2dfc80

…dling

consolidate tsconfig.workspace.jsons into toplevel tsconfig.demo.json

f102635

upgrade packages on demo test

b7ffcea

specify cwd in pnpm upgrade

a546d55

Remove demo lockfiles from Git tracking

e088e7d

LucDeCaf force-pushed the isolate-demos branch from 05f2c98 to e088e7d Compare December 11, 2025 17:14

Fix incorrectly resolved version changes

1c13ba3

Chriztiaan reviewed Dec 12, 2025

View reviewed changes

demos/django-react-native-todolist/metro.config.js Outdated Show resolved Hide resolved

Chriztiaan reviewed Dec 12, 2025

View reviewed changes

demos/angular-supabase-todolist/package.json Outdated Show resolved Hide resolved

LucDeCaf added 5 commits December 12, 2025 09:59

Remove unneeded metro configs

981e150

Update scripts and use tsc instead of tsx

33c2884

Update demo script documentation and add pnpm demos:update script

ee6690a

Add timeout to failing test

67c6a37

Merge branch 'main' into isolate-demos

80c3199

LucDeCaf force-pushed the isolate-demos branch from fe023f5 to 80c3199 Compare December 12, 2025 10:57

Chriztiaan reviewed Dec 12, 2025

View reviewed changes

demos/example-capacitor/package.json Outdated Show resolved Hide resolved

Chriztiaan reviewed Dec 12, 2025

View reviewed changes

demos/example-electron/package.json Outdated Show resolved Hide resolved

Chriztiaan reviewed Dec 12, 2025

View reviewed changes

demos/react-multi-client/package.json Outdated Show resolved Hide resolved

Chriztiaan approved these changes Dec 12, 2025

View reviewed changes

demos/react-native-supabase-todolist/package.json Outdated Show resolved Hide resolved

demos/react-native-web-supabase-todolist/package.json Outdated Show resolved Hide resolved

demos/react-supabase-todolist-optional-sync/package.json Outdated Show resolved Hide resolved

Chriztiaan requested changes Dec 12, 2025

View reviewed changes

LucDeCaf added 4 commits December 12, 2025 13:16

Fix reverted wa-sqlite versions

ae64cc8

Fix reverted react-native-quick-sqlite versions

c52715e

Update lockfile

50d8d99

Merge branch 'main' into isolate-demos

8815270

LucDeCaf requested a review from Chriztiaan December 12, 2025 11:25

LucDeCaf added 4 commits December 12, 2025 13:36

Remove unneeded pnpm upgrade call

c0f623d

Revert accidental package version change

98762d7

Update demo packages and update script

b6a7ec9

Final final touches

21fbf58

LucDeCaf commented Dec 12, 2025

View reviewed changes

LucDeCaf requested a review from stevensJourney December 12, 2025 13:04

stevensJourney reviewed Dec 15, 2025

View reviewed changes

Isolate demos folder #784

Are you sure you want to change the base?

Isolate demos folder #784

Uh oh!

Conversation

LucDeCaf commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

simolus3 commented Dec 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Chriztiaan left a comment

Choose a reason for hiding this comment

Uh oh!

LucDeCaf left a comment

Choose a reason for hiding this comment

Uh oh!

Chriztiaan commented Dec 12, 2025

Uh oh!

stevensJourney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LucDeCaf Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Isolate `demos` folder #784

Isolate `demos` folder #784

LucDeCaf commented Nov 26, 2025 •

edited

Loading

changeset-bot bot commented Nov 26, 2025 •

edited

Loading

LucDeCaf Dec 15, 2025 •

edited

Loading