@pitlane/dev 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @pitlane/dev
 
+## 0.4.0
+
+SPA mode.
+
+- `remix({ server: false })` targets client-rendered apps. No server
+  environment is configured, nothing builds to `dist/ssr`, and `vite build`
+  emits a static site from `index.html`. What remains is the part a SPA still
+  wants: component HMR through the `remix/ui-hmr` browser transform, including
+  the arrow-form normalization, so edits hot-swap in place and keep live
+  component state. Every `server*` option goes with it, and `clientEntry` too,
+  and `<HMR />` from `pitlane:dev` resolves to the inert component — there is
+  no server data to revalidate.
+- The option is named for what it removes. React Router spells the same switch
+  `ssr: false`, which reads like it only turns off server rendering; it does
+  not, in either plugin. An app that wants browser-rendered UI in front of
+  routes that still run per request keeps `server: true` and writes a server
+  entry that answers data and a shell.
+- SPA mode works under Vite's experimental bundled dev mode
+  (`experimental.bundledDev` / `vite dev --experimentalBundle`), component
+  hot-swap included. Server-rendered apps do not: bundled dev serves only
+  bundle entrypoints, so the client module URLs an SSR render writes into its
+  HTML have nothing behind them. That is upstream's Phase 4 (server
+  environments), still a prototype.
+
 ## 0.3.0
 
 Dev-time hot module replacement.

package/README.md

