Merge pull request #1170 from objectstack-ai/copilot/fix-left-menu-prefix-issue

fix(studio): resolve router basepath at runtime for sub-path mounts

Author: xuyushun441-sys

apps/server/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @objectstack/example-host
 
+## Unreleased
+
+### Patch Changes
+
+- **Unified Studio mount path to `/_studio/` for all deployments** (CLI embedded, Vercel, self-host).
+  - `vercel.json`: studio SPA now serves under `/_studio/:path*` with a dedicated rewrite to `/_studio/index.html`. Root `/` and bare `/_studio` redirect to `/_studio/`. Asset caching headers scoped to `/_studio/assets/*`. `VITE_BASE=/_studio/` is set in `build.env`.
+  - `scripts/build-vercel.sh`: studio dist is copied to `public/_studio/` (previously `public/`), so Vercel serves it under the same sub-path the CLI uses. This resolves the deep-link / sidebar-click routing failures that occurred when the Studio was mounted at the public root.
+
 ## 4.0.4
 
 ### Patch Changes

apps/server/scripts/build-vercel.sh

@@ -27,13 +27,16 @@ cd apps/server
 # 2. Bundle API serverless function
 node scripts/bundle-api.mjs
 
-# 3. Copy studio dist files to public/ for UI serving
-echo "[build-vercel] Copying studio dist to public/..."
+# 3. Copy studio dist files to public/_studio/ for UI serving.
+# Studio is always mounted under /_studio/ (same convention as the CLI
+# static plugin). Vite builds with base: '/_studio/' so its asset URLs
+# and router basepath are already correct for this mount point.
+echo "[build-vercel] Copying studio dist to public/_studio/..."
 rm -rf public
-mkdir -p public
+mkdir -p public/_studio
 if [ -d "../studio/dist" ]; then
