Merge pull request #4 from JoviDeCroock/feat/adapter-by-reference

feat: pass adapters by reference instead of string

Author: JoviDeCroock

.github/workflows/ci.yml

@@ -18,6 +18,8 @@ jobs:
 
       - name: Install pnpm
         uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+        with:
+          version: 10.28.1
 
       - name: Install Node.js
         uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
@@ -39,3 +41,9 @@ jobs:
 
       - name: Test
         run: pnpm test
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: E2E tests
+        run: pnpm e2e

docs/ADAPTERS.md

@@ -26,9 +26,21 @@ are served and how ISG revalidation state is tracked.
 
 ## Adapter Interface
 
-Each adapter exports two things:
+Each adapter exports three things:
 
-### 1. Request handler factory
+### 1. Adapter factory (for the Vite plugin)
+
+```typescript
+// Example: Node adapter
+import { nodeAdapter } from "@viact/adapter-node";
+
+viact({ adapter: nodeAdapter() });
+```
+
+The factory returns a `ViactAdapter` object that the Vite plugin uses to
+generate the server entry module.
+
+### 2. Request handler factory
 
 ```typescript
 // Example: Node adapter
@@ -37,14 +49,14 @@ export function createNodeRequestHandler<TContext>(
 ): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 ```
 
-### 2. Entry module generator (for the Vite plugin)
+### 3. Entry module generator (for custom adapters)
 
 ```typescript
 export function createNodeServerEntryModule(options?: NodeServerEntryModuleOptions): string;
 ```
 
-The Vite plugin calls the entry module generator to create a virtual module
-(`virtual:viact/node-server`) that bootstraps the server.
+The adapter factory calls the entry module generator internally to create a virtual module
+(`virtual:viact/server`) that bootstraps the server.
 
 ---
 
@@ -114,7 +126,7 @@ the executable production server entry.
 - **Default request context**: generated worker entries pass `{ env,
 executionContext }` to viact so loaders, actions, and middleware can access
   bindings without extra wiring.
-- **Build output**: `viact({ adapter: "cloudflare" })` makes `viact build`
+- **Build output**: `viact({ adapter: cloudflareAdapter() })` makes `viact build`
   emit a Worker bundle in `dist/server/server.js`. You own a `wrangler.jsonc`
   in your project root that points at the output — this lets you add KV, D1,
   R2, cron, and any other Cloudflare bindings without losing them on rebuild.