@@ -114,6 +114,7 @@ Leave it unguarded: in a production build the specifier resolves to a component
 
 ```ts
 remix({
+    server: true, // default — false selects SPA mode
     clientEntry: "app/entry.browser", // default — false disables the client build
     serverEntry: "app/entry.server", // default
     serverEnvironments: ["ssr"], // default
@@ -123,11 +124,57 @@ remix({
 
 | Option               | Type              | Default               | Purpose                                                                                                                                                           |
 | -------------------- | ----------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server`             | `boolean`         | `true`                | Whether the app has a server. Pass `false` for [SPA mode](#spa-mode), which ignores every option below.                                                           |
 | `clientEntry`        | `string \| false` | `"app/entry.browser"` | Client entry module. Pass `false` for fully server-rendered apps with no hydration.                                                                               |
 | `serverEntry`        | `string`          | `"app/entry.server"`  | Server entry module, built as `dist/ssr/index.js`.                                                                                                                |
 | `serverEnvironments` | `string[]`        | `["ssr"]`             | Environment names the `clientEntry()` transform treats as "server".                                                                                               |
 | `serverHandler`      | `boolean`         | `true`                | Serve dev requests through your server entry. Set `false` when `@cloudflare/vite-plugin`, `@netlify/vite-plugin`, or `nitro/vite` owns dev-time request handling. |
 
+## SPA mode
+
+Some apps have no server — a static host, a router that never touches one.
+`remix({ server: false })` targets those. React Router spells the same switch
+`ssr: false`:
+
+```ts
+// vite.config.ts
+import { remix } from "@pitlane/dev";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [remix({ server: false })],
+});
+```
+
+There is no server environment, nothing is built to `dist/ssr`, and
+`vite build` emits a static site from your `index.html`. The plugin's one
+remaining job is the one a SPA still wants: component HMR. Editing a component
+swaps it in place and keeps live state, arrow forms included.
+
+Every `server*` option goes with it, and `clientEntry` too — the browser entry
+is whatever `index.html` loads. `<HMR />` from `pitlane:dev` resolves to the
+inert component, because there is no server data to revalidate.
+
+Deploying means pointing every unknown URL at `index.html` so the client router
+can resolve it; on GitHub Pages that is a copy of `index.html` at `404.html`,
+on Netlify a `/* /index.html 200` redirect.
+
+The option removes the server, not the server rendering, which is what React
+Router's `ssr: false` does too. For a browser-rendered UI in front of routes
+that still run per request, stay in the default mode and let the server entry
+answer JSON on its data routes and one `remix/ui` shell on its document
+routes: nothing here asks it to render app UI. [Client rendering with a
+server](https://pitlane.tools/guides/spa#client-rendering-with-a-server) shows
+the shape.
+
+SPA mode also works under Vite's experimental bundled dev mode
+(`experimental.bundledDev`, or `vite dev --experimentalBundle`), component
+hot-swap included. Server-rendered apps do not yet: bundled dev serves only
+bundle entrypoints, so the client module URLs an SSR render writes into its
+HTML resolve to nothing. That is upstream's
+[Phase 4](https://github.com/vitejs/vite/discussions/22746) — server
+environments — still a prototype.
+
 ## The server entry contract
 
 The server entry **default-exports a fetch handler** — an object exposing `fetch(request: Request): Response | Promise<Response>`. A `createRouter()` router already is one:

package/dist/index.d.mts

@@ -9,6 +9,21 @@ interface RemixPluginOptions {
    * @default "app/entry.browser"
    */
   clientEntry?: string | false;
+  /**
+   * Whether the app has a server at all. Pass `false` for SPA mode: no
+   * server environment is configured, nothing is built to `dist/ssr`, and
+   * `vite build` emits a static site from `index.html`.
+   *
+   * This is about the server, not about server rendering. With `false`
+   * every `server*` option below goes with it, because there is no server
+   * for them to describe, and `clientEntry` goes too: the browser entry is
+   * whatever `index.html` loads. An app that wants its UI rendered in the
+   * browser while its routes still answer per request keeps `true` and
+   * writes a server entry that serves data and a shell.
+   *
+   * @default true
+   */
+  server?: boolean;
   /**
    * Server entry module, built as `dist/ssr/index.js`. Must default-export
    * a fetch handler: an object exposing
@@ -31,6 +46,8 @@ interface RemixPluginOptions {
    * Set to `false` when another plugin owns dev-time request handling —
    * e.g. `@cloudflare/vite-plugin`, `@netlify/vite-plugin`, or `nitro/vite`.
    *
+   * Ignored when `server` is `false`, which has no fetch handler.
+   *
    * @default true
    */
   serverHandler?: boolean;

package/dist/index.mjs

@@ -649,7 +649,8 @@ function findClientEntryCalls(program) {
 * Deno.
 */
 function remix(options = {}) {
-	let { clientEntry = "app/entry.browser", serverEntry = "app/entry.server", serverEnvironments = ["ssr"], serverHandler = true } = options;
+	let { clientEntry = "app/entry.browser", server = true, serverEntry = "app/entry.server", serverEnvironments = ["ssr"], serverHandler = true } = options;
+	if (!server) return spa();
 	let serverEnvironmentSet = new Set(serverEnvironments);
 	return [
 		fullstack({
@@ -672,6 +673,24 @@ function remix(options = {}) {
 	];
 }
 /**
+* SPA mode: the subset of `remix()` that applies when there is no server.
+* Vite already serves `index.html` and builds it to a static site, so the only
+* thing left to wire is component hot module replacement — which a
+* client-rendered app wants just as much as a server-rendered one.
+*
+* Everything server-shaped is absent by construction: no server environment,
+* no `dist/ssr`, no dev fetch handler, and no server-data HMR (there is no
+* server data to revalidate, so `<HMR />` resolves to the inert component).
+*/
+function spa() {
+	let serverEnvironmentSet = /* @__PURE__ */ new Set();
+	return [
+		componentHmr(serverEnvironmentSet),
+		hmrComponent(false),
+		clientEntryTransform(serverEnvironmentSet)
+	];
+}
+/**
 * Suppresses `aborted` errors from client disconnects (e.g. search-as-you-type
 * or navigating away mid-fetch) that would otherwise trigger Vite's dev error
 * overlay. The match is deliberately narrow so real failures still propagate.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pitlane/dev",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "remix() — the Remix 3 Vite plugin: build orchestration, clientEntry() hydration transform, dev server with component and server-data HMR, and preview for any Vite or Vite+ project.",
     "keywords": [
         "pitlane",