@tinacms/astro 0.2.0 → 0.3.0

package/src/data.test-d.ts

@@ -0,0 +1,53 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { QueryResult, RequestOptions } from './data';
+import { requestWithMetadata } from './data';
+
+interface Post {
+  title: string;
+  body: string;
+}
+
+// requestWithMetadata is the one wrapper every Astro page calls around
+// client.queries.<name>(). A regression that widened TData to `unknown`
+// would pass every runtime test, so the guarantee has to be type-level.
+
+describe('requestWithMetadata', () => {
+  it('threads the query data type through to QueryResult', async () => {
+    const result = await requestWithMetadata(
+      Promise.resolve({
+        data: { title: 't', body: 'b' } satisfies Post,
+        query: 'query Post { ... }',
+        variables: {},
+      })
+    );
+    expectTypeOf(result).toEqualTypeOf<QueryResult<Post>>();
+    expectTypeOf(result.data).toEqualTypeOf<Post>();
+  });
+
+  it('does not widen TData when given an explicit type argument', () => {
+    expectTypeOf<
+      Awaited<ReturnType<typeof requestWithMetadata<Post>>>
+    >().toEqualTypeOf<QueryResult<Post>>();
+  });
+
+  it('accepts a bare (non-promise) client result', () => {
+    expectTypeOf(requestWithMetadata).toBeCallableWith({
+      data: { title: 't', body: 'b' } satisfies Post,
+      query: 'q',
+      variables: {},
+    });
+  });
+
+  it('accepts null / undefined sources (static build, no client scope)', () => {
+    expectTypeOf(requestWithMetadata).toBeCallableWith(null);
+    expectTypeOf(requestWithMetadata).toBeCallableWith(undefined);
+  });
+});
+
+describe('RequestOptions', () => {
+  it('priority is the literal "primary" or absent', () => {
+    expectTypeOf<RequestOptions['priority']>().toEqualTypeOf<
+      'primary' | undefined
+    >();
+  });
+});

package/src/data.ts

@@ -1,29 +1,3 @@
-/**
- * `requestWithMetadata()` is the only Astro-specific call site needed
- * around the standard `client.queries.<name>(...)` pattern. In production
- * it stamps the result with the metadata `tinaField()` reads to build
- * click-to-focus markers and the `id` the bridge uses to address forms;
- * inside the editor iframe it additionally swaps `data` for the unsaved
- * overlay the bridge has POSTed for that form.
- *
- * The current `Astro.request` is read from AsyncLocalStorage scoped by
- * the middleware the `tina()` integration injects, so the call site stays
- * a single argument:
- *
- * ```ts
- * import client from '../../tina/__generated__/client';
- * import { requestWithMetadata } from '@tinacms/astro';
- *
- * const post = await requestWithMetadata(
- *   client.queries.post({ relativePath: `${slug}.md` }),
- * );
- * ```
- *
- * Outside a request scope (static builds, integration not installed) the
- * wrapper falls through to a metadata-stamped pass-through — production
- * output stays correct, just without the live overlay swap that only
- * matters during admin editing.
- */
 import { addMetadata, hashFromQuery } from '@tinacms/bridge/metadata';
 import { readOverlay } from '@tinacms/bridge/preview';
 import { recordForm } from './internal/forms-store';
@@ -36,9 +10,6 @@ export interface QueryResult<TData> {
   id: string;
 }
 