-  cp -r ../studio/dist/* public/
-  echo "[build-vercel]   ✓ Copied studio dist to public/"
+  cp -r ../studio/dist/. public/_studio/
+  echo "[build-vercel]   ✓ Copied studio dist to public/_studio/"
 else
   echo "[build-vercel]   ⚠ Studio dist not found (skipped)"
 fi

apps/server/vercel.json

@@ -6,7 +6,8 @@
   "build": {
     "env": {
       "VITE_RUNTIME_MODE": "server",
-      "VITE_SERVER_URL": ""
+      "VITE_SERVER_URL": "",
+      "VITE_BASE": "/_studio/"
     }
   },
   "functions": {
@@ -17,14 +18,18 @@
   },
   "headers": [
     {
-      "source": "/assets/(.*)",
+      "source": "/_studio/assets/(.*)",
       "headers": [
         { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
       ]
     }
   ],
+  "redirects": [
+    { "source": "/", "destination": "/_studio/", "permanent": false },
+    { "source": "/_studio", "destination": "/_studio/", "permanent": false }
+  ],
   "rewrites": [
     { "source": "/api/:path*", "destination": "/api/[[...route]]" },
-    { "source": "/((?!api/).*)", "destination": "/index.html" }
+    { "source": "/_studio/:path*", "destination": "/_studio/index.html" }
   ]
 }

apps/studio/CHANGELOG.md

@@ -4,13 +4,20 @@
 
 ### Patch Changes
 
-- Fix TanStack Router basepath resolution when Studio is mounted under a sub-path
-  (e.g. `/_studio/` via the CLI `--ui` flag). Previously, routes such as
-  `/_studio/packages` or `/_studio/:package/objects/:name` failed to match —
-  the router treated the mount prefix as a `$package` route parameter, producing
-  "Not Found" errors. The router now derives `basepath` from Vite's
-  `import.meta.env.BASE_URL`, which works transparently for both root and
-  sub-path deployments.
+- **Fix duplicate sidebar rendering on `/$package/objects/:name` and `/$package/metadata/:type/:name`.** Both the parent `$package.tsx` layout and its children rendered their own `<AppSidebar>` + `<main>` + `<SiteHeader>` shell. With TanStack Router's flat file routing, children render inside the parent's `<Outlet>` — producing a visible copy of the left sidebar in the right content pane instead of the metadata detail.
+  - `$package.tsx` is now a pure layout: `<AppSidebar>` + `<main>` wrapper + `<Outlet>`. No `SiteHeader`.
+  - New `$package.index.tsx` leaf handles the exact `/$package` URL, rendering `<SiteHeader selectedView="overview">` + `<DeveloperOverview>`.
+  - `$package.objects.$name.tsx` and `$package.metadata.$type.$name.tsx` simplified to render only their `<SiteHeader>` + `<PluginHost>`; shell is inherited from the parent layout.
+- **Unified Studio mount path to `/_studio/` for all deployments.** The Vite
+  build default is now `base: '/_studio/'` (was `'./'`), baking the correct
+  absolute asset URLs and router basepath into every bundle. This removes the
+  previous build-time/runtime ambiguity that required the host server to
+  rewrite `href="/..."` URLs or inject a `window.__OBJECTSTACK_STUDIO_BASEPATH__`
+  marker.
+- `resolveBasepath()` in `src/router.ts` simplified to rely solely on Vite's
+  `import.meta.env.BASE_URL`, which now always yields `/_studio/` for
+  production bundles and CLI dev (the CLI dev server sets
+  `VITE_BASE=/_studio/`). Runtime `window` injection workaround removed.
 
 ## 4.0.4
 

apps/studio/src/routeTree.gen.ts

@@ -13,6 +13,7 @@ import { Route as PackagesRouteImport } from './routes/packages'
 import { Route as ApiConsoleRouteImport } from './routes/api-console'
 import { Route as PackageRouteImport } from './routes/$package'
 import { Route as IndexRouteImport } from './routes/index'
+import { Route as PackageIndexRouteImport } from './routes/$package.index'
 import { Route as PackageObjectsNameRouteImport } from './routes/$package.objects.$name'
 import { Route as PackageMetadataTypeNameRouteImport } from './routes/$package.metadata.$type.$name'
 
@@ -36,6 +37,11 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const PackageIndexRoute = PackageIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => PackageRoute,
+} as any)
 const PackageObjectsNameRoute = PackageObjectsNameRouteImport.update({
   id: '/objects/$name',
   path: '/objects/$name',
@@ -52,14 +58,15 @@ export interface FileRoutesByFullPath {
   '/$package': typeof PackageRouteWithChildren
   '/api-console': typeof ApiConsoleRoute
   '/packages': typeof PackagesRoute
+  '/$package/': typeof PackageIndexRoute
   '/$package/objects/$name': typeof PackageObjectsNameRoute
   '/$package/metadata/$type/$name': typeof PackageMetadataTypeNameRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
-  '/$package': typeof PackageRouteWithChildren
   '/api-console': typeof ApiConsoleRoute
   '/packages': typeof PackagesRoute
+  '/$package': typeof PackageIndexRoute
   '/$package/objects/$name': typeof PackageObjectsNameRoute
   '/$package/metadata/$type/$name': typeof PackageMetadataTypeNameRoute
 }
@@ -69,6 +76,7 @@ export interface FileRoutesById {
   '/$package': typeof PackageRouteWithChildren
   '/api-console': typeof ApiConsoleRoute
   '/packages': typeof PackagesRoute
+  '/$package/': typeof PackageIndexRoute
   '/$package/objects/$name': typeof PackageObjectsNameRoute
   '/$package/metadata/$type/$name': typeof PackageMetadataTypeNameRoute
 }
@@ -79,14 +87,15 @@ export interface FileRouteTypes {
     | '/$package'
     | '/api-console'
     | '/packages'
+    | '/$package/'
     | '/$package/objects/$name'
     | '/$package/metadata/$type/$name'
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
-    | '/$package'
     | '/api-console'
     | '/packages'
+    | '/$package'
     | '/$package/objects/$name'
     | '/$package/metadata/$type/$name'
   id:
@@ -95,6 +104,7 @@ export interface FileRouteTypes {
     | '/$package'
     | '/api-console'
     | '/packages'
+    | '/$package/'
     | '/$package/objects/$name'
     | '/$package/metadata/$type/$name'
   fileRoutesById: FileRoutesById
@@ -136,6 +146,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/$package/': {
+      id: '/$package/'
+      path: '/'
+      fullPath: '/$package/'
+      preLoaderRoute: typeof PackageIndexRouteImport
+      parentRoute: typeof PackageRoute
+    }
     '/$package/objects/$name': {
       id: '/$package/objects/$name'
       path: '/objects/$name'
@@ -154,11 +171,13 @@ declare module '@tanstack/react-router' {
 }
 
 interface PackageRouteChildren {
+  PackageIndexRoute: typeof PackageIndexRoute
   PackageObjectsNameRoute: typeof PackageObjectsNameRoute
   PackageMetadataTypeNameRoute: typeof PackageMetadataTypeNameRoute
 }
 
 const PackageRouteChildren: PackageRouteChildren = {
+  PackageIndexRoute: PackageIndexRoute,
   PackageObjectsNameRoute: PackageObjectsNameRoute,
   PackageMetadataTypeNameRoute: PackageMetadataTypeNameRoute,
 }

apps/studio/src/router.ts

@@ -13,17 +13,13 @@ import { routeTree } from './routeTree.gen';
 /**
  * Compute the router basepath from Vite's `BASE_URL`.
  *
- * When Studio is mounted under a sub-path (e.g. `/_studio/` via the CLI `--ui`
- * flag, which sets `VITE_BASE=/_studio/`), TanStack Router must strip that
- * prefix before matching route patterns. Otherwise URLs such as
- * `/_studio/packages` are mis-interpreted as `/$package="_studio"/packages`.
+ * Studio is always mounted under `/_studio/` — the Vite build sets
+ * `base: '/_studio/'` by default (see `vite.config.ts`), which makes
+ * `import.meta.env.BASE_URL === '/_studio/'` for every production bundle
+ * and `/_studio/` for the CLI dev server (which also sets `VITE_BASE`).
  *
- * Vite exposes the configured base as `import.meta.env.BASE_URL`:
- *   - Root deployment: `'/'` → basepath `'/'` (no-op)
- *   - Sub-path deployment: `'/_studio/'` → basepath `'/_studio'`
- *
- * TanStack Router expects the basepath WITHOUT a trailing slash (except for
- * the root `'/'`), so we normalise accordingly.
+ * TanStack Router expects the basepath WITHOUT a trailing slash (except
+ * for the root `'/'`), so we normalise accordingly.
  */
 function resolveBasepath(): string {
   const base = (import.meta.env.BASE_URL ?? '/').trim();

apps/studio/src/routes/$package.index.tsx

@@ -0,0 +1,35 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { createFileRoute } from '@tanstack/react-router';
+import { SiteHeader } from '@/components/site-header';
+import { DeveloperOverview } from '../components/DeveloperOverview';
+import { usePackages } from '../hooks/usePackages';
+
+/**
+ * Leaf route for the exact `/$package` URL — the package overview page.
+ *
+ * Owns its own `SiteHeader`; the layout shell (sidebar + main wrapper) is
+ * provided by the parent `$package.tsx` route.
+ */
+function PackageIndexComponent() {
+  const { packages, selectedPackage } = usePackages();
+
+  return (
+    <>
+      <SiteHeader
+        selectedView="overview"
+        packageLabel={selectedPackage?.manifest?.name || selectedPackage?.manifest?.id}
+      />
+      <div className="flex flex-1 flex-col overflow-hidden">
+        <DeveloperOverview
+          packages={packages}
+          selectedPackage={selectedPackage}
+        />
+      </div>
+    </>
+  );
+}
+
+export const Route = createFileRoute('/$package/')({
+  component: PackageIndexComponent,
+});

apps/studio/src/routes/$package.metadata.$type.$name.tsx

@@ -1,36 +1,28 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { createFileRoute } from '@tanstack/react-router';
-import { AppSidebar } from '../components/app-sidebar';
 import { SiteHeader } from '@/components/site-header';
 import { PluginHost } from '../plugins';
 import { usePackages } from '../hooks/usePackages';
 
 function MetadataViewComponent() {
   const { type, name } = Route.useParams();
-  const { packages, selectedPackage, setSelectedPackage } = usePackages();
+  const { selectedPackage } = usePackages();
 
   return (
     <>
-      <AppSidebar
-        packages={packages}
-        selectedPackage={selectedPackage}
-        onSelectPackage={setSelectedPackage}
+      <SiteHeader
+        selectedMeta={{ type, name }}
+        selectedView="metadata"
+        packageLabel={selectedPackage?.manifest?.name || selectedPackage?.manifest?.id}
       />
-      <main className="flex min-w-0 flex-1 flex-col h-svh overflow-hidden bg-background">
-        <SiteHeader
-          selectedMeta={{ type, name }}
-          selectedView="metadata"
-          packageLabel={selectedPackage?.manifest?.name || selectedPackage?.manifest?.id}
+      <div className="flex flex-1 flex-col overflow-hidden">
+        <PluginHost
+          metadataType={type}
+          metadataName={name}
+          packageId={selectedPackage?.manifest?.id}
         />
-        <div className="flex flex-1 flex-col overflow-hidden">
-          <PluginHost
-            metadataType={type}
-            metadataName={name}
-            packageId={selectedPackage?.manifest?.id}
-          />
-        </div>
-      </main>
+      </div>
     </>
   );
 }

apps/studio/src/routes/$package.objects.$name.tsx

@@ -1,36 +1,28 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { createFileRoute } from '@tanstack/react-router';
-import { AppSidebar } from '../components/app-sidebar';
 import { SiteHeader } from '@/components/site-header';
 import { PluginHost } from '../plugins';
 import { usePackages } from '../hooks/usePackages';
 
 function ObjectViewComponent() {
   const { name } = Route.useParams();
-  const { packages, selectedPackage, setSelectedPackage } = usePackages();
+  const { selectedPackage } = usePackages();
 
   return (
     <>
-      <AppSidebar
-        packages={packages}
-        selectedPackage={selectedPackage}
-        onSelectPackage={setSelectedPackage}
+      <SiteHeader
+        selectedObject={name}
+        selectedView="object"
+        packageLabel={selectedPackage?.manifest?.name || selectedPackage?.manifest?.id}
       />
-      <main className="flex min-w-0 flex-1 flex-col h-svh overflow-hidden bg-background">
-        <SiteHeader
-          selectedObject={name}
-          selectedView="object"
-          packageLabel={selectedPackage?.manifest?.name || selectedPackage?.manifest?.id}
+      <div className="flex flex-1 flex-col overflow-hidden">
+        <PluginHost
+          metadataType="object"
+          metadataName={name}
+          packageId={selectedPackage?.manifest?.id}
         />
-        <div className="flex flex-1 flex-col overflow-hidden">
-          <PluginHost
-            metadataType="object"
-            metadataName={name}
-            packageId={selectedPackage?.manifest?.id}
-          />
-        </div>
-      </main>
+      </div>
     </>
   );
 }

apps/studio/src/routes/$package.tsx

@@ -2,10 +2,19 @@
 
 import { createFileRoute, Outlet } from '@tanstack/react-router';
 import { AppSidebar } from '../components/app-sidebar';
-import { SiteHeader } from '@/components/site-header';
 import { usePackages } from '../hooks/usePackages';
 import { useEffect } from 'react';
 
+/**
+ * Layout for every `/$package/*` route.
+ *
+ * Renders the persistent left `AppSidebar` and the main content frame, and
+ * delegates the `SiteHeader` + body rendering to the child leaf routes via
+ * `<Outlet />`. Keeping the header in the children lets each leaf (index,
+ * object view, metadata view) provide accurate breadcrumbs without prop-
+ * drilling. It also prevents the duplicated-shell bug that occurred when
+ * both this layout and its children each rendered their own `AppSidebar`.
+ */
 function PackageLayoutComponent() {
   const { package: packageId } = Route.useParams();
   const { packages, selectedPackage, setSelectedPackage } = usePackages();
@@ -26,13 +35,7 @@ function PackageLayoutComponent() {
         onSelectPackage={setSelectedPackage}
       />
       <main className="flex min-w-0 flex-1 flex-col h-svh overflow-hidden bg-background">
-        <SiteHeader
-          selectedView="overview"
-          packageLabel={selectedPackage?.manifest?.name || selectedPackage?.manifest?.id}
-        />
-        <div className="flex flex-1 flex-col overflow-hidden">
-          <Outlet />
-        </div>
+        <Outlet />
       </main>
     </>
   );