@convex-dev/static-hosting 0.1.2-beta.0

package/src/client/next.ts

@@ -0,0 +1,223 @@
+import { httpActionGeneric } from "convex/server";
+import type { FunctionReference, HttpRouter } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+// MIME type mapping for Next.js static assets
+const MIME_TYPES: Record<string, string> = {
+  ".js": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".map": "application/json",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+/**
+ * Register HTTP routes for serving a Next.js app via Convex HTTP actions.
+ *
+ * Static assets (`/_next/static/*`) are served directly from Convex storage
+ * (V8 runtime, instant). All other requests are forwarded to a Node.js action
+ * that runs NextServer.
+ *
+ * @param http - The HTTP router to register routes on
+ * @param component - The component API reference (for storage lookups)
+ * @param actionRef - Reference to the generated `handle` action
+ * @param options - Configuration options
+ * @param options.pathPrefix - URL prefix (default: "/")
+ *
+ * @example
+ * ```typescript
+ * // convex/http.ts
+ * import { httpRouter } from "convex/server";
+ * import { registerNextRoutes } from "@convex-dev/static-hosting/next";
+ * import { components, internal } from "./_generated/api";
+ *
+ * const http = httpRouter();
+ * registerNextRoutes(http, components.staticHosting, internal._generatedNextServer.handle);
+ * export default http;
+ * ```
+ */
+export function registerNextRoutes(
+  http: HttpRouter,
+  component: ComponentApi,
+  actionRef: FunctionReference<"action", "internal", Record<string, unknown>, unknown>,
+  {
+    pathPrefix = "/",
+    warmup = true,
+  }: {
+    pathPrefix?: string;
+    /** Inject a warmup script into static HTML pages to pre-boot the Node.js
+     *  NextServer in the background. Defaults to true. */
+    warmup?: boolean;
+  } = {},
+) {
+  const normalizedPrefix =
+    pathPrefix === "/" ? "" : pathPrefix.replace(/\/$/, "");
+
+  // Hop-by-hop headers that must not be forwarded through proxies
+  const hopByHopHeaders = new Set([
+    "transfer-encoding",
+    "connection",
+    "keep-alive",
+    "upgrade",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+  ]);
+
+  const handler = httpActionGeneric(async (ctx, request) => {
+    const url = new URL(request.url);
+    let path = url.pathname;
+
+    // Remove prefix if present
+    if (normalizedPrefix && path.startsWith(normalizedPrefix)) {
+      path = path.slice(normalizedPrefix.length) || "/";
+    }
+
+    // Warmup endpoint: boots the Node.js action in the background
+    if (warmup && path === "/__warmup") {
+      try {
+        await (ctx as { runAction: (ref: typeof actionRef, args: Record<string, unknown>) => Promise<unknown> }).runAction(actionRef, {
+          url: `${url.origin}/`,
+          method: "GET",
+          headers: [],
+        });
+      } catch {
+        // Warmup failure is non-critical
+      }
+      return new Response(null, { status: 204 });
+    }
+
+    // Serve /_next/static/* from Convex storage (fast, V8 runtime)
+    if (path.startsWith("/_next/static/")) {
+      type AssetDoc = {
+        storageId?: string;
+        contentType: string;
+      } | null;
+
+      const asset: AssetDoc = await ctx.runQuery(component.lib.getByPath, {
+        path,
+      });
+
+      if (asset?.storageId) {
+        const blob = await ctx.storage.get(asset.storageId);
+        if (blob) {
+          return new Response(blob, {
+            status: 200,
+            headers: {
+              "Content-Type": asset.contentType,
+              "Cache-Control": "public, max-age=31536000, immutable",
+              "X-Content-Type-Options": "nosniff",
+            },
+          });
+        }
+      }
+
+      // Fall through to Node action if not in storage
+    }
+
+    // Forward everything else to the Node.js action
+    try {
+      const method = request.method;
+      const headers: string[][] = [];
+      request.headers.forEach((value, key) => {
+        headers.push([key, value]);
+      });
+      const body =
+        !["GET", "HEAD"].includes(method)
+          ? await request.arrayBuffer()
+          : undefined;
+
+      const result = (await (ctx as { runAction: (ref: typeof actionRef, args: Record<string, unknown>) => Promise<unknown> }).runAction(actionRef, {
+        url: request.url,
+        method,
+        headers,
+        body: body ? body : undefined,
+      })) as {
+        status: number;
+        headers: string[][];
+        body: ArrayBuffer;
+      };
+
+      // Filter out hop-by-hop headers
+      const filteredHeaders = result.headers.filter(
+        ([key]) => !hopByHopHeaders.has(key.toLowerCase()),
+      );
+
+      let responseBody: ArrayBuffer | string | null =
+        result.body.byteLength > 0 ? result.body : null;
+
+      // Inject warmup script into HTML responses so subsequent pages
+      // don't need to wait for a cold start
+      if (warmup && responseBody) {
+        const contentType = filteredHeaders.find(
+          ([k]) => k.toLowerCase() === "content-type",
+        );
+        if (contentType && contentType[1].includes("text/html")) {
+          const html = new TextDecoder().decode(result.body);
+          const warmupUrl = normalizedPrefix
+            ? `${normalizedPrefix}/__warmup`
+            : "/__warmup";
+          const script = `<script>fetch("${warmupUrl}").catch(()=>{})</script>`;
+          responseBody = html.replace("</head>", `${script}</head>`);
+        }
+      }
+
+      return new Response(responseBody, {
+        status: result.status,
+        headers: filteredHeaders as [string, string][],
+      });
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Internal Server Error";
+      console.error("Next.js handler error:", error);
+      return new Response(message, {
+        status: 500,
+        headers: { "Content-Type": "text/plain" },
+      });
+    }
+  });
+
+  const methods = [
+    "GET",
+    "POST",
+    "PUT",
+    "DELETE",
+    "PATCH",
+    "OPTIONS",
+  ] as const;
+
+  for (const method of methods) {
+    http.route({
+      pathPrefix: pathPrefix === "/" ? "/" : `${normalizedPrefix}/`,
+      method,
+      handler,
+    });
+
+    if (normalizedPrefix) {
+      http.route({
+        path: normalizedPrefix,
+        method,
+        handler,
+      });
+    }
+  }
+}
+
+/**
+ * Get the MIME type for a file path.
+ */
+export function getNextMimeType(filePath: string): string {
+  const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
+  return MIME_TYPES[ext] || "application/octet-stream";
+}

package/src/client/nextAdapter.ts

@@ -0,0 +1,17 @@
+import { toReqRes, toFetchResponse } from "fetch-to-node";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export type NodeRequestHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<void>;
+
+export async function handleWithNodeHandler(
+  request: Request,
+  handler: NodeRequestHandler,
+): Promise<Response> {
+  const { req, res } = toReqRes(request);
+  await handler(req, res);
+  if (!res.writableEnded) res.end();
+  return await toFetchResponse(res);
+}

package/src/client/setup.test.ts

@@ -0,0 +1,26 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+import {
+  defineSchema,
+  type GenericSchema,
+  type SchemaDefinition,
+} from "convex/server";
+import { type ComponentApi } from "../component/_generated/component.js";
+import { componentsGeneric } from "convex/server";
+import { register } from "../test.js";
+
+export function initConvexTest<
+  Schema extends SchemaDefinition<GenericSchema, boolean>,
+>(schema?: Schema) {
+  const t = convexTest(schema ?? defineSchema({}), modules);
+  register(t);
+  return t;
+}
+export const components = componentsGeneric() as unknown as {
+  staticHosting: ComponentApi;
+};
+
+test("setup", () => {});

package/src/component/_generated/api.ts

@@ -0,0 +1,50 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  lib: typeof lib;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,104 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      gcOldAssets: FunctionReference<
+        "mutation",
+        "internal",
+        { currentDeploymentId: string },
+        { blobIds: Array<string>; storageIds: Array<string> },
+        Name
+      >;
+      generateUploadUrl: FunctionReference<
+        "mutation",
+        "internal",
+        {},
+        string,
+        Name
+      >;
+      getByPath: FunctionReference<
+        "query",
+        "internal",
+        { path: string },
+        {
+          _creationTime: number;
+          _id: string;
+          blobId?: string;
+          contentType: string;
+          deploymentId: string;
+          path: string;
+          storageId?: string;
+        } | null,
+        Name
+      >;
+      getCurrentDeployment: FunctionReference<
+        "query",
+        "internal",
+        {},
+        {
+          _creationTime: number;
+          _id: string;
+          currentDeploymentId: string;
+          deployedAt: number;
+        } | null,
+        Name
+      >;
+      listAssets: FunctionReference<
+        "query",
+        "internal",
+        { limit?: number },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          blobId?: string;
+          contentType: string;
+          deploymentId: string;
+          path: string;
+          storageId?: string;
+        }>,
+        Name
+      >;
+      recordAsset: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          blobId?: string;
+          contentType: string;
+          deploymentId: string;
+          path: string;
+          storageId?: string;
+        },
+        { oldBlobId: string | null; oldStorageId: string | null },
+        Name
+      >;
+      setCurrentDeployment: FunctionReference<
+        "mutation",
+        "internal",
+        { deploymentId: string },
+        null,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,161 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+
+export default defineComponent("staticHosting");