-/** Shape every `client.queries.<name>` returns. Inferring from this lets
- *  `requestWithMetadata()` stay framework-agnostic — it doesn't need to
- *  know about `PostQuery`, `PageQuery`, etc. */
 type ClientResult<TData> =
   | {
       data: TData;
@@ -48,17 +19,23 @@ type ClientResult<TData> =
   | null
   | undefined;
 
+export interface RequestOptions {
+  /** Mark the page's own document so the admin opens it on load instead
+   *  of a layout-level global. Mirrors `useTina`'s
+   *  `experimental___selectFormByFormId`. */
+  priority?: 'primary';
+}
+
 export async function requestWithMetadata<TData>(
-  source: ClientResult<TData> | Promise<ClientResult<TData>>
+  source: ClientResult<TData> | Promise<ClientResult<TData>>,
+  options?: RequestOptions
 ): Promise<QueryResult<TData>> {
   let result: ClientResult<TData> = null;
   try {
     result = (await source) ?? null;
   } catch (error) {
-    // Disk-fetch failures are normal in edit mode (a doc the editor is
-    // creating doesn't exist yet) and should never crash the page render
-    // — the bridge will populate via overlay. In production, the warning
-    // surfaces real misconfigurations.
+    // In edit mode a doc the editor is creating won't exist yet; the
+    // bridge will populate via overlay. Don't crash the render.
     console.warn('[@tinacms/astro] client query failed', error);
   }
 
@@ -83,14 +60,13 @@ export async function requestWithMetadata<TData>(
     id,
   };
 
-  // Append to the per-request forms list so the integration's middleware
-  // can splice the bridge wiring into edit-mode pages without the caller
-  // touching their layout. No-ops outside a request scope (static builds).
+  // No-op outside a request scope (static builds).
   recordForm({
     id,
     query,
     variables,
     data: enriched.data as unknown as object,
+    priority: options?.priority,
   });
 
   return enriched;

package/src/integration.ts

@@ -1,49 +1,94 @@
-/**
- * Tina Astro integration. Wires the middleware that exposes
- * `Astro.locals.tinaEdit` so pages and components can branch on edit
- * context without writing `src/middleware.ts` themselves.
- *
- * Usage:
- *
- * ```ts
- * // astro.config.mjs
- * import { defineConfig } from 'astro/config';
- * import tina from '@tinacms/astro/integration';
- *
- * export default defineConfig({
- *   integrations: [tina()],
- * });
- * ```
- */
-import type { AstroIntegration } from 'astro';
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
+import type { Plugin as VitePlugin } from 'vite';
 
 export interface TinaIntegrationOptions {
-  /** Override the middleware ordering relative to other integrations.
-   *  Defaults to `'pre'` so `Astro.locals.tinaEdit` is populated before
-   *  user middleware sees the request. */
   middlewareOrder?: 'pre' | 'post';
 }
 
+/** Where the injected bridge bootstrap imports the bridge bundle from. */
+const BRIDGE_ROUTE = '/admin/bridge.js';
+
 export default function tina(
   options: TinaIntegrationOptions = {}
 ): AstroIntegration {
   const { middlewareOrder = 'pre' } = options;
+  // Resolved client output dir, captured at config:done and consumed at
+  // build:done (only then is the final output location known).
+  let clientDir: URL | undefined;
+
   return {
     name: '@tinacms/astro',
     hooks: {
-      'astro:config:setup': ({ addMiddleware, injectRoute }) => {
+      'astro:config:setup': ({ addMiddleware, updateConfig }) => {
         addMiddleware({
           entrypoint: '@tinacms/astro/middleware',
           order: middlewareOrder,
         });
-        // The middleware splices a `<script type="module" src="/_tina/bridge.js">`
-        // into edit-mode pages. This route serves the bundled bridge.
-        // Production pages never reference it (the script tag isn't injected).
-        injectRoute({
-          pattern: '/_tina/bridge.js',
-          entrypoint: '@tinacms/astro/bridge-route',
-        });
+        // Dev: serve the bridge straight from the package rather than writing
+        // it into the user's source tree — config-time writes churn
+        // public/admin on every `astro dev`/`astro build`, break on read-only
+        // or sandboxed filesystems, and can race `tinacms build`.
+        updateConfig({ vite: { plugins: [bridgeDevPlugin()] } });
+      },
+      'astro:config:done': ({ config }) => {
+        clientDir = config.build.client;
       },
+      'astro:build:done': ({ logger }) => {
+        // Build: emit the bridge next to the admin SPA in the *output* tree.
+        // `build.client` is where `public/` is copied to and what every
+        // adapter serves statically, so the bridge ships as a static asset
+        // (some adapters won't emit injected on-demand routes — e.g.
+        // @astrojs/vercel in static mode) without touching the source tree.
+        if (!clientDir) return;
+        emitBridgeAsset(fileURLToPath(new URL('admin/', clientDir)), logger);
+      },
+    },
+  };
+}
+
+function resolveBridge(): string {
+  return createRequire(import.meta.url).resolve('@tinacms/bridge');
+}
+
+// Dev-only Vite plugin that answers `/admin/bridge.js` from the installed
+// bridge package. The bridge never varies per request, so a single readFile
+// per request is fine and nothing is persisted to disk.
+function bridgeDevPlugin(): VitePlugin {
+  return {
+    name: '@tinacms/astro:bridge-dev',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const path = (req.url || '').split('?')[0];
+        if (path !== BRIDGE_ROUTE) {
+          next();
+          return;
+        }
+        try {
+          const body = readFileSync(resolveBridge());
+          res.setHeader('Content-Type', 'text/javascript');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(body);
+        } catch (error) {
+          res.statusCode = 500;
+          res.end(`/* @tinacms/astro: bridge unavailable: ${error} */`);
+        }
+      });
     },
   };
 }
