Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
20c6742
feat(stack): resolve media and route docs clients
olliethedev Aug 29, 2026
7c5a44d
fix(media): authenticate Vercel Blob token exchange
olliethedev Aug 29, 2026
d1b6b09
fix(stack): isolate resolved media and route docs runtimes
olliethedev Aug 29, 2026
674b696
docs(media): distinguish request and browser stacks
olliethedev Aug 29, 2026
9a47fc6
docs(media): clarify upload transport contracts
olliethedev Aug 29, 2026
b95a741
fix(codegen): emit canonical media client factories
olliethedev Aug 29, 2026
c731919
fix(route-docs): bind introspection to client stack
olliethedev Aug 29, 2026
9232515
fix(media): resolve assets against plugin origin
olliethedev Aug 29, 2026
4ddedf0
fix(route-docs): scope schema cache per stack
olliethedev Aug 29, 2026
b3e7791
fix(media): normalize registration mutation results
olliethedev Aug 29, 2026
393acf8
fix(route-docs): isolate identical stack caches
olliethedev Aug 29, 2026
125e91d
fix(codegen): resolve browser stack origins
olliethedev Aug 29, 2026
e562a58
fix(route-docs): keep schema loading client-side
olliethedev Aug 29, 2026
0318597
fix(media): preserve mutation data identity
olliethedev Aug 29, 2026
cd003b9
fix(route-docs): stabilize reconstructed cache keys
olliethedev Aug 29, 2026
3edbd8e
fix(route-docs): key schemas by sitemap output
olliethedev Aug 29, 2026
2a4fe1e
fix(stack): isolate client-only route docs caches
olliethedev Aug 29, 2026
49fbc7f
fix(media): lazy load library page
olliethedev Aug 29, 2026
1b78fc3
fix(stack): bind media and route docs caches
olliethedev Aug 29, 2026
f16ad13
docs(media): describe loader context
olliethedev Aug 29, 2026
558ce59
docs(media): clarify identity hydration
olliethedev Aug 29, 2026
5034949
fix(media): partition resolved query caches
olliethedev Aug 29, 2026
010c3c9
docs(media): explain endpoint-scoped query keys
olliethedev Aug 29, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
342 changes: 159 additions & 183 deletions docs/content/docs/plugins/media.mdx

Large diffs are not rendered by default.

81 changes: 58 additions & 23 deletions docs/content/docs/plugins/route-docs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,17 +37,21 @@ Ensure you followed the general [framework installation guide](/installation) fi
Import and register the Route Docs client plugin in your client configuration:

```tsx title="lib/stack-client.tsx"
import { createStackClient } from "@btst/stack/client"
import { createClientStack } from "@btst/stack/client"
import { routeDocsClientPlugin } from "@btst/stack/plugins/route-docs/client"
import type { QueryClient } from "@tanstack/react-query"

export const getStackClient = (queryClient: QueryClient) =>
createStackClient({
export const getStackClient = (
queryClient: QueryClient,
baseURL: string,
) =>
createClientStack({
api: { baseURL, basePath: "/api/data" },
site: { baseURL, basePath: "/pages" },
queryClient,
plugins: {
// Keep your other client plugin entries here. Route Docs introspects them.
routeDocs: routeDocsClientPlugin({
queryClient,
siteBasePath: "/pages",
title: "Client Route Documentation",
description: "Documentation for all client routes in this application",
}),
Expand All @@ -59,9 +63,31 @@ export const getStackClient = (queryClient: QueryClient) =>
The Route Docs plugin is client-only. There is no backend plugin required.
</Callout>

Render it under the standard provider-only layout from the
[installation guide](/installation): one top-level router and API config, with
no Route Docs override block.
Route Docs consumes only the resolved query client, site location, and
registered client definitions it needs for introspection. It does not call a
Route Docs API, require a fake backend plugin, or accept transport configuration
for symmetry.

Render it under the standard layout from the [installation guide](/installation)
by passing the resolved stack to `StackProvider`. No Route Docs override block
is required:

```tsx
<StackProvider stack={stack} router={frameworkRouter}>
{children}
</StackProvider>
```

Inside `StackProvider`, `useRegisteredRoutes()` is automatically bound to that
stack, so multiple stacks cannot leak route definitions into one another. Pass
the resolved stack explicitly when the hook is rendered outside the provider:

```tsx
import { useRegisteredRoutes } from "@btst/stack/plugins/route-docs/client"

