Merge pull request #319 from objectstack-ai/copilot/optimize-static-file-paths

Author: hotlong

.gitignore

@@ -30,4 +30,8 @@ packages/server/objectstack.config.js
 *.tgz
 package/
 
+# SPA static assets copied during Vercel build (build artifacts, not source)
+public/console/
+public/_studio/
+
 .objectstack

CHANGELOG.md

@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- **Optimize static file access paths — serve SPA assets directly from Vercel CDN** — Console
+  and Studio SPA static assets (JS, CSS, fonts, images) are now copied to `public/console/` and
+  `public/_studio/` during the Vercel build step. Vercel's filesystem-first routing serves these
+  files directly from its CDN edge network, bypassing the `api/[[...route]]` serverless function
+  entirely. This eliminates unnecessary cold-start latency for asset requests, enables browser
+  and CDN caching with `Cache-Control: public, max-age=31536000, immutable` headers for
+  content-hashed assets, and reduces serverless function invocations. The API handler retains
+  its static SPA plugin for non-Vercel deployments (Docker, local dev) and SPA HTML fallback.
+  - Updated `scripts/build-vercel.sh` to copy SPA dist assets to `public/` after package builds
+  - Added `headers` configuration in `vercel.json` for long-lived cache on asset paths
+  - Updated `.gitignore` to exclude `public/console/` and `public/_studio/` (build artifacts)
 - **Vercel deployment — switched from InMemoryDriver to TursoDriver** — The Vercel serverless
   handler (`api/[[...route]].ts`) now uses `@objectstack/driver-turso` (TursoDriver) instead of
   `@objectstack/driver-memory` (InMemoryDriver). In production, set `TURSO_DATABASE_URL` and

docs/DEPLOYMENT.md

@@ -289,11 +289,28 @@ Build pipeline:
 | Field | Value | Purpose |
 |-------|-------|---------|
 | `installCommand` | `pnpm install` | Installs all workspace dependencies |
-| `buildCommand` | `bash scripts/build-vercel.sh` | Runs the Vercel build script that builds core, patches console plugin, then compiles all business plugins |
+| `buildCommand` | `bash scripts/build-vercel.sh` | Runs the Vercel build script that builds core, patches console plugin, compiles all business plugins, and copies SPA static assets to `public/` |
 | `functions.memory` | `1024` MB | Memory allocated to the serverless function |
 | `functions.maxDuration` | `60` s | Maximum execution time per request (Pro plan) |
 | `functions.includeFiles` | `{packages/*/dist,node_modules/@object-ui/console/dist,node_modules/@objectstack/*/dist,node_modules/@libsql,node_modules/better-sqlite3,node_modules/@opentelemetry/api}/**` | Bundles business plugin dist/, all @objectstack packages (including Auth, Studio, TursoDriver), libSQL/better-sqlite3 native deps, and OpenTelemetry with the function |
