@remix-run/spa 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Placeholder Package
+# spa
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
+Client-rendered application routing for Remix. It connects a standard fetch router to the browser
+UI runtime without exposing the response carrier used to associate route responses with Remix
+nodes.
+
+## Features
+
+- **Standard fetch routing** - Preserve `Request` to `Response` dispatch, redirects, status codes,
+  headers, middleware, and cancellation
+- **Node rendering middleware** - Render `RemixNode` values through `context.render()`
+- **Browser runtime** - Resolve the current URL and future frame navigations through the router
+- **Initial fallback** - Display an interactive Remix node while the first route loads
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Install `render()` before middleware and route handlers that use `context.render()`, then pass the
+router to `run()`.
+
+```tsx
+import { createRouter } from 'remix/router'
+import { get, route } from 'remix/routes'
+import { render, run } from 'remix/spa'
+
+const routes = route({
+  home: get('/'),
+  about: get('/about'),
+})
+
+const router = createRouter({
+  middleware: [render()],
+  defaultHandler({ render }) {
+    return render(<h1>Not Found</h1>, { status: 404 })
+  },
+})
+
+router.map(routes, {
+  actions: {
+    home({ render }) {
+      return render(<h1>Home</h1>)
+    },
+    about({ render }) {
+      return render(<h1>About</h1>)
+    },
+  },
+})
+
+const app = run(router, { fallback: <p>Loading…</p> })
+await app.ready()
+```
+
+The router remains an ordinary fetch router, so its normal actions, controllers, middleware, and
+context typing continue to apply.
+
+## Wrapping Route Content
+
+Pass a request-aware transform to `render()` when every route should share an application shell.
+
+```tsx
+const router = createRouter({
+  middleware: [
+    render((content, { url }) => (
+      <main data-pathname={url.pathname}>
+        <nav>{/* ... */}</nav>
+        {content}
+      </main>
+    )),
+  ],
+})
+```
+
+## Related Packages
+
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Request
+  routing, controllers, and middleware context
+- [`render-middleware`](https://github.com/remix-run/remix/tree/main/packages/render-middleware) -
+  Request-scoped renderer middleware
+- [`ui`](https://github.com/remix-run/remix/tree/main/packages/ui) - Remix components, frames, and
+  browser runtime
+
+## Related Work
+
+- [Fetch standard](https://fetch.spec.whatwg.org/) - The request and response model preserved by SPA
+  routers
+- [Navigation API](https://wicg.github.io/navigation-api/) - Browser navigation lifecycle used by
+  the Remix UI runtime
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { render, run, type Render, type RenderTransform, type Router, type RunOptions, type Runtime, } from './lib/spa.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,MAAM,EACX,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,OAAO,GACb,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { render, run, } from './lib/spa.js';

package/dist/lib/spa.d.ts

@@ -0,0 +1,65 @@
+import type { Middleware, RequestContext } from '@remix-run/fetch-router';
+import { type Renderer } from '@remix-run/render-middleware';
+import { type AppRuntime, type RemixNode } from '@remix-run/ui';
+/** Creates a response that the SPA runtime can render. */
+export interface Render {
+    /**
+     * Creates a renderable route response.
+     *
+     * @param node Node to render.
+     * @param init Optional response status and headers.
+     * @returns A response understood by the SPA runtime.
+     */
+    (node: RemixNode, init?: ResponseInit): Response;
+}
+/** Transforms a route node before the SPA runtime renders it. */
+export interface RenderTransform {
+    /**
+     * Transforms a node using the active request context.
+     *
+     * @param node Node returned by the route.
+     * @param context Active request context.
+     * @returns The node to render.
+     */
+    (node: RemixNode, context: RequestContext): RemixNode;
+}
+/** Minimal router contract used by {@link run}. */
+export interface Router {
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+/** Client runtime returned by {@link run}. */
+export type Runtime = Omit<AppRuntime, 'ready'> & {
+    /** Resolves after the client runtime starts and the initial route renders. */
+    ready(): Promise<void>;
+};
+/** Options for starting a client-rendered Remix application. */
+export interface RunOptions {
+    /** Remix node to display while the initial route loads. */
+    fallback?: RemixNode;
+}
+type RenderMiddleware = Middleware<{
+    key: typeof Renderer;
+    value: Render;
+    property: 'render';
+}>;
+/**
+ * Creates middleware that exposes `context.render()` for SPA route responses.
+ *
+ * @param transform Optional transform that wraps or replaces route nodes.
+ * @returns Middleware that installs the SPA renderer on request context.
+ */
+export declare function render(transform?: RenderTransform): RenderMiddleware;
+/**
+ * Starts a client-rendered Remix application for the current document.
+ *
+ * The current URL and subsequent same-origin navigations are dispatched through `router`. Route
+ * handlers return responses created by the {@link render} middleware, and their associated nodes
+ * are rendered into the document's top frame.
+ *
+ * @param router Router that resolves browser requests to SPA route responses.
+ * @param options Options for the initial render.
+ * @returns The running application runtime.
+ */
+export declare function run(router: Router, options?: RunOptions): Runtime;
+export {};
+//# sourceMappingURL=spa.d.ts.map

package/dist/lib/spa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spa.d.ts","sourceRoot":"","sources":["../../src/lib/spa.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AACxE,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,SAAS,EAEf,MAAM,eAAe,CAAA;AAEtB,0DAA0D;AAC1D,MAAM,WAAW,MAAM;IACrB;;;;;;OAMG;IACH,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,SAAS,CAAA;CACtD;AAED,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC5E;AAED,8CAA8C;AAC9C,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG;IAChD,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,CAAA;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,KAAK,gBAAgB,GAAG,UAAU,CAAC;IACjC,GAAG,EAAE,OAAO,QAAQ,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,QAAQ,CAAA;CACnB,CAAC,CAAA;AAKF;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAOpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CA0BrE"}

package/dist/lib/spa.js

@@ -0,0 +1,109 @@
+import { renderWith } from '@remix-run/render-middleware';
+import { run as runRuntime, spaResponse, } from '@remix-run/ui';
+const redirectStatuses = new Set([301, 302, 303, 307, 308]);
+const maxRedirects = 10;
+/**
+ * Creates middleware that exposes `context.render()` for SPA route responses.
+ *
+ * @param transform Optional transform that wraps or replaces route nodes.
+ * @returns Middleware that installs the SPA renderer on request context.
+ */
+export function render(transform) {
+    return renderWith((context) => function render(node, init) {
+        return spaResponse.create(transform ? transform(node, context) : node, init);
+    });
+}
+/**
+ * Starts a client-rendered Remix application for the current document.
+ *
+ * The current URL and subsequent same-origin navigations are dispatched through `router`. Route
+ * handlers return responses created by the {@link render} middleware, and their associated nodes
+ * are rendered into the document's top frame.
+ *
+ * @param router Router that resolves browser requests to SPA route responses.
+ * @param options Options for the initial render.
+ * @returns The running application runtime.
+ */
+export function run(router, options = {}) {
+    let app = runRuntime({
+        loadModule() {
+            throw new Error('SPA responses cannot hydrate client entries');
+        },
+        async resolveFrame(src, options) {
+            let url = new URL(src, document.baseURI);
+            let { response, redirectedTo } = await followFrameRedirects(router, url, {
+                method: options?.method,
+                body: getRequestBody(options),
+                signal: options?.signal,
+            });
+            return spaResponse.finalize(response, redirectedTo);
+        },
+    });
+    let readyPromise = app.ready().then(async () => {
+        if (options.fallback !== undefined) {
+            await app.frames.top.replace(options.fallback);
+        }
+        await app.frames.top.reload();
+    });
+    return Object.assign(app, {
+        ready: () => readyPromise,
+    });
+}
+async function followFrameRedirects(router, url, init) {
+    let initialOrigin = url.origin;
+    let method = init.method?.toUpperCase() ?? 'GET';
+    let body = init.body;
+    let redirectedTo;
+    for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
+        let response = await router.fetch(url, { ...init, method, body });
+        if (!redirectStatuses.has(response.status)) {
+            return { response, redirectedTo };
+        }
+        let location = response.headers.get('Location');
+        if (!location)
+            return { response };
+        if (redirectCount === maxRedirects) {
+            throw new TypeError(`SPA route exceeded ${maxRedirects} redirects`);
+        }
+        let nextUrl = new URL(location, url);
+        if (nextUrl.origin !== initialOrigin) {
+            throw new TypeError('SPA routes cannot redirect to another origin');
+        }
+        if ((response.status === 303 && method !== 'GET' && method !== 'HEAD') ||
+            ((response.status === 301 || response.status === 302) && method === 'POST')) {
+            method = 'GET';
+            body = undefined;
+        }
+        url = nextUrl;
+        redirectedTo = url.href;
+    }
+    throw new TypeError(`SPA route exceeded ${maxRedirects} redirects`);
+}
+// Frame reloads can receive raw FormData without going through form navigation. Encode it here so
+// manual reloads use the requested form encoding instead of always sending multipart bodies.
+function getRequestBody(options) {
+    let formData = options?.formData;
+    let method = options?.method;
+    if (!formData || !method || ['get', 'head'].includes(method.toLowerCase()))
+        return;
+    let encType = options?.encType;
+    if (encType === 'text/plain') {
+        let body = '';
+        for (let [name, value] of formData) {
+            name = normalizeLineBreaks(name);
+            value = normalizeLineBreaks(typeof value === 'string' ? value : value.name);
+            body += `${name}=${value}\r\n`;
+        }
+        return new Blob([body], { type: 'text/plain' });
+    }
+    if (encType !== 'application/x-www-form-urlencoded')
+        return formData;
+    let body = new URLSearchParams();
+    for (let [name, value] of formData) {
+        body.append(name, typeof value === 'string' ? value : value.name);
+    }
+    return body;
+}
+function normalizeLineBreaks(value) {
+    return value.replace(/\r\n|\r|\n/g, '\r\n');
+}

package/package.json

@@ -1,14 +1,55 @@
 {
   "name": "@remix-run/spa",
-  "version": "0.0.0",
-  "description": "Placeholder package for Remix CI/OIDC setup",
+  "version": "0.1.0",
+  "description": "Client-rendered application routing for Remix",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/remix-run/remix.git",
     "directory": "packages/spa"
   },
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/spa#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test*.ts",
+    "!src/**/*.test*.tsx"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@types/dom-navigation": "^1.0.7",
+    "@types/node": "^24.6.0",
+    "typescript": "^7.0.2",
+    "@remix-run/assert": "^0.3.0",
+    "@remix-run/test": "^0.6.0"
+  },
+  "dependencies": {
+    "@remix-run/render-middleware": "^0.2.0",
+    "@remix-run/ui": "^0.8.0",
+    "@remix-run/fetch-router": "^0.21.0"
+  },
+  "keywords": [
+    "remix",
+    "spa",
+    "router",
+    "client",
+    "browser"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "remix test",
+    "test:bun": "bun x --bun remix test",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  render,
+  run,
+  type Render,
+  type RenderTransform,
+  type Router,
+  type RunOptions,
+  type Runtime,
+} from './lib/spa.ts'

package/src/lib/spa.ts

@@ -0,0 +1,187 @@
+import type { Middleware, RequestContext } from '@remix-run/fetch-router'
+import { renderWith, type Renderer } from '@remix-run/render-middleware'
+import {
+  run as runRuntime,
+  spaResponse,
+  type AppRuntime,
+  type RemixNode,
+  type ResolveFrameOptions,
+} from '@remix-run/ui'
+
+/** Creates a response that the SPA runtime can render. */
+export interface Render {
+  /**
+   * Creates a renderable route response.
+   *
+   * @param node Node to render.
+   * @param init Optional response status and headers.
+   * @returns A response understood by the SPA runtime.
+   */
+  (node: RemixNode, init?: ResponseInit): Response
+}
+
+/** Transforms a route node before the SPA runtime renders it. */
+export interface RenderTransform {
+  /**
+   * Transforms a node using the active request context.
+   *
+   * @param node Node returned by the route.
+   * @param context Active request context.
+   * @returns The node to render.
+   */
+  (node: RemixNode, context: RequestContext): RemixNode
+}
+
+/** Minimal router contract used by {@link run}. */
+export interface Router {
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>
+}
+
+/** Client runtime returned by {@link run}. */
+export type Runtime = Omit<AppRuntime, 'ready'> & {
+  /** Resolves after the client runtime starts and the initial route renders. */
+  ready(): Promise<void>
+}
+
+/** Options for starting a client-rendered Remix application. */
+export interface RunOptions {
+  /** Remix node to display while the initial route loads. */
+  fallback?: RemixNode
+}
+
+type RenderMiddleware = Middleware<{
+  key: typeof Renderer
+  value: Render
+  property: 'render'
+}>
+
+const redirectStatuses = new Set([301, 302, 303, 307, 308])
+const maxRedirects = 10
+
+/**
+ * Creates middleware that exposes `context.render()` for SPA route responses.
+ *
+ * @param transform Optional transform that wraps or replaces route nodes.
+ * @returns Middleware that installs the SPA renderer on request context.
+ */
+export function render(transform?: RenderTransform): RenderMiddleware {
+  return renderWith(
+    (context) =>
+      function render(node: RemixNode, init?: ResponseInit): Response {
+        return spaResponse.create(transform ? transform(node, context) : node, init)
+      },
+  )
+}
+
+/**
+ * Starts a client-rendered Remix application for the current document.
+ *
+ * The current URL and subsequent same-origin navigations are dispatched through `router`. Route
+ * handlers return responses created by the {@link render} middleware, and their associated nodes
+ * are rendered into the document's top frame.
+ *
+ * @param router Router that resolves browser requests to SPA route responses.
+ * @param options Options for the initial render.
+ * @returns The running application runtime.
+ */
+export function run(router: Router, options: RunOptions = {}): Runtime {
+  let app = runRuntime({
+    loadModule() {
+      throw new Error('SPA responses cannot hydrate client entries')
+    },
+    async resolveFrame(src, options) {
+      let url = new URL(src, document.baseURI)
+      let { response, redirectedTo } = await followFrameRedirects(router, url, {
+        method: options?.method,
+        body: getRequestBody(options),
+        signal: options?.signal,
+      })
+      return spaResponse.finalize(response, redirectedTo)
+    },
+  })
+
+  let readyPromise = app.ready().then(async () => {
+    if (options.fallback !== undefined) {
+      await app.frames.top.replace(options.fallback)
+    }
+    await app.frames.top.reload()
+  })
+
+  return Object.assign(app, {
+    ready: () => readyPromise,
+  })
+}
+
+async function followFrameRedirects(
+  router: Router,
+  url: URL,
+  init: RequestInit,
+): Promise<{ response: Response; redirectedTo?: string }> {
+  let initialOrigin = url.origin
+  let method = init.method?.toUpperCase() ?? 'GET'
+  let body = init.body
+  let redirectedTo: string | undefined
+
+  for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
+    let response = await router.fetch(url, { ...init, method, body })
+    if (!redirectStatuses.has(response.status)) {
+      return { response, redirectedTo }
+    }
+
+    let location = response.headers.get('Location')
+    if (!location) return { response }
+    if (redirectCount === maxRedirects) {
+      throw new TypeError(`SPA route exceeded ${maxRedirects} redirects`)
+    }
+
+    let nextUrl = new URL(location, url)
+    if (nextUrl.origin !== initialOrigin) {
+      throw new TypeError('SPA routes cannot redirect to another origin')
+    }
+
+    if (
+      (response.status === 303 && method !== 'GET' && method !== 'HEAD') ||
+      ((response.status === 301 || response.status === 302) && method === 'POST')
+    ) {
+      method = 'GET'
+      body = undefined
+    }
+
+    url = nextUrl
+    redirectedTo = url.href
+  }
+
+  throw new TypeError(`SPA route exceeded ${maxRedirects} redirects`)
+}
+
+// Frame reloads can receive raw FormData without going through form navigation. Encode it here so
+// manual reloads use the requested form encoding instead of always sending multipart bodies.
+function getRequestBody(options?: ResolveFrameOptions): BodyInit | undefined {
+  let formData = options?.formData
+  let method = options?.method
+  if (!formData || !method || ['get', 'head'].includes(method.toLowerCase())) return
+
+  let encType = options?.encType
+
+  if (encType === 'text/plain') {
+    let body = ''
+    for (let [name, value] of formData) {
+      name = normalizeLineBreaks(name)
+      value = normalizeLineBreaks(typeof value === 'string' ? value : value.name)
+      body += `${name}=${value}\r\n`
+    }
+    return new Blob([body], { type: 'text/plain' })
+  }
+
+  if (encType !== 'application/x-www-form-urlencoded') return formData
+
+  let body = new URLSearchParams()
+  for (let [name, value] of formData) {
+    body.append(name, typeof value === 'string' ? value : value.name)
+  }
+  return body
+}
+
+function normalizeLineBreaks(value: string): string {
+  return value.replace(/\r\n|\r|\n/g, '\r\n')
+}