const routes = useRegisteredRoutes()
const explicitRoutes = useRegisteredRoutes(stack)
```

## Accessing the Documentation

Expand All @@ -77,20 +103,29 @@ Replace `/pages` with your configured `siteBasePath`.

```tsx
routeDocsClientPlugin({
// React Query client for data fetching
queryClient: queryClient,

// Custom title for the documentation page
title: "Client Route Documentation",

// Description shown on the page
description: "Documentation for all client routes",

// Base path for generating URLs (default: "/pages")
siteBasePath: "/pages",

// Custom route path (default: "/route-docs")
basePath: "/docs/routes",
})
```

The canonical programmatic ID is `routeDocs`; the npm package and route keep
the `route-docs` slug. Site-origin and mount-path replacements belong to the
stack endpoint map and drive metadata plus every rendered Visit link together:

```tsx
createClientStack({
api,
site,
queryClient,
plugins: { routeDocs: routeDocsClientPlugin() },
endpoints: {
routeDocs: {
site: { baseURL: "https://docs.example.com", basePath: "/" },
},
},
})
```

Expand Down Expand Up @@ -143,14 +178,14 @@ The Route Docs page exposes your application's route structure. Consider these m
const routeDocs =
process.env.NODE_ENV === "development"
? {
routeDocs: routeDocsClientPlugin({
queryClient,
siteBasePath: "/pages",
}),
routeDocs: routeDocsClientPlugin(),
}
: {}

createStackClient({
createClientStack({
api,
site,
queryClient,
plugins: {
// ...your other client plugins,
...routeDocs,
Expand Down
11 changes: 4 additions & 7 deletions docs/content/docs/shadcn-registry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -251,11 +251,7 @@ import { mediaClientPlugin } from "@btst/stack/plugins/media/client"
import { LibraryPageComponent } from "@/components/btst/media/client/components/pages/library-page"

mediaClientPlugin({
apiBaseURL: "...",
apiBasePath: "/api/data",
siteBaseURL: "...",
siteBasePath: "/pages",
queryClient,
uploadMode: "direct",
pageComponents: {
library: LibraryPageComponent, // media library page
},
Expand All @@ -264,8 +260,9 @@ mediaClientPlugin({

Keep the top-level `createClientStack({ api, site, queryClient })` runtime,
pass its resolved browser stack to `StackProvider.stack`, and keep the provider
router plus media-specific upload mode and hooks configured so the ejected
component uses the same runtime services as the built-in page.
router configured so the ejected component uses the same runtime services as
the built-in page. Upload mode belongs to `mediaClientPlugin()`; optional image
compression and route lifecycle callbacks remain inferred provider overrides.

## Available `pageComponents` keys

Expand Down
9 changes: 5 additions & 4 deletions packages/cli/src/templates/shared/lib/stack-client.tsx.hbs
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ import { QueryClient } from "@tanstack/react-query"

export function getStackClient(
queryClient: QueryClient,
options?: { headers?: Headers },
options?: { headers?: Headers; origin?: string },
) {
const baseURL = getBaseURL()
const baseURL = getBaseURL(options?.origin)
return createStackClient({
api: {
baseURL,
Expand All @@ -27,10 +27,11 @@ export function getStackClient(
})
}

function getBaseURL() {
function getBaseURL(serverOrigin?: string) {
if (typeof window !== "undefined") {
return window.location.origin
return {{{browserSiteURLExpression}}} || window.location.origin
}
if (serverOrigin) return serverOrigin

// Use literal process.env.XXX so bundlers (Vite define, Next.js, etc.)
// can statically replace these at build/transform time.
Expand Down
52 changes: 50 additions & 2 deletions packages/cli/src/utils/__tests__/scaffold-plan.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,9 @@ describe("scaffold plan", () => {
(f) => f.path === "lib/stack-client.tsx",
);
expect(stackClientFile?.content).toContain("blogClientPlugin");
expect(stackClientFile?.content).toContain("const baseURL = getBaseURL()");
expect(stackClientFile?.content).toContain(
"const baseURL = getBaseURL(options?.origin)",
);
expect(stackClientFile?.content).toContain(
"...(options?.headers ? { headers: options.headers } : {})",
);
Expand Down Expand Up @@ -262,7 +264,7 @@ describe("scaffold plan", () => {
);
expect(stackClientFile?.content).toBeDefined();
expect(stackClientFile?.content).toContain(
"const baseURL = getBaseURL()",
"const baseURL = getBaseURL(options?.origin)",
);
expect(stackClientFile?.content).toContain(
'if (typeof window !== "undefined")',
Expand Down Expand Up @@ -475,6 +477,52 @@ describe("scaffold plan", () => {
);
});

it.each(["nextjs", "react-router", "tanstack"] as const)(
"emits plugin-only Media and Route Docs factories for %s",
async (framework) => {
const browserSiteURLExpression =
framework === "nextjs"
? "process.env.NEXT_PUBLIC_SITE_URL"
: "import.meta.env.VITE_PUBLIC_SITE_URL";
const plan = await buildScaffoldPlan({
framework,
adapter: "memory",
plugins: ["media", "route-docs"],
alias: "@/",
cssFile:
framework === "nextjs" ? "app/globals.css" : "src/styles/app.css",
});
const stackClientFile = plan.files.find((file) =>
file.path.endsWith("stack-client.tsx"),
);
const pagesLayoutFile = plan.files.find((file) =>
file.content.includes("<StackProvider"),
);

expect(stackClientFile?.content).toContain("media: mediaClientPlugin(),");
expect(stackClientFile?.content).toContain(
"routeDocs: routeDocsClientPlugin(),",
);
expect(stackClientFile?.content).not.toContain("apiBaseURL:");
expect(stackClientFile?.content).not.toContain("siteBasePath:");
expect(stackClientFile?.content).toContain(
`return ${browserSiteURLExpression} || window.location.origin`,
);
expect(stackClientFile?.content).toContain(
"const baseURL = getBaseURL(options?.origin)",
);
expect(stackClientFile?.content).toContain(
"if (serverOrigin) return serverOrigin",
);
expect(stackClientFile?.content).toContain(
"if (process.env.BTST_SITE_URL) return process.env.BTST_SITE_URL",
);
expect(pagesLayoutFile?.content).not.toContain("as never");
expect(pagesLayoutFile?.content).not.toContain('"media": {');
expect(pagesLayoutFile?.content).not.toContain("queryClient,");
},
);

it("uses shared query client utility in react-router pages route template", async () => {
const plan = await buildScaffoldPlan({
framework: "react-router",
Expand Down
19 changes: 9 additions & 10 deletions packages/cli/src/utils/scaffold-plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ const CANONICAL_CLIENT_PLUGIN_KEYS = new Set<PluginKey>([
"comments",
"form-builder",
"kanban",
"media",
Comment thread
olliethedev marked this conversation as resolved.
Resolved
"route-docs",
]);

function getFrameworkPaths(framework: Framework, cssFile: string) {
Expand Down Expand Up @@ -66,10 +68,14 @@ function getFrameworkPaths(framework: Framework, cssFile: string) {

function getPublicSiteURLVar(framework: Framework) {
if (framework === "nextjs") return "NEXT_PUBLIC_SITE_URL";
if (framework === "react-router") return "PUBLIC_SITE_URL";
return "VITE_PUBLIC_SITE_URL";
}

function getBrowserSiteURLExpression(framework: Framework) {
if (framework === "nextjs") return "process.env.NEXT_PUBLIC_SITE_URL";
return "import.meta.env.VITE_PUBLIC_SITE_URL";
}

function getPagesLayoutFilePath(framework: Framework): string {
if (framework === "nextjs") return "app/pages/layout.tsx";
if (framework === "react-router") return "app/routes/pages/_layout.tsx";
Expand Down Expand Up @@ -179,9 +185,6 @@ function buildPluginTemplateContext(
if (CANONICAL_CLIENT_PLUGIN_KEYS.has(m.key)) {
return `\t\t\t${m.configKey}: ${m.clientSymbol}(),`;
}
if (m.key === "route-docs") {
return `\t\t\t${m.configKey}: ${m.clientSymbol}({\n\t\t\t\tqueryClient,\n\t\t\t\tsiteBasePath: "/pages",\n\t\t\t}),`;
}
const siteBase = "/pages";
return `\t\t\t${m.configKey}: ${m.clientSymbol}({
\t\t\t\tapiBaseURL: baseURL,
Expand All @@ -194,18 +197,13 @@ function buildPluginTemplateContext(
.join("\n"),
pagesLayoutOverrides: clientMetas
.map((m) => {
if (m.key === "route-docs") {
if (m.key === "route-docs" || m.key === "media") {
return "";
}
const layoutFile = getPagesLayoutFilePath(framework);
if (m.key === "comments") {
return "";
}
if (m.key === "media") {
return `\t\t\t\t\t"${m.key}": {
\t\t\t\t\t\tqueryClient,
\t\t\t\t\t},`;
}
if (m.key === "blog") {
return `\t\t\t\t\t"${m.key}": {
\t\t\t\t\t\tuploadImage: async () => {
Expand Down Expand Up @@ -329,6 +327,7 @@ export async function buildScaffoldPlan(
const sharedContext = {
alias: input.alias,
providerApiLiteral: '{{ baseURL, basePath: "/api/data" }}',
browserSiteURLExpression: getBrowserSiteURLExpression(input.framework),
publicSiteURLVar: getPublicSiteURLVar(input.framework),
useGlobalSingleton:
input.framework === "nextjs" && input.adapter === "memory",
Expand Down
22 changes: 17 additions & 5 deletions packages/stack/registry/btst-media.json

Large diffs are not rendered by default.

7 changes: 6 additions & 1 deletion packages/stack/scripts/build-registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,12 @@ const PLUGINS: PluginConfig[] = [
// the package must be present at build time.
extraNpmDeps: ["@vercel/blob"],
extraRegistryDeps: [],
pluginRootFiles: ["types.ts", "schemas.ts", "permissions.ts"],
pluginRootFiles: [
"types.ts",
"schemas.ts",
"permissions.ts",
"asset-url.ts",
],
},
];

Expand Down
Loading
Loading