+
+function emitBridgeAsset(adminDir: string, logger: AstroIntegrationLogger) {
+  try {
+    mkdirSync(adminDir, { recursive: true });
+    copyFileSync(resolveBridge(), join(adminDir, 'bridge.js'));
+  } catch (error) {
+    logger.warn(
+      `could not emit admin/bridge.js — visual editing will not load: ${error}`
+    );
+  }
+}

package/src/internal/admin-origin.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve `PUBLIC_TINA_ADMIN_ORIGIN` (comma-separated allowed) from
+ * Astro's `import.meta.env`. Returns `null` when unset — the bridge then
+ * falls back to `window.location.origin`.
+ */
+export function adminOrigins(): string[] | null {
+  const env = (
+    import.meta as ImportMeta & {
+      env?: Record<string, string | undefined>;
+    }
+  ).env;
+  const raw = env?.PUBLIC_TINA_ADMIN_ORIGIN;
+  if (!raw) return null;
+  const origins = raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return origins.length > 0 ? origins : null;
+}

package/src/internal/forms-store.ts

@@ -1,26 +1,16 @@
-/**
- * Per-request collector for `tina()` results. Each call pushes its
- * `{id, query, variables, data}` payload here so the integration's
- * middleware can read the full list at response time and splice the
- * bridge wiring into edit-mode pages — the user never writes a `forms`
- * prop or imports a wiring component.
- *
- * Initialised by the middleware the `tina()` integration injects.
- *
- * The store is keyed by a `Symbol.for(...)` slot on `globalThis` so all
- * bundle copies of this module (esbuild inlines it into each entry that
- * imports it) share the same instance — without that, the middleware
- * would `.run()` one ALS while `tina()` reads from a different one.
- */
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { escapeAttr } from './escape';
 
 export interface CollectedForm {
   id: string;
   query: string;
   variables: object;
   data: object;
+  priority?: 'primary';
 }
 
+// Symbol slot on globalThis so bundle copies (esbuild inlines this module
+// into each entry that imports it) share one ALS instance.
 const STORE_KEY = Symbol.for('@tinacms/astro/forms-store');
 
 type Slot = { [STORE_KEY]?: AsyncLocalStorage<CollectedForm[]> };
