Update

stack-auth · N2D4 · Oct 20, 2025 · Oct 17, 2025 · Oct 17, 2025 · Oct 17, 2025
commit 8a76453b5655edfaa951ce0296af6a0c29328259
diff --git a/.claude/settings.json b/.claude/settings.json
@@ -21,7 +21,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if ! curl -s --connect-timeout 1 http://localhost:8102 >/dev/null 2>&1; then echo -e '\\n\\n\\033[1;31mCannot reach backend on port 8102! Please run `pnpm run dev` before querying Claude Code\\033[0m\\n\\n' >&2; exit 2; fi"
+            "command": "PORT=${STACK_PORT_PREFIX:-81}02; if ! curl -s --connect-timeout 1 \"http://localhost:$PORT\" >/dev/null 2>&1; then echo -e \"\\n\\n\\033[1;31mCannot reach backend on port $PORT! Please run \\`pnpm run dev\\` before querying Claude Code\\033[0m\\n\\n\" >&2; exit 2; fi"
           }
         ]
       }

diff --git a/.github/workflows/e2e-custom-base-port-api-tests.yaml b/.github/workflows/e2e-custom-base-port-api-tests.yaml
@@ -0,0 +1,153 @@
+name: Runs E2E API Tests
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
+
+jobs:
+  build:
+    runs-on: ubicloud-standard-8
+    env:
+      NODE_ENV: test
+      STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
+      STACK_DIRECT_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:6728/stackframe"
+      STACK_PORT_PREFIX: "67"
+
+    strategy:
+      matrix:
+        node-version: [22.x]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+            version: 9.1.2
+
+      # Even just starting the Docker Compose as a daemon is slow because we have to download and build the images
+      # so, we run it in the background
+      - name: Start Docker Compose in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: docker compose -f docker/dependencies/docker.compose.yaml up -d &
+          # we don't need to wait on anything, just need to start the daemon
+          wait-on: /dev/null
+          tail: true
+          wait-for: 3s
+          log-output-if: true
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create .env.test.local file for apps/backend
+        run: cp apps/backend/.env.development apps/backend/.env.test.local
+
+      - name: Create .env.test.local file for apps/dashboard
+        run: cp apps/dashboard/.env.development apps/dashboard/.env.test.local
+
+      - name: Create .env.test.local file for apps/e2e
+        run: cp apps/e2e/.env.development apps/e2e/.env.test.local
+
+      - name: Create .env.test.local file for docs
+        run: cp docs/.env.development docs/.env.test.local
+
+      - name: Create .env.test.local file for examples/cjs-test
+        run: cp examples/cjs-test/.env.development examples/cjs-test/.env.test.local
+
+      - name: Create .env.test.local file for examples/demo
+        run: cp examples/demo/.env.development examples/demo/.env.test.local
+
+      - name: Create .env.test.local file for examples/docs-examples
+        run: cp examples/docs-examples/.env.development examples/docs-examples/.env.test.local
+
+      - name: Create .env.test.local file for examples/e-commerce
+        run: cp examples/e-commerce/.env.development examples/e-commerce/.env.test.local
+
+      - name: Create .env.test.local file for examples/middleware
+        run: cp examples/middleware/.env.development examples/middleware/.env.test.local
+
+      - name: Create .env.test.local file for examples/partial-prerendering
+        run: cp examples/partial-prerendering/.env.development examples/partial-prerendering/.env.test.local
+
+      - name: Create .env.test.local file for examples/supabase
+        run: cp examples/supabase/.env.development examples/supabase/.env.test.local
+
+      - name: Create .env.test.local file for examples/convex
+        run: cp examples/convex/.env.development examples/convex/.env.test.local
+
+      - name: Build
+        run: pnpm build
+
+      - name: Wait on Postgres
+        run: pnpm run wait-until-postgres-is-ready:pg_isready
+
+      - name: Wait on Inbucket
+        run: npx wait-on tcp:localhost:8129
+
+      - name: Wait on Svix
+        run: npx wait-on tcp:localhost:8113
+
+      - name: Initialize database
+        run: pnpm run db:init
+
+      - name: Start stack-backend in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:backend --log-order=stream &
+          wait-on: |
+            http://localhost:8102
+          tail: true
+          wait-for: 30s
+          log-output-if: true
+      - name: Start stack-dashboard in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:dashboard --log-order=stream &
+          wait-on: |
+            http://localhost:8102
+          tail: true
+          wait-for: 30s
+          log-output-if: true
+      - name: Start mock-oauth-server in background
+        uses: JarvusInnovations/background-action@v1.0.7
+        with:
+          run: pnpm run start:mock-oauth-server --log-order=stream &
+          wait-on: |
+            http://localhost:8102
+          tail: true
+          wait-for: 30s
+          log-output-if: true
+
+      - name: Wait 10 seconds
+        run: sleep 10
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Run tests again, to make sure they are stable (attempt 1)
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
+        run: pnpm test
+
+      - name: Run tests again, to make sure they are stable (attempt 2)
+        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
+        run: pnpm test
+
+      - name: Verify data integrity
+        run: pnpm run verify-data-integrity
+
+      - name: Print Docker Compose logs
+        if: always()
+        run: docker compose -f docker/dependencies/docker.compose.yaml logs
diff --git a/AGENTS.md b/AGENTS.md
@@ -34,11 +34,11 @@ You should ALWAYS add new E2E tests when you change the API or SDK interface. Ge
 Stack Auth is a monorepo using Turbo for build orchestration. The main components are:
 
 ### Apps (`/apps`)
