Node.js install error documentation (#549)

Author: stevensJourney

.changeset/sour-spiders-rhyme.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': patch
+---
+
+Update README with common installation issues section

demos/angular-supabase-todolist/angular.json

@@ -20,10 +20,7 @@
             "customWebpackConfig": {
               "path": "./extra-webpack.config.js"
             },
-            "allowedCommonJsDependencies": [
-              "js-logger",
-              "ws"
-            ],
+            "allowedCommonJsDependencies": ["js-logger", "ws"],
             "outputPath": "dist",
             "index": "src/index.html",
             "main": "src/main.ts",
@@ -39,7 +36,7 @@
                 {
                   "type": "initial",
                   "maximumWarning": "500kb",
-                  "maximumError": "5mb"
+                  "maximumError": "6mb"
                 },
                 {
                   "type": "anyComponentStyle",

demos/angular-supabase-todolist/package.json

@@ -14,27 +14,27 @@
   },
   "private": true,
   "dependencies": {
-    "@angular/animations": "^18.1.1",
-    "@angular/common": "^18.1.1",
-    "@angular/compiler": "^18.1.1",
-    "@angular/core": "^18.1.1",
-    "@angular/forms": "^18.1.1",
-    "@angular/platform-browser": "^18.1.1",
-    "@angular/platform-browser-dynamic": "^18.1.1",
-    "@angular/router": "^18.1.1",
-    "@angular/service-worker": "^18.1.1",
+    "@angular/animations": "^19.2.4",
+    "@angular/common": "^19.2.4",
+    "@angular/compiler": "^19.2.4",
+    "@angular/core": "^19.2.4",
+    "@angular/forms": "^19.2.4",
+    "@angular/platform-browser": "^19.2.4",
+    "@angular/platform-browser-dynamic": "^19.2.4",
+    "@angular/router": "^19.2.4",
+    "@angular/service-worker": "^19.2.4",
     "@journeyapps/wa-sqlite": "^1.2.0",
     "@powersync/web": "workspace:*",
     "@supabase/supabase-js": "^2.44.4",
     "rxjs": "~7.8.1",
     "tslib": "^2.6.3",
-    "zone.js": "~0.14.8"
+    "zone.js": "~0.15.0"
   },
   "devDependencies": {
-    "@angular-builders/custom-webpack": "^18.0.0",
-    "@angular-devkit/build-angular": "^18.1.1",
-    "@angular/cli": "^18.1.1",
-    "@angular/compiler-cli": "^18.1.1",
+    "@angular-builders/custom-webpack": "^19.0.0",
+    "@angular-devkit/build-angular": "^19.2.5",
+    "@angular/cli": "^19.2.5",
+    "@angular/compiler-cli": "^19.2.4",
     "dotenv": "^16.4.5",
     "http-server": "^14.1.1",
     "typescript": "~5.5.3"

packages/node/README.md

@@ -26,6 +26,27 @@ npm install @powersync/node
 Both `@powersync/node` and the `better-sqlite3` packages have install scripts that need to run to compile
 or download sqlite3 and PowerSync binaries.
 
+### Common Installation Issues
+
+The `better-sqlite` package requires native compilation, which depends on certain system tools. This compilation process is handled by `node-gyp` and may fail if required dependencies are missing or misconfigured.
+
+#### Node-gyp Version Conflicts
+
+`better-sqlite` depends on `node-gyp@^11`, but some project configurations may introduce multiple versions of `node-gyp`, potentially causing build issues.
+
+#### Python Dependency Issues
+
+`node-gyp` requires Python for compilation. If your project uses `node-gyp` below version `10` and your system has Python `3.12` or later, you may encounter the following error:
+
+```python
+ModuleNotFoundError: No module named 'distutils'
+```
+
+To resolve this, either:
+
+- Upgrade `node-gyp` to version 10 or later.
+- Install Python [setuptools](https://pypi.org/project/setuptools/), which includes `distutils`.
+
 # Getting Started
 
 The [Node.js SDK reference](https://docs.powersync.com/client-sdk-references/node)