chore(repo): configure TypeScript project references

Author: mandarini

.cursor/mcp.json

@@ -1,8 +1,3 @@
 {
-  "mcpServers": {
-    "nx-mcp": {
-      "command": "npx",
-      "args": ["-y", "nx-mcp@latest"]
-    }
-  }
+  "mcpServers": {}
 }

.eslintignore

@@ -0,0 +1 @@
+node_modules

.eslintrc.json

@@ -0,0 +1,42 @@
+{
+  "root": true,
+  "ignorePatterns": ["**/*"],
+  "plugins": ["@nx"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {
+        "@nx/enforce-module-boundaries": [
+          "error",
+          {
+            "enforceBuildableLibDependency": true,
+            "allow": [],
+            "depConstraints": [
+              {
+                "sourceTag": "*",
+                "onlyDependOnLibsWithTags": ["*"]
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "extends": ["plugin:@nx/typescript"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "extends": ["plugin:@nx/javascript"],
+      "rules": {}
+    },
+    {
+      "files": ["*.spec.ts", "*.spec.tsx", "*.spec.js", "*.spec.jsx"],
+      "env": {
+        "jest": true
+      },
+      "rules": {}
+    }
+  ]
+}

.github/workflows/ci-core.yml

@@ -44,7 +44,7 @@ jobs:
       # Prepend any command with "nx-cloud record --" to record its logs to Nx Cloud
       # - run: npx nx-cloud record -- echo Hello World
       # When you enable task distribution, run the e2e-ci task instead of e2e
-      - name: Check generated types are in sync
+      - name: Check common types are in sync
         run: npm run codegen:check
 
       - name: Build affected packages
@@ -55,6 +55,7 @@ jobs:
 
       - name: Run test:ci for affected packages
         run: npx nx affected --target=test:ci
+        timeout-minutes: 15
 
       - name: Upload coverage for functions-js (if affected)
         uses: coverallsapp/github-action@v2
@@ -75,15 +76,6 @@ jobs:
           flag-name: realtime-js
           fail-on-error: false
         continue-on-error: true
-      - name: Upload coverage for postgrest-js (if affected)
-        uses: coverallsapp/github-action@v2
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          path-to-lcov: ./packages/core/postgrest-js/coverage/lcov.info
-          parallel: true
-          flag-name: postgrest-js
-          fail-on-error: false
-        continue-on-error: true
       - name: Run auth-js tests (if affected)
         run: npx nx affected --target=test:auth
 
@@ -108,19 +100,89 @@ jobs:
           flag-name: storage-js
           fail-on-error: false
         continue-on-error: true
+  # Separate job for postgrest-js tests (Docker-based, retriable)
+  test-postgrest-js:
+    name: Test postgrest-js
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          filter: tree:0
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+      - uses: nrwl/nx-set-shas@v4
+
+      - name: Run postgrest-js integration tests (if affected)
+        run: npx nx affected --target=test:ci:postgrest
+        timeout-minutes: 10
+
+      - name: Run postgrest-js type tests (if affected)
+        run: npx nx affected --target=test:types:ci
+        timeout-minutes: 15
+
+      - name: Upload coverage for postgrest-js (if affected)
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: ./packages/core/postgrest-js/coverage/lcov.info
+          parallel: true
+          flag-name: postgrest-js
+          fail-on-error: false
+        continue-on-error: true
+
+  # Separate job for slow type generation check (runs in parallel)
+  check-postgrest-generated-types:
+    name: Check Postgrest Generated Types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          filter: tree:0
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Check if database schema changed
+        id: check_changes
+        run: |
+          git fetch origin ${{ github.base_ref }}
+          if git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -q "packages/core/postgrest-js/test/db/"; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Verify generated types are in sync
+        if: steps.check_changes.outputs.changed == 'true'
+        run: npm run codegen:check:postgrest
+        timeout-minutes: 5
+
+      - name: Skip check
+        if: steps.check_changes.outputs.changed != 'true'
+        run: echo "⏭️  Skipping - no database schema changes detected"
+
   # SUMMARY JOB
   all-core-tests-pass:
     name: All Core Package Tests Pass
     runs-on: ubuntu-latest
-    needs: setup-build-test-node-20
+    needs: [setup-build-test-node-20, test-postgrest-js, check-postgrest-generated-types]
     steps:
       - name: Summary
         run: echo "✅ All core package tests passed successfully!"
 
   coveralls-finish:
     name: Coveralls Finished
     runs-on: ubuntu-latest
-    needs: setup-build-test-node-20
+    needs: [setup-build-test-node-20, test-postgrest-js]
     steps:
       - name: Coveralls Finished
         uses: coverallsapp/github-action@v2

.gitignore

@@ -49,4 +49,5 @@ Thumbs.db
 .github/instructions/nx.instructions.md
 
 vite.config.*.timestamp*
-vitest.config.*.timestamp*
+vitest.config.*.timestamp*
+test-output

.husky/pre-push

@@ -0,0 +1,21 @@
+# Check if postgrest-js test database schema was modified
+if git diff --name-only origin/master...HEAD 2>/dev/null | grep -q "packages/core/postgrest-js/test/db/"; then
+  echo "📝 Detected changes in postgrest-js test database schema..."
+  echo "🔍 Checking if generated types are in sync..."
+
+  npm run codegen:check:postgrest
+
+  if [ $? -ne 0 ]; then
+    echo ""
+    echo "❌ Push blocked: Postgrest generated types are out of sync"
+    echo ""
+    echo "To fix this:"
+    echo "  1. Run: npm run codegen:postgrest"
+    echo "  2. Commit the updated test/types.generated.ts"
+    echo "  3. Push again"
+    echo ""
+    exit 1
+  fi
+
+  echo "✅ Postgrest generated types are in sync"
+fi

CLAUDE.md

@@ -138,14 +138,14 @@ nx test supabase-js --coverage           # Test with coverage
 
 **Docker Requirements:**
 
-| Package      | Docker Required | Infrastructure                  | Special Commands |
-| ------------ | --------------- | ------------------------------- | ---------------- |
-| auth-js      | ✅ Yes          | Auth Server + Postgres          | May use `nx test:auth auth-js` |
-| functions-js | ✅ Yes          | Deno relay (testcontainers)     | Standard `nx test functions-js` |
-| postgrest-js | ✅ Yes          | PostgREST + PostgreSQL          | Standard `nx test postgrest-js` |
+| Package      | Docker Required | Infrastructure                  | Special Commands                     |
+| ------------ | --------------- | ------------------------------- | ------------------------------------ |
+| auth-js      | ✅ Yes          | Auth Server + Postgres          | May use `nx test:auth auth-js`       |
+| functions-js | ✅ Yes          | Deno relay (testcontainers)     | Standard `nx test functions-js`      |
+| postgrest-js | ✅ Yes          | PostgREST + PostgreSQL          | Standard `nx test postgrest-js`      |
 | storage-js   | ✅ Yes          | Storage API + PostgreSQL + Kong | May use `nx test:storage storage-js` |
-| realtime-js  | ❌ No           | Mock WebSockets                 | Standard `nx test realtime-js` |
-| supabase-js  | ❌ No           | Unit tests only                 | Standard `nx test supabase-js` |
+| realtime-js  | ❌ No           | Mock WebSockets                 | Standard `nx test realtime-js`       |
+| supabase-js  | ❌ No           | Unit tests only                 | Standard `nx test supabase-js`       |
 
 > **📖 See [TESTING.md](docs/TESTING.md) for complete testing guide and troubleshooting**
 
@@ -216,6 +216,68 @@ nx release --tag=latest --yes  # Promotes to stable with same version for ALL pa
 
 Each library has its own `tsconfig.json` extending the base configuration, allowing for library-specific adjustments while maintaining consistency.
 
+### TypeScript Project References Setup
+
+This repository uses TypeScript project references for incremental builds and better type checking across packages.
+
+**What's Configured:**
+
+1. **tsconfig.base.json** - Base configuration inherited by all projects:
+   - `composite: true` - Enables project references
+   - `declaration: true` - Required by composite
+   - `moduleResolution: "bundler"` - Works with workspaces
+   - `isolatedModules: true` - Inherited but overridden in core packages
+   - `noImplicitOverride: true` - Inherited but overridden in core packages
+   - **No `customConditions`** - Removed to avoid conflicts with CommonJS packages
+
+2. **Root tsconfig.json** - References all projects in the monorepo:
+
+   ```json
+   {
+     "extends": "./tsconfig.base.json",
+     "files": [],
+     "references": [
+       { "path": "./packages/core/auth-js" },
+       { "path": "./packages/core/realtime-js" }
+       // ... all other packages
+     ]
+   }
+   ```
+
+3. **Core packages** (auth-js, realtime-js, postgrest-js, functions-js, storage-js):
+   - Keep `module: "CommonJS"` for backward compatibility
+   - Override `moduleResolution: "Node"` (required for CommonJS)
+   - Override `isolatedModules: false` (existing code doesn't use `export type`)
+   - Override `noImplicitOverride: false` (existing code doesn't use `override` keyword)
+   - Add `references` array pointing to dependencies (managed by `nx sync`)
+
+4. **Utils packages** (utils-fetch):
+   - Inherit `moduleResolution: "bundler"` from base
+   - Can optionally add `customConditions: ["@supabase-js/source"]` for source preference
+
+**Key Principles:**
+
+- ✅ **No Breaking Changes**: Build output is identical - only type-checking is affected
+- ✅ **Incremental Builds**: TypeScript only recompiles changed projects
+- ✅ **Better Performance**: Reduced memory usage during builds
+- ✅ **Automatic References**: Nx sync automatically maintains project references
+- ⚠️ **No `customConditions` in base**: Would conflict with `moduleResolution: "Node"`
+
+**When Adding New Packages:**
+
+1. Ensure `composite: true` and `declaration: true` are set
+2. Add `references` array pointing to dependencies
+3. If using CommonJS, override `moduleResolution: "Node"` and disable strict options
+4. Run `nx sync` to update root tsconfig.json automatically
+
+**Important Notes:**
+
+- TypeScript project references work WITHOUT `customConditions` - it's optional
+- `customConditions` only optimizes source file resolution during development
+- Core packages use `moduleResolution: "Node"` which is incompatible with `customConditions`
+- The `isolatedModules: false` override avoids requiring `export type` for type re-exports
+- All build outputs remain identical to pre-project-references setup
+
 ## Testing Infrastructure
 
 ### Unit Tests (Jest)
@@ -314,10 +376,12 @@ Tests run against multiple environments:
 ### Branch Information
 
 **Current Repository:**
+
 - **Default branch**: `master` (confirmed current default)
 - **Repository URL**: `github.com/supabase/supabase-js`
 
 **Original Repository Branches** (for historical reference):
+
 - **master**: auth-js, postgrest-js, realtime-js, supabase-js
 - **main**: functions-js, storage-js