-- **backend** (`/apps/backend`): Next.js API backend running on port 8102
+- **backend** (`/apps/backend`): Next.js API backend running on port `<$STACK_PORT_PREFIX>02` (defaults to 8102)
   - Main API routes in `/apps/backend/src/app/api/latest`
   - Database models using Prisma
-- **dashboard** (`/apps/dashboard`): Admin dashboard on port 8101
-- **dev-launchpad**: Development portal on port 8100
+- **dashboard** (`/apps/dashboard`): Admin dashboard on port `<$STACK_PORT_PREFIX>01` (defaults to 8101)
+- **dev-launchpad**: Development portal on port `<$STACK_PORT_PREFIX>00` (defaults to 8100)
 - **e2e**: End-to-end tests
 
 ### Packages (`/packages`)

diff --git a/apps/backend/package.json b/apps/backend/package.json
@@ -7,12 +7,12 @@
     "typecheck": "tsc --noEmit",
     "with-env": "dotenv -c development --",
     "with-env:prod": "dotenv -c --",
-    "dev": "concurrently -n \"dev,codegen,prisma-studio\" -k \"next dev --turbopack --port 8102\" \"pnpm run codegen:watch\" \"pnpm run prisma-studio\"",
+    "dev": "concurrently -n \"dev,codegen,prisma-studio\" -k \"next dev --turbopack --port ${STACK_PORT_PREFIX:-81}02\" \"pnpm run codegen:watch\" \"pnpm run prisma-studio\"",
     "build": "pnpm run codegen && next build",
     "docker-build": "pnpm run codegen && next build --experimental-build-mode compile",
     "build-self-host-migration-script": "tsup --config scripts/db-migrations.tsup.config.ts",
     "analyze-bundle": "ANALYZE_BUNDLE=1 pnpm run build",
-    "start": "next start --port 8102",
+    "start": "next start --port ${STACK_PORT_PREFIX:-81}02",
     "codegen-prisma": "pnpm run prisma generate",
     "codegen-prisma:watch": "pnpm run prisma generate --watch",
     "codegen-route-info": "pnpm run with-env tsx scripts/generate-route-info.ts",