@@ -163,7 +175,7 @@ export default {
 
 - **Edge runtime handler**: generated server entries export a default `fetch`-style
   handler that Vercel bundles as an Edge Function.
-- **Build Output API v3**: `viact({ adapter: "vercel" })` makes `viact build`
+- **Build Output API v3**: `viact({ adapter: vercelAdapter() })` makes `viact build`
   emit `.vercel/output/config.json`, `.vercel/output/static/`, and
   `.vercel/output/functions/render.func/`.
 - **Clean URL routing**: prerendered SSG pages are copied into
@@ -202,19 +214,51 @@ export default async function handle(request, context) {
 
 ## Writing a Custom Adapter
 
-An adapter needs to:
+A custom adapter exports a factory function that returns a `ViactAdapter` object:
+
+```typescript
+import type { ViactAdapter } from "@viact/vite-plugin";
+
+export function myAdapter(options?: MyOptions): ViactAdapter {
+  return {
+    id: "my-platform",
+    serverImports: 'import { handleViactRequest, resolveApp, resolveApiRoutes } from "viact";',
+    createServerEntryModule() {
+      // Return JavaScript source code that will be appended to the
+      // generated virtual:viact/server module.
+      return `
+export default async function handle(request) {
+  return handleViactRequest({
+    app: resolvedApp,
+    registry,
+    request,
+    apiRoutes,
+    clientEntryUrl: clientEntryUrl ?? undefined,
+    cssManifest,
+    jsManifest,
+  });
+}
+`;
+    },
+  };
+}
+```
+
+The generated server entry module has access to `resolvedApp`, `registry`,
+`apiRoutes`, `clientEntryUrl`, `cssManifest`, and `jsManifest` -- your
+`createServerEntryModule()` code can reference these directly.
+
+At the runtime level, an adapter also typically needs to:
 
 1. **Accept a platform request** and convert it to a Web `Request` object
-2. **Check for static assets** — serve files from `dist/client/` with appropriate
+2. **Check for static assets** -- serve files from `dist/client/` with appropriate
    headers (content-type, cache-control with immutable for hashed assets)
-3. **Check for prerendered pages** — SSG and ISG routes have HTML files on disk.
+3. **Check for prerendered pages** -- SSG and ISG routes have HTML files on disk.
    For ISG, implement staleness checking.
-4. **Delegate dynamic requests** to `handleViactRequest()` from `@viact/framework`
+4. **Delegate dynamic requests** to `handleViactRequest()` from `viact`
 5. **Convert the Web `Response`** back to the platform's response format
-6. **Provide a context factory** — create app-level context from platform-specific
+6. **Provide a context factory** -- create app-level context from platform-specific
    inputs (env bindings, headers, etc.)
-7. **Export an entry module generator** — a function that returns JavaScript source
-   code for the Vite plugin to use as a virtual module
 
 ### Context factory pattern
 

examples/basic/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "dependencies": {
     "@viact/adapter-node": "workspace:*",
+    "@viact/adapter-vercel": "workspace:*",
     "viact": "workspace:*"
   },
   "devDependencies": {

examples/basic/vite.config.ts

@@ -1,15 +1,21 @@
 import { defineConfig } from "vite";
 import { viact } from "@viact/vite-plugin";
 
-export default defineConfig({
-  plugins: [
-    viact({
-      adapter:
-        process.env.VIACT_ADAPTER === "vercel"
-          ? "vercel"
-          : process.env.VIACT_ADAPTER === "node"
-            ? "node"
-            : "cloudflare",
-    }),
-  ],
-});
+async function resolveAdapter() {
+  if (process.env.VIACT_ADAPTER === "vercel") {
+    const { vercelAdapter } = await import("@viact/adapter-vercel");
+    return vercelAdapter();
+  }
+
+  if (process.env.VIACT_ADAPTER === "node") {
+    const { nodeAdapter } = await import("@viact/adapter-node");
+    return nodeAdapter();
+  }
+
+  const { cloudflareAdapter } = await import("@viact/adapter-cloudflare");
+  return cloudflareAdapter();
+}
+
+export default defineConfig(async () => ({
+  plugins: [viact({ adapter: await resolveAdapter() })],
+}));

examples/cloudflare/vite.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from "vite";
 import { viact } from "@viact/vite-plugin";
+import { cloudflareAdapter } from "@viact/adapter-cloudflare";
 
 export default defineConfig({
-  plugins: [viact({ adapter: "cloudflare" })],
+  plugins: [viact({ adapter: cloudflareAdapter() })],
 });

examples/docs/src/routes/docs/adapters.md

@@ -34,9 +34,10 @@ Deploy to Cloudflare's global edge network. Static assets are served from the `A
 ```ts [vite.config.ts]
 import { defineConfig } from "vite";
 import { viact } from "@viact/vite-plugin";
+import { cloudflareAdapter } from "@viact/adapter-cloudflare";
 
 export default defineConfig({
-  plugins: [viact({ adapter: "cloudflare" })],
+  plugins: [viact({ adapter: cloudflareAdapter() })],
 });
 ```
 
@@ -96,7 +97,8 @@ Deploy using Vercel's Build Output API v3. SSG pages are served from the static
 
 ```ts
 // vite.config.ts
-viact({ adapter: "vercel" })
+import { vercelAdapter } from "@viact/adapter-vercel";
+viact({ adapter: vercelAdapter() })
 
 // package.json
 "@viact/adapter-vercel": "*"
@@ -130,7 +132,8 @@ Run viact as a standard Node.js HTTP server. The adapter handles static file ser
 
 ```ts
 // vite.config.ts
-viact({ adapter: "node" })
+import { nodeAdapter } from "@viact/adapter-node";
+viact({ adapter: nodeAdapter() })
 
 // package.json
 "@viact/adapter-node": "*"
@@ -172,11 +175,39 @@ The context object is available as `args.context` in every loader, action, middl
 
 ## Writing a Custom Adapter
 
-A custom adapter needs to:
+A custom adapter exports a factory function that returns a `ViactAdapter` object:
+
+```ts
+import type { ViactAdapter } from "@viact/vite-plugin";
+
+export function myAdapter(): ViactAdapter {
+  return {
+    id: "my-platform",
+    serverImports: 'import { handleViactRequest, resolveApp, resolveApiRoutes } from "viact";',
+    createServerEntryModule() {
+      return `
+export default async function handle(request) {
+  return handleViactRequest({
+    app: resolvedApp,
+    registry,
+    request,
+    apiRoutes,
+    clientEntryUrl: clientEntryUrl ?? undefined,
+    cssManifest,
+    jsManifest,
+  });
+}
+`;
+    },
+  };
+}
+```
+
+At the runtime level, an adapter also typically needs to:
 
 1. Accept a platform request and convert it to a Web `Request`
-2. Check for static assets — serve files from `dist/client/` with appropriate headers
-3. Check for prerendered pages — serve SSG/ISG HTML (with staleness checking for ISG)
+2. Check for static assets -- serve files from `dist/client/` with appropriate headers
+3. Check for prerendered pages -- serve SSG/ISG HTML (with staleness checking for ISG)
 4. Delegate dynamic requests to `handleViactRequest()` from `viact`
 5. Convert the Web `Response` back to the platform's response format
 6. Provide a context factory for platform-specific values