@@ -33,9 +23,28 @@ export const formsStore: AsyncLocalStorage<CollectedForm[]> = (slot[
 export function recordForm(form: CollectedForm): void {
   const list = formsStore.getStore();
   if (!list) return;
-  // Same id can appear multiple times (e.g., layout + page both fetch the
-  // global). De-dup on id so the bridge doesn't see two open events for
-  // the same form.
-  if (list.some((existing) => existing.id === form.id)) return;
+  // Same id can appear twice (layout + page both fetch the global). Dedup
+  // and upgrade to `primary` if a later call asserts it.
+  const existing = list.find((entry) => entry.id === form.id);
+  if (existing) {
+    if (form.priority === 'primary') existing.priority = 'primary';
+    return;
+  }
   list.push(form);
 }
+
+export function sortByPriority(forms: CollectedForm[]): CollectedForm[] {
+  return [...forms].sort(
+    (a, b) =>
+      (a.priority === 'primary' ? 0 : 1) - (b.priority === 'primary' ? 0 : 1)
+  );
+}
+
+export function renderFormPayloadDiv(
+  form: CollectedForm,
+  primary: boolean
+): string {
+  return `<div data-tina-form="${escapeAttr(JSON.stringify(form))}"${
+    primary ? ' data-tina-primary' : ''
+  } hidden></div>`;
+}

package/src/island-route.ts

@@ -1,33 +1,19 @@
 /**
- * Factory for the dynamic `/tina-island/[name]` endpoint the bridge calls
- * to refetch a region with the editor's overlay applied. Each entry in
- * `islands` describes one editable region: how to load its data, which
- * Astro component to render, and the wrapper element the page-side
- * `<div data-tina-island>` is expected to swap.
- *
- * @experimental
- *
- * Built on Astro's `experimental_AstroContainer`, which is itself
- * experimental — Astro may break the underlying API in any minor or patch
- * release. The shape of `createIslandRoute` is similarly experimental and
- * will graduate once the container API stabilises.
- *
- * Usage:
- *
- * ```ts
- * // src/pages/tina-island/[name].ts
- * import { experimental_createIslandRoute } from '@tinacms/astro/experimental';
- * import { islands } from '../../lib/islands';
- *
- * export const prerender = false;
- * export const ALL = experimental_createIslandRoute(islands);
- * ```
+ * @experimental Built on Astro's `experimental_AstroContainer`. Both APIs
+ * may break in any Astro minor/patch.
  */
+import { PREVIEW_CONTENT_TYPE, PRIME_HEADER } from '@tinacms/bridge/preview';
 import type { APIRoute } from 'astro';
 import { experimental_AstroContainer as AstroContainer } from 'astro/container';
 import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
-import { PREVIEW_CONTENT_TYPE } from '@tinacms/bridge/preview';
 import { escapeAttr } from './internal/escape';
+import {
+  type CollectedForm,
+  formsStore,
+  renderFormPayloadDiv,
+  sortByPriority,
+} from './internal/forms-store';
+import { requestStore } from './internal/request-context';
 
 export interface IslandWrapper {
   tag: string;
@@ -62,13 +48,23 @@ export function experimental_createIslandRoute(
       return new Response(`Unknown island "${params.name}"`, { status: 404 });
     }
 
+    const priming = request.headers.get(PRIME_HEADER) !== null;
+
     try {
-      const data = await island.fetch(request, url.searchParams);
-      const container = await AstroContainer.create();
-      const html = await container.renderToString(island.component, {
-        props: island.propsFromData(data, url.searchParams),
-      });
-      return new Response(wrapIsland(html, island.wrapper, url), {
+      const forms: CollectedForm[] = [];
+      const html = await requestStore.run(request, () =>
+        formsStore.run(forms, async () => {
+          const data = await island.fetch(request, url.searchParams);
+          const container = await AstroContainer.create();
+          return container.renderToString(island.component, {
+            props: island.propsFromData(data, url.searchParams),
+          });
+        })
+      );
+      const body =
+        (priming ? renderFormPayloads(forms) : '') +
+        wrapIsland(html, island.wrapper, url);
+      return new Response(body, {
         headers: {
           'Content-Type': 'text/html; charset=utf-8',
           'Cache-Control': 'no-store',
@@ -80,12 +76,8 @@ export function experimental_createIslandRoute(
   };
 }
 
-/**
- * Layered defense for an endpoint whose response is shaped by the request
- * body. The bridge always issues a same-origin POST with the Tina-preview
- * content-type; production traffic never matches all three signals so it
- * can never reach the renderer.
- */
+// Bridge issues a same-origin POST with the Tina-preview content-type;
+// production traffic can't match all three signals.
 function rejectIfUnsafe(request: Request): Response | null {
   if (request.method !== 'POST') {
     return new Response('Method Not Allowed', { status: 405 });
@@ -94,13 +86,20 @@ function rejectIfUnsafe(request: Request): Response | null {
   if (!contentType.includes(PREVIEW_CONTENT_TYPE)) {
     return new Response('Not Found', { status: 404 });
   }
-  const fetchSite = request.headers.get('sec-fetch-site');
-  if (fetchSite === 'cross-site' || fetchSite === 'cross-origin') {
+  if (request.headers.get('sec-fetch-site') === 'cross-site') {
     return new Response('Forbidden', { status: 403 });
   }
   return null;
 }
 
+// Keyed on the explicit `primary` flag (not position): each island route
+// call is independent, so position would tag every island's first form.
+function renderFormPayloads(forms: CollectedForm[]): string {
+  return sortByPriority(forms)
+    .map((form) => renderFormPayloadDiv(form, form.priority === 'primary'))
+    .join('');
+}
+
 function wrapIsland(html: string, wrapper: IslandWrapper, url: URL): string {
   const cls = wrapper.className
     ? ` class="${escapeAttr(wrapper.className)}"`

package/src/middleware.ts

@@ -1,29 +1,24 @@
-/**
- * Astro middleware injected by the `tina()` integration.
- *
- * - Resolves `isEditMode(request)` once and stashes it on
- *   `context.locals.tinaEdit` so pages and components can branch on edit
- *   context without re-parsing headers.
- * - Scopes the request and a per-request forms collector via
- *   AsyncLocalStorage so `tina()` reads them implicitly — the caller
- *   never threads `Astro.request` through their loaders.
- * - In edit mode only, splices `<div data-tina-form>` payloads and a
- *   `<script>` that loads `/_tina/bridge.js` before `</head>`. The user
- *   writes nothing in their layout, and production HTML is byte-
- *   identical to a Tina-free Astro app.
- * - In edit mode only, refreshes the `__tina_edit` cookie so the session
- *   survives in-iframe link clicks (whose Referer is the previous
- *   preview page, not `/admin/`).
- */
 import type { MiddlewareHandler } from 'astro';
-import { escapeAttr } from './internal/escape';
-import { type CollectedForm, formsStore } from './internal/forms-store';
+import { adminOrigins } from './internal/admin-origin';
+import {
+  type CollectedForm,
+  formsStore,
+  renderFormPayloadDiv,
+  sortByPriority,
+} from './internal/forms-store';
 import { requestStore } from './internal/request-context';
 import { EDIT_COOKIE_HEADER, isEditMode } from './is-edit-mode';
 
 const HEAD_CLOSE = '</head>';
 
 export const onRequest: MiddlewareHandler = (context, next) => {
+  // Prerendered routes can never be in edit mode; reading their synthetic
+  // build-time headers would only emit Astro's request.headers warning.
+  if (context.isPrerendered) {
+    (context.locals as { tinaEdit?: boolean }).tinaEdit = false;
+    return next();
+  }
+
   const editing = isEditMode(context.request);
   (context.locals as { tinaEdit?: boolean }).tinaEdit = editing;
 
@@ -73,11 +68,10 @@ function editModeInit(response: Response): ResponseInit {
 }
 
 function renderInjection(forms: CollectedForm[]): string {
-  const formDivs = forms
-    .map(
-      (form) =>
-        `<div data-tina-form="${escapeAttr(JSON.stringify(form))}" hidden></div>`
-    )
+  // No explicit priority => sort is a no-op and the first form (page
+  // frontmatter runs before its layout's) wins as primary.
+  const formDivs = sortByPriority(forms)
+    .map((form, i) => renderFormPayloadDiv(form, i === 0))
     .join('');
   return formDivs + bridgeScript();
 }
@@ -87,32 +81,9 @@ function bridgeScript(): string {
   const initArg = origins ? `{adminOrigin:${JSON.stringify(origins)}}` : '';
   return (
     `<script type="module">` +
-    `import{init,refreshForms}from"/_tina/bridge.js";` +
+    `import{init,refreshForms}from"/admin/bridge.js";` +
     `init(${initArg});` +
     `document.addEventListener("astro:page-load",refreshForms);` +
     `</script>`
   );
 }
-
-/**
- * Read `PUBLIC_TINA_ADMIN_ORIGIN` (comma-separated for multi-origin setups)
- * from Astro's `import.meta.env`. Returns null when unset so `bridge.init()`
- * falls back to `window.location.origin` — the common same-host case.
- *
- * `import.meta.env` is cast inline because the package ships no `env.d.ts`
- * to keep the public type surface free of Vite/Astro client-types coupling.
- */
-function adminOrigins(): string[] | null {
-  const env = (
-    import.meta as ImportMeta & {
-      env?: Record<string, string | undefined>;
-    }
-  ).env;
-  const raw = env?.PUBLIC_TINA_ADMIN_ORIGIN;
-  if (!raw) return null;
-  const origins = raw
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
-  return origins.length > 0 ? origins : null;
-}

package/src/vite.ts

@@ -0,0 +1,40 @@
+import type { Plugin } from 'vite';
+
+/**
+ * Dev-only Vite plugin that redirects `/admin` (and `/admin/`) to
+ * `/admin/index.html`.
+ *
+ * In `astro dev`, the admin SPA is served straight from `public/admin/` and
+ * Vite does not resolve a directory index for it, so a bare `/admin` request
+ * 404s. This plugin makes `/admin` land on the SPA the same way it does in a
+ * production build. It only applies to the dev server (`apply: 'serve'`); a
+ * built site serves `public/admin/index.html` itself.
+ *
+ * @example
+ * // astro.config.mjs
+ * import { tinaAdminDevRedirect } from '@tinacms/astro/vite';
+ *
+ * export default defineConfig({
+ *   vite: { plugins: [tinaAdminDevRedirect()] },
+ * });
+ */
+export function tinaAdminDevRedirect(): Plugin {
+  return {
+    name: 'tina-admin-dev-redirect',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const path = (req.url || '').split('?')[0];
+        if (path === '/admin' || path === '/admin/') {
+          res.statusCode = 302;
+          res.setHeader('Location', '/admin/index.html');
+          res.end();
+          return;
+        }
+        next();
+      });
+    },
+  };
+}
+
+export default tinaAdminDevRedirect;

package/dist/bridge-route.d.ts

@@ -1,3 +0,0 @@
-import type { APIRoute } from 'astro';
-export declare const prerender = false;
-export declare const GET: APIRoute;

package/dist/bridge-route.js

@@ -1,22 +0,0 @@
-// src/bridge-route.ts
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-var require2 = createRequire(import.meta.url);
-var cached;
-function loadBridge() {
-  if (cached !== void 0) return cached;
-  const bridgePath = require2.resolve("@tinacms/bridge");
-  cached = readFileSync(bridgePath, "utf-8");
-  return cached;
-}
-var prerender = false;
-var GET = () => new Response(loadBridge(), {
-  headers: {
-    "Content-Type": "application/javascript; charset=utf-8",
-    "Cache-Control": "public, max-age=31536000, immutable"
-  }
-});
-export {
-  GET,
-  prerender
-};

package/src/bridge-route.ts

@@ -1,33 +0,0 @@
-/**
- * Astro endpoint injected by the `tina()` integration. Serves the bridge
- * as a single self-contained ESM bundle at `/_tina/bridge.js`. Loaded by
- * the inline `<script type="module">` the middleware splices into edit-
- * mode pages — production visitors never reach this URL.
- *
- * `@tinacms/bridge`'s build already emits a fully bundled `dist/index.js`
- * (no relative imports remain), so we stream it back as-is and let the
- * browser cache it immutably.
- */
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import type { APIRoute } from 'astro';
-
-const require = createRequire(import.meta.url);
-let cached: string | undefined;
-
-function loadBridge(): string {
-  if (cached !== undefined) return cached;
-  const bridgePath = require.resolve('@tinacms/bridge');
-  cached = readFileSync(bridgePath, 'utf-8');
-  return cached;
-}
-
-export const prerender = false;
-
-export const GET: APIRoute = () =>
-  new Response(loadBridge(), {
-    headers: {
-      'Content-Type': 'application/javascript; charset=utf-8',
-      'Cache-Control': 'public, max-age=31536000, immutable',
-    },
-  });