@@ -21,7 +21,7 @@
     "codegen:watch": "concurrently -n \"prisma,docs,route-info,migration-imports\" -k \"pnpm run codegen-prisma:watch\" \"pnpm run watch-docs\" \"pnpm run codegen-route-info:watch\" \"pnpm run generate-migration-imports:watch\"",
     "psql-inner": "psql $(echo $STACK_DATABASE_CONNECTION_STRING | sed 's/\\?.*$//')",
     "psql": "pnpm run with-env pnpm run psql-inner",
-    "prisma-studio": "pnpm run with-env prisma studio --port 8106 --browser none",
+    "prisma-studio": "pnpm run with-env prisma studio --port ${STACK_PORT_PREFIX:-81}06 --browser none",
     "prisma": "pnpm run with-env prisma",
     "db:migration-gen": "pnpm run with-env tsx scripts/db-migrations.ts generate-migration-file",
     "db:reset": "pnpm run with-env tsx scripts/db-migrations.ts reset",

diff --git a/apps/backend/src/lib/freestyle.tsx b/apps/backend/src/lib/freestyle.tsx
@@ -15,7 +15,8 @@ export class Freestyle {
       if (!["development", "test"].includes(getNodeEnvironment())) {
         throw new StackAssertionError("Mock Freestyle key used in production; please set the STACK_FREESTYLE_API_KEY environment variable.");
       }
-      baseUrl = "http://localhost:8122";
+      const prefix = getEnvVariable("STACK_PORT_PREFIX", "81");
+      baseUrl = `http://localhost:${prefix}22`;
     }
     this.freestyle = new FreestyleSandboxes({
       apiKey,

diff --git a/apps/backend/src/lib/stripe.tsx b/apps/backend/src/lib/stripe.tsx
@@ -9,10 +9,11 @@ import { createStripeProxy, type StripeOverridesMap } from "./stripe-proxy";
 
 const stripeSecretKey = getEnvVariable("STACK_STRIPE_SECRET_KEY");
 const useStripeMock = stripeSecretKey === "sk_test_mockstripekey" && ["development", "test"].includes(getNodeEnvironment());
+const stackPortPrefix = getEnvVariable("STACK_PORT_PREFIX", "81");
 const stripeConfig: Stripe.StripeConfig = useStripeMock ? {
   protocol: "http",
   host: "localhost",
-  port: 8123,
+  port: Number(`${stackPortPrefix}23`),
 } : {};
 
 export const getStackStripe = (overrides?: StripeOverridesMap) => {

diff --git a/apps/dashboard/package.json b/apps/dashboard/package.json
@@ -7,11 +7,11 @@
     "typecheck": "tsc --noEmit",
     "with-env": "dotenv -c development --",
     "with-env:prod": "dotenv -c --",
-    "dev": "next dev --turbopack --port 8101",
+    "dev": "next dev --turbopack --port ${STACK_PORT_PREFIX:-81}01",
     "build": "next build",
     "docker-build": "next build --experimental-build-mode compile",
     "analyze-bundle": "ANALYZE_BUNDLE=1 pnpm run build",
-    "start": "next start --port 8101",
+    "start": "next start --port ${STACK_PORT_PREFIX:-81}01",
     "psql": "pnpm run with-env bash -c 'psql $STACK_DATABASE_CONNECTION_STRING'",
     "lint": "next lint"
   },

diff --git a/apps/dev-launchpad/.gitignore b/apps/dev-launchpad/.gitignore
@@ -0,0 +1 @@
+public/env-config.js
diff --git a/apps/dev-launchpad/package.json b/apps/dev-launchpad/package.json
@@ -3,7 +3,7 @@
   "version": "2.8.43",
   "private": true,
   "scripts": {
-    "dev": "serve -p 8100 -s public",
+    "dev": "node scripts/write-env-config.js && serve -p ${STACK_PORT_PREFIX:-81}00 -s public",
     "clean": "rimraf node_modules"
   },
   "dependencies": {