-| `rewrites` | `/(.*) → /api/[[...route]]` | Routes all requests to the catch-all handler |
+| `headers` | `/console/assets/*`, `/_studio/assets/*` | Sets `Cache-Control: public, max-age=31536000, immutable` on content-hashed static assets |
+| `rewrites` | `/(.*) → /api/[[...route]]` | Routes non-static requests to the catch-all handler (static files in `public/` are served by Vercel's CDN before rewrites are evaluated) |
+
+### Static Asset Optimization
+
+SPA static assets (JS, CSS, fonts, images) are served directly from Vercel's CDN edge network
+instead of routing through the serverless function:
+
+- **Build step**: `scripts/build-vercel.sh` copies Console assets to `public/console/assets/`
+  and Studio assets to `public/_studio/assets/` after building all packages.
+- **Vercel routing order**: redirects → headers → **filesystem** → rewrites. Files in `public/`
+  (the output directory) are matched at the filesystem step, **before** rewrites, so they bypass
+  the `api/[[...route]]` serverless function entirely.
+- **Cache headers**: Content-hashed assets (e.g., `index-DDpLaQOV.js`) get
+  `Cache-Control: public, max-age=31536000, immutable` for optimal CDN and browser caching.
+- **SPA fallback**: Only `index.html` and client-side routes still go through the API handler.
+  The static SPA plugin in the serverless function handles these requests, plus serves as the
+  fallback for non-Vercel deployments (Docker, local dev).
 
 ### Architecture Details
 

scripts/build-vercel.sh

@@ -8,6 +8,7 @@
 #   1. Build the core package first (other packages depend on it)
 #   2. Patch the console plugin (dereference pnpm symlinks)
 #   3. Build all business packages in parallel
+#   4. Copy SPA static assets to public/ for direct serving by Vercel's CDN
 #
 # Usage (called automatically by Vercel via vercel.json):
 #   bash scripts/build-vercel.sh
@@ -37,4 +38,49 @@ pnpm --filter @hotcrm/ai \
      --filter @hotcrm/financial-services \
      build
 
+# ---------------------------------------------------------------------------
+# Copy SPA static assets to public/ so Vercel serves them directly from CDN
+# instead of routing through the serverless function.
+#
+# Vercel's routing order: redirects → headers → filesystem → rewrites
+# Files in public/ (the outputDirectory) are matched at the "filesystem"
+# step, BEFORE rewrites, so they bypass the API handler entirely.
+#
+# Only asset files (JS, CSS, fonts, images) are copied — NOT index.html.
+# SPA entry points must still go through the API handler for proper
+# client-side routing fallback.
+# ---------------------------------------------------------------------------
+
+echo "▸ Copying SPA static assets to public/ for direct CDN serving..."
+
+# Console SPA (@object-ui/console)
+CONSOLE_DIST="node_modules/@object-ui/console/dist"
+if [ -d "$CONSOLE_DIST/assets" ]; then
+  mkdir -p public/console/assets
+  cp -r "$CONSOLE_DIST/assets/"* public/console/assets/
+  echo "  ✓ Console assets copied to public/console/assets/"
+  # Copy manifest.json if present (referenced by <link rel="manifest">)
+  if [ -f "$CONSOLE_DIST/manifest.json" ]; then
+    cp "$CONSOLE_DIST/manifest.json" public/console/manifest.json
+    echo "  ✓ Console manifest.json copied"
+  fi
+else
+  echo "  ⚠ Console dist/assets not found — skipping"
+fi
+
+# Studio SPA (@objectstack/studio)
+STUDIO_DIST="node_modules/@objectstack/studio/dist"
+if [ -d "$STUDIO_DIST/assets" ]; then
+  mkdir -p public/_studio/assets
+  cp -r "$STUDIO_DIST/assets/"* public/_studio/assets/
+  echo "  ✓ Studio assets copied to public/_studio/assets/"
+  # Copy vite.svg favicon if present
+  if [ -f "$STUDIO_DIST/vite.svg" ]; then
+    cp "$STUDIO_DIST/vite.svg" public/_studio/vite.svg
+    echo "  ✓ Studio vite.svg copied"
+  fi
+else
+  echo "  ⚠ Studio dist/assets not found — skipping"
+fi
+
 echo "✓ Vercel build complete."

vercel.json

@@ -10,6 +10,20 @@
       "includeFiles": "{packages/*/dist,node_modules/@object-ui/console/dist,node_modules/@objectstack/*/dist,node_modules/@libsql,node_modules/better-sqlite3,node_modules/@opentelemetry/api}/**"
     }
   },
+  "headers": [
+    {
+      "source": "/console/assets/(.*)",
+      "headers": [
+        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
+      ]
+    },
+    {
+      "source": "/_studio/assets/(.*)",
+      "headers": [
+        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
+      ]
+    }
+  ],
   "rewrites": [
     { "source": "/api/:path*", "destination": "/api/[[...route]]" },
     { "source": "/(.*)", "destination": "/api/[[...route]]" }