evolit 0.2.1 → 0.3.0

package/README.md

@@ -46,6 +46,26 @@ Generated applications declare `"@/*": ["./*"]` in `jsconfig.json`, so editors a
 use the same convention. An explicit `@/*` mapping in `jsconfig.json` or `tsconfig.json` takes
 priority when an application needs a different source root.
 
+### Interpolated dynamic imports
+
+Relative dynamic imports may use a template literal when every possible module can be discovered
+from the literal path at build time:
+
+```tsx
+const module = await import(`./templates/${locale}/${name}.tsx`);
+```
+
+Evolit treats each interpolation as one wildcard that matches a single path segment. The example
+above discovers `./templates/*/*.tsx`, compiles every matching module, and emits a finite runtime
+dispatcher whose cases preserve the original source specifiers. Interpolations never cross a `/`,
+and there is no framework-imposed candidate limit.
+
+The template must be relative, end in a supported authored module extension, and match at least one
+module during compilation. A runtime value that was not among the discovered candidates rejects the
+import. Development watches the matched directory tree, so adding a new candidate invalidates the
+affected graph. Arbitrary computed specifiers that do not use this template-literal form remain
+outside the statically discoverable graph.
+
 ### Package CSS and static assets
 
 Applications can import stylesheets exposed through package `exports` in the same way as local
@@ -301,6 +321,32 @@ server components and helpers that do not receive route props directly. It retur
 Reading `getRouteState().url` has the same dynamic-rendering semantics as `requestUrl()`; reading
 `params` and `searchParams` participates in the normal segment-cache key tracking.
 
+## Server Setup
+
+Server integrations that need one-time application setup can be registered with
+`server.setup`. A module specifier is compiled as part of the server graph, so the
+setup may be authored in JavaScript or TypeScript:
+
+```js
+// evolit.config.js
+export default {
+  server: {
+    setup: "./src/server/setup.ts",
+  },
+};
+```
+
+The module exports `setup` (or a default function). Evolit invokes it once per
+runtime and once before build-time prerendering with `{ projectRoot, mode }`.
+It may return a cleanup function or `{ dispose() }`; runtime cleanup runs from
+`runtime.close()`.
+
+When `@litsx/urql` is installed, Evolit opens its SSR resource around the whole
+route render and supplies `{ request, responseHeaders }`. Request-derived URQL
+configuration therefore stays isolated per render, extracted SSR data is read
+before the scope closes, and integration response headers are included before
+the response is cached.
+
 ## Extensions
 
 Optional integrations are configured explicitly in `evolit.config.js`. Core only coordinates their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -71,7 +71,7 @@
     "ws": "^8.18.3"
   },
   "peerDependencies": {
-    "@litsx/urql": "^0.3.0"
+    "@litsx/urql": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@litsx/urql": {

package/src/build.js

@@ -51,7 +51,13 @@ import {
 import { serializeRouteCachePolicy } from "./route-config.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { ensureDirectory, writeJson } from "./fs-utils.js";
-import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
+import {
+  appendSsrUrqlData,
+  applySsrUrqlRequestContext,
+  createSsrUrqlRequestContext,
+  runWithOptionalSsrUrqlScope,
+} from "./urql-ssr.js";
+import { runServerSetup } from "./server-setup.js";
 
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
@@ -157,6 +163,11 @@ async function writeDeploymentRuntimeEntry(buildRoot) {
 
 export async function buildProject(projectRoot, options = {}) {
   const evolitConfig = await loadEvolitConfig(projectRoot);
+  const serverSetupCleanup = await runServerSetup({
+    projectRoot,
+    mode: "production",
+    evolitConfig,
+  });
   const extensions = resolveEvolitExtensions(evolitConfig);
   const extensionClientDescriptors = getExtensionClientDescriptors(extensions);
   const packageClientSpecifiers = new Set(
@@ -541,23 +552,32 @@ export async function buildProject(projectRoot, options = {}) {
       seenPrerenderTargets.add(targetPathname);
 
       const targetRequest = new Request(`http://evolit.local${targetPathname}`);
-      const { routeResult, response } = await runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+      const urqlRequestContext = createSsrUrqlRequestContext(targetRequest);
+      const { routeResult, response } = await runWithOptionalSsrUrqlScope(urqlRequestContext, async (urqlAdapter) => {
         const resolvedRouteResult = await routeResolver.resolveRequest(targetRequest);
         if (resolvedRouteResult.type !== "route" || resolvedRouteResult.cachePolicy.mode === "dynamic") {
           return { routeResult: resolvedRouteResult, response: null };
         }
 
         const renderedResponse = await renderRouteTreeWithAdapter(resolvedRouteResult, ssrAdapter);
+        const responseWithData = urqlAdapter
+          ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
+          : renderedResponse;
         return {
           routeResult: resolvedRouteResult,
-          response: urqlAdapter
-            ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
-            : renderedResponse,
+          response: applySsrUrqlRequestContext(
+            resolvedRouteResult,
+            responseWithData,
+            urqlRequestContext,
+          ),
         };
       });
       if (!response) {
         continue;
       }
+      if (routeResult.cachePolicy.mode === "dynamic") {
+        continue;
+      }
       if (response.status !== 200) {
         continue;
       }
@@ -656,5 +676,7 @@ export async function buildProject(projectRoot, options = {}) {
   await writeJson(path.join(buildRoot, DEPLOY_ASSETS_MANIFEST_FILENAME), deployAssets);
   await writeJson(path.join(buildRoot, DEPLOY_SERVER_MANIFEST_FILENAME), deployServer);
 
+  await serverSetupCleanup?.();
+
   return manifestPath;
 }

package/src/compiler.js

@@ -20,6 +20,7 @@ import { ensureDirectory } from "./fs-utils.js";
 const MODULE_SPECIFIER_PATTERN =
   /\b(?:import|export)\s+(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
 const CSS_DEPENDENCY_PATTERN = /(?:@import\s+(?:url\(\s*)?["']([^"']+)["']\s*\)?|url\(\s*["']?([^"')]+)["']?\s*\))/g;
+const DYNAMIC_IMPORT_WILDCARD = "\u0000EVOLIT_DYNAMIC_IMPORT_WILDCARD\u0000";
 const RESOLVABLE_IMPORT_EXTENSIONS = [
   ...MODULE_EXTENSIONS,
   ...STATIC_ASSET_EXTENSIONS,
@@ -388,17 +389,30 @@ function getCompiledServerComponentExports(code, sourcePath) {
   return exports;
 }
 
-function collectImportedNamesBySpecifier(code, sourcePath) {
-  const sourceFile = ts.createSourceFile(sourcePath, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+function analyzeModuleReferences(code, sourcePath, scriptKind = ts.ScriptKind.JS) {
+  const sourceFile = ts.createSourceFile(sourcePath, code, ts.ScriptTarget.Latest, true, scriptKind);
   const bySpecifier = new Map();
+  const staticReferences = [];
+  const dynamicReferences = [];
   const add = (specifier, name) => {
     const names = bySpecifier.get(specifier) ?? new Set();
     names.add(name);
     bySpecifier.set(specifier, names);
   };
+  const addStaticReference = (node, importedName = null) => {
+    const specifier = node.text;
+    staticReferences.push({
+      specifier,
+      start: node.getStart(sourceFile) + 1,
+      end: node.end - 1,
+    });
+    if (importedName) add(specifier, importedName);
+  };
+
   for (const statement of sourceFile.statements) {
-    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteralLike(statement.moduleSpecifier)) {
       const specifier = statement.moduleSpecifier.text;
+      addStaticReference(statement.moduleSpecifier);
       if (statement.importClause?.name) add(specifier, "default");
       if (statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings)) {
         for (const element of statement.importClause.namedBindings.elements) {
@@ -408,9 +422,10 @@ function collectImportedNamesBySpecifier(code, sourcePath) {
     } else if (
       ts.isExportDeclaration(statement)
       && statement.moduleSpecifier
-      && ts.isStringLiteral(statement.moduleSpecifier)
+      && ts.isStringLiteralLike(statement.moduleSpecifier)
     ) {
       const specifier = statement.moduleSpecifier.text;
+      addStaticReference(statement.moduleSpecifier);
       if (!statement.exportClause) add(specifier, "*");
       else if (ts.isNamedExports(statement.exportClause)) {
         for (const element of statement.exportClause.elements) add(specifier, element.propertyName?.text ?? element.name.text);
@@ -421,13 +436,119 @@ function collectImportedNamesBySpecifier(code, sourcePath) {
     if (
       ts.isCallExpression(node)
       && node.expression.kind === ts.SyntaxKind.ImportKeyword
-      && node.arguments.length === 1
-      && ts.isStringLiteral(node.arguments[0])
-    ) add(node.arguments[0].text, "*");
+      && node.arguments.length >= 1
+    ) {
+      const argument = node.arguments[0];
+      if (ts.isStringLiteralLike(argument)) {
+        addStaticReference(argument, "*");
+      } else if (ts.isTemplateExpression(argument)) {
+        const staticParts = [
+          argument.head.text,
+          ...argument.templateSpans.map((span) => span.literal.text),
+        ];
+        dynamicReferences.push({
+          pattern: staticParts.join(DYNAMIC_IMPORT_WILDCARD),
+          displayPattern: staticParts.join("*"),
+          expressionText: code.slice(argument.getStart(sourceFile), argument.end),
+          optionsText: node.arguments.length > 1
+            ? code.slice(node.arguments[1].getStart(sourceFile), node.arguments.at(-1).end)
+            : null,
+          start: node.getStart(sourceFile),
+          end: node.end,
+        });
+      }
+    }
     ts.forEachChild(node, visit);
   };
   visit(sourceFile);
-  return bySpecifier;
+
+  return {
+    importedNamesBySpecifier: bySpecifier,
+    staticReferences,
+    dynamicReferences,
+  };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function createDynamicImportSegmentPattern(segment) {
+  return new RegExp(
+    `^${segment.split(DYNAMIC_IMPORT_WILDCARD).map(escapeRegExp).join("[^/]+")}$`,
+  );
+}
+
+async function discoverDynamicImportCandidates({
+  projectRoot,
+  sourcePath,
+  pattern,
+  displayPattern,
+  managedSourceRoots,
+}) {
+  const normalizedPattern = pattern.replaceAll("\\", "/");
+  if (!isRelativeSpecifier(normalizedPattern)) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} must be relative.`,
+    );
+  }
+  if (!MODULE_EXTENSIONS.some((extension) => normalizedPattern.endsWith(extension))) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} must end in a supported module extension.`,
+    );
+  }
+
+  const segments = normalizedPattern.split("/");
+  const firstDynamicSegment = segments.findIndex((segment) => segment.includes(DYNAMIC_IMPORT_WILDCARD));
+  if (firstDynamicSegment < 0) return { candidates: [], watchedDirectories: [] };
+
+  const scanRoot = path.resolve(path.dirname(sourcePath), ...segments.slice(0, firstDynamicSegment));
+  if (isPathOutsideManagedRoots(projectRoot, managedSourceRoots, scanRoot)) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} resolves outside the managed source roots.`,
+    );
+  }
+
+  const segmentPatterns = segments
+    .slice(firstDynamicSegment)
+    .map(createDynamicImportSegmentPattern);
+  const candidates = [];
+  const watchedDirectories = new Set();
+
+  async function visitDirectory(directory, segmentIndex) {
+    watchedDirectories.add(directory);
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return;
+      throw error;
+    }
+
+    const matcher = segmentPatterns[segmentIndex];
+    const isFinalSegment = segmentIndex === segmentPatterns.length - 1;
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      if (!matcher.test(entry.name)) continue;
+      const candidatePath = path.join(directory, entry.name);
+      if (isFinalSegment) {
+        if (entry.isFile()) candidates.push(candidatePath);
+      } else if (entry.isDirectory()) {
+        await visitDirectory(candidatePath, segmentIndex + 1);
+      }
+    }
+  }
+
+  await visitDirectory(scanRoot, 0);
+  if (candidates.length === 0) {
+    throw new Error(
+      `Dynamic import pattern ${JSON.stringify(displayPattern)} in ${sourcePath} did not match any modules.`,
+    );
+  }
+
+  return {
+    candidates,
+    watchedDirectories: [...watchedDirectories],
+  };
 }
 
 function createClientServerComponentImportError(entryPath, sourcePath, parents) {
@@ -841,18 +962,17 @@ async function rewriteRelativeSpecifiers({
   managedSourceRoots,
   serverExportsByModule,
   packageImports,
+  dynamicImportDirectories,
 }) {
   const magicSource = new MagicString(code);
   let didRewrite = false;
+  const moduleReferences = analyzeModuleReferences(code, sourcePath);
   const importedNamesBySpecifier = target === "client"
-    ? collectImportedNamesBySpecifier(code, sourcePath)
+    ? moduleReferences.importedNamesBySpecifier
     : new Map();
 
-  for (const match of code.matchAll(MODULE_SPECIFIER_PATTERN)) {
-    const specifier = match[1] ?? match[2] ?? null;
-    if (!specifier) {
-      continue;
-    }
+  for (const reference of moduleReferences.staticReferences) {
+    const { specifier } = reference;
 
     const aliasedImportPath = isBareSpecifier(specifier)
       ? await resolveProjectMappedImport(projectRoot, sourcePath, specifier)
@@ -996,18 +1116,99 @@ async function rewriteRelativeSpecifiers({
     ) {
       normalizedReplacement = `${normalizedReplacement}?${serverImportQuery}`;
     }
-    const quotedSpecifierIndex = match.index + match[0].indexOf(specifier);
     const replacementValue = normalizedReplacement.split(path.sep).join("/");
     if (replacementValue !== specifier) {
       didRewrite = true;
       magicSource.update(
-        quotedSpecifierIndex,
-        quotedSpecifierIndex + specifier.length,
+        reference.start,
+        reference.end,
         replacementValue,
       );
     }
   }
 
+  const dynamicImportHelpers = [];
+  for (const [index, reference] of moduleReferences.dynamicReferences.entries()) {
+    const discovery = await discoverDynamicImportCandidates({
+      projectRoot,
+      sourcePath,
+      pattern: reference.pattern,
+      displayPattern: reference.displayPattern,
+      managedSourceRoots,
+    });
+    discovery.watchedDirectories.forEach((directory) => dynamicImportDirectories.add(directory));
+
+    const cases = [];
+    for (const resolvedImportPath of discovery.candidates) {
+      const compiledImportPath = await compileModule(resolvedImportPath);
+      const serverExports = serverExportsByModule?.get(resolvedImportPath) ?? new Set();
+      if (target === "client" && serverExports.size > 0) {
+        throw new Error(
+          `Client module ${sourcePath} dynamically imports Server Component export(s) from ${resolvedImportPath}: `
+          + `${[...serverExports].join(", ")}. Split the server exports into a separate module.`,
+        );
+      }
+
+      const importerOutputPath = toOutputPath(projectRoot, outputRoot, sourcePath);
+      let replacementPath = path.relative(path.dirname(importerOutputPath), compiledImportPath);
+      if (!replacementPath.startsWith(".")) replacementPath = `./${replacementPath}`;
+      replacementPath = replacementPath.split(path.sep).join("/");
+      if (
+        target === "server"
+        && mode === "development"
+        && typeof serverImportQuery === "string"
+        && serverImportQuery.length > 0
+      ) {
+        replacementPath = `${replacementPath}?${serverImportQuery}`;
+      }
+
+      let sourceSpecifier = path.relative(path.dirname(sourcePath), resolvedImportPath)
+        .split(path.sep)
+        .join("/");
+      if (!sourceSpecifier.startsWith(".")) sourceSpecifier = `./${sourceSpecifier}`;
+      cases.push(
+        `    case ${JSON.stringify(sourceSpecifier)}: return import(${JSON.stringify(replacementPath)}${reference.optionsText ? ", options" : ""});`,
+      );
+
+      if (target === "client") {
+        const sourceMetadata = moduleMetadata.get(sourcePath) ?? {
+          moduleImports: new Set(),
+          vendorImports: new Set(),
+          styleImports: new Set(),
+          assetImports: new Set(),
+        };
+        sourceMetadata.moduleImports.add(
+          path.relative(outputRoot, compiledImportPath).split(path.sep).join("/"),
+        );
+        moduleMetadata.set(sourcePath, sourceMetadata);
+      }
+    }
+
+    let helperName = `__evolit_dynamic_import_${index}`;
+    while (code.includes(helperName)) helperName = `_${helperName}`;
+    const sourceModuleId = path.relative(projectRoot, sourcePath).split(path.sep).join("/");
+    const unknownImportPrefix = `Unknown dynamic import in ${sourceModuleId}: `;
+    dynamicImportHelpers.push([
+      `function ${helperName}(specifier${reference.optionsText ? ", options" : ""}) {`,
+      "  switch (specifier) {",
+      ...cases,
+      "    default:",
+      `      return Promise.reject(new Error(${JSON.stringify(unknownImportPrefix)} + specifier));`,
+      "  }",
+      "}",
+    ].join("\n"));
+    magicSource.update(
+      reference.start,
+      reference.end,
+      `${helperName}(${reference.expressionText}${reference.optionsText ? `, ${reference.optionsText}` : ""})`,
+    );
+    didRewrite = true;
+  }
+
+  if (dynamicImportHelpers.length > 0) {
+    magicSource.append(`\n\n${dynamicImportHelpers.join("\n\n")}\n`);
+  }
+
   const rewrittenCode = magicSource.toString();
   if (!sourceMaps || !didRewrite) {
     return {
@@ -1131,7 +1332,10 @@ export function invalidateDevelopmentCompilationCache(projectRoot, changedPaths
     const shouldInvalidate =
       normalizedChangedPaths == null ||
       !dependencies ||
-      [...dependencies].some((dependency) => normalizedChangedPaths.has(dependency));
+      [...dependencies.files].some((dependency) => normalizedChangedPaths.has(dependency)) ||
+      [...dependencies.directories].some((directory) =>
+        [...normalizedChangedPaths].some((changedPath) => !isPathOutsideProject(directory, changedPath))
+      );
     if (shouldInvalidate) {
       developmentGraphCache.delete(key);
       developmentGraphDependencies.delete(key);
@@ -1163,6 +1367,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
   const moduleMetadata = new Map();
   const serverExportsByModule = new Map();
   const packageImports = new Set();
+  const dynamicImportDirectories = new Set();
   const serverImportQuery = target === "server" && mode === "development"
     ? `t=${Date.now()}`
     : null;
@@ -1233,6 +1438,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
       managedSourceRoots,
       serverExportsByModule,
       packageImports,
+      dynamicImportDirectories,
     });
 
     await fs.writeFile(outputPath, rewritten.code, "utf8");
@@ -1262,6 +1468,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
     entrypoint: await compileModule(entryPath),
     outputRoot,
     sourceFiles: [...new Set([...visited.keys(), ...staticAssetFiles])],
+    watchedDirectories: [...dynamicImportDirectories],
     packageImports: [...packageImports].sort(),
   };
 }
@@ -1286,7 +1493,10 @@ export async function compileModuleGraph(entryPath, options = {}) {
     developmentGraphCache.set(cacheKey, pendingCompile);
     pendingCompile.then((result) => {
       if (developmentGraphCache.get(cacheKey) === pendingCompile) {
-        developmentGraphDependencies.set(cacheKey, new Set(result.sourceFiles));
+        developmentGraphDependencies.set(cacheKey, {
+          files: new Set(result.sourceFiles),
+          directories: new Set(result.watchedDirectories ?? []),
+        });
       }
     }, () => {});
   }
@@ -1425,15 +1635,15 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
     if (isComponent && isServer) boundaries.add(sourcePath);
     if (!traverseNonBoundary) return;
     const componentImportSpecifiers = collectComponentImportSpecifiers(source, sourcePath);
-    for (const match of source.matchAll(MODULE_SPECIFIER_PATTERN)) {
-      const specifier = match[1] ?? match[2];
-      if (!specifier) continue;
+    const moduleReferences = analyzeModuleReferences(source, sourcePath, ts.ScriptKind.TSX);
+
+    async function visitResolvedSpecifier(specifier) {
       const aliasResolved = isBareSpecifier(specifier)
         ? await resolveProjectMappedImport(projectRoot, sourcePath, specifier)
         : null;
       const resolved = aliasResolved
         ?? await resolveProjectModuleSpecifier(projectRoot, sourcePath, specifier);
-      if (!resolved) continue;
+      if (!resolved) return;
       if (shouldCompileModule(resolved)) {
         if (isBareSpecifier(specifier) && aliasResolved == null) {
           if (componentImportSpecifiers.has(specifier)) {
@@ -1450,6 +1660,21 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
         assets.add(resolved);
       }
     }
+
+    for (const reference of moduleReferences.staticReferences) {
+      await visitResolvedSpecifier(reference.specifier);
+    }
+    for (const reference of moduleReferences.dynamicReferences) {
+      const discovery = await discoverDynamicImportCandidates({
+        projectRoot,
+        sourcePath,
+        pattern: reference.pattern,
+        displayPattern: reference.displayPattern,
+      });
+      for (const candidate of discovery.candidates) {
+        await visit(candidate, true);
+      }
+    }
   }
 
   for (const entryPath of entryPaths) await visit(entryPath);

package/src/deployment-runtime.js

@@ -41,12 +41,18 @@ import {
 } from "./response-cache.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { createNavigationResponseFromDocument } from "./route-segments.js";
-import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
+import {
+  appendSsrUrqlData,
+  applySsrUrqlRequestContext,
+  createSsrUrqlRequestContext,
+  runWithOptionalSsrUrqlScope,
+} from "./urql-ssr.js";
 import {
   getExtensionClientDescriptors,
   resolveEvolitExtensions,
   runRequestExtensions,
 } from "./extensions.js";
+import { runServerSetup } from "./server-setup.js";
 
 function isBarePackageModuleId(value) {
   return typeof value === "string"
@@ -882,7 +888,8 @@ export async function createRequestRenderer({
       return effectiveRouteResolver.resolveRoutePolicy(request, options);
     },
     async renderRoute(request, routePolicyResult = null, options = {}) {
-      return runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+      const urqlRequestContext = createSsrUrqlRequestContext(request);
+      return runWithOptionalSsrUrqlScope(urqlRequestContext, async (urqlAdapter) => {
         const shouldPrepareBeforeResolve = mode === "development" && !currentAssetManifest;
         let resolvedRoutePolicyResult = routePolicyResult;
         if (shouldPrepareBeforeResolve) {
@@ -895,9 +902,14 @@ export async function createRequestRenderer({
           await this.prepareRouteClientArtifacts(routeResult);
         }
         const renderedResponse = await renderRouteTreeWithAdapter(routeResult, ssrAdapter);
-        const response = urqlAdapter
+        const responseWithData = urqlAdapter
           ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
           : renderedResponse;
+        const response = applySsrUrqlRequestContext(
+          routeResult,
+          responseWithData,
+          urqlRequestContext,
+        );
         return {
           routeResult,
           response,
@@ -921,8 +933,10 @@ export async function createDeploymentRuntime({
   routeResolver,
   onDevelopmentEvent,
   managedSourceRoots,
+  evolitConfig: configuredEvolitConfig,
 } = {}) {
-  const evolitConfig = await loadEvolitConfig(projectRoot);
+  const evolitConfig = configuredEvolitConfig ?? await loadEvolitConfig(projectRoot);
+  const serverSetupCleanup = await runServerSetup({ projectRoot, mode, evolitConfig });
   const extensions = resolveEvolitExtensions(evolitConfig);
   const extensionClientSpecifiers = getExtensionClientDescriptors(extensions).map((descriptor) => descriptor.module);
   const effectiveManagedSourceRoots = managedSourceRoots
@@ -1072,6 +1086,7 @@ export async function createDeploymentRuntime({
       if (revalidationTasks) {
         await Promise.all(revalidationTasks.values());
       }
+      await serverSetupCleanup?.();
     },
   };
 }

package/src/server-setup.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { importCompiledModule, resolveProjectModuleSpecifier } from "./compiler.js";
+
+function resolveSetupExport(moduleRecord, setupPath) {
+  const setup = moduleRecord.setup ?? moduleRecord.default;
+  if (typeof setup !== "function") {
+    throw new TypeError(
+      `Expected server setup module ${JSON.stringify(setupPath)} to export a setup function or a default function.`,
+    );
+  }
+  return setup;
+}
+
+function normalizeCleanup(result) {
+  if (result == null) return null;
+  if (typeof result === "function") return result;
+  if (typeof result === "object" && typeof result.dispose === "function") {
+    return () => result.dispose();
+  }
+  throw new TypeError("Evolit server setup must return nothing, a cleanup function, or an object with dispose().");
+}
+
+/** Runs the application server bootstrap once for a build or runtime instance. */
+export async function runServerSetup({ projectRoot, mode, evolitConfig = {} }) {
+  const serverConfig = evolitConfig.server;
+  if (serverConfig == null) return null;
+  if (!serverConfig || typeof serverConfig !== "object" || Array.isArray(serverConfig)) {
+    throw new TypeError("Expected server in evolit.config.js to be an object.");
+  }
+
+  const configuredSetup = serverConfig.setup;
+  if (configuredSetup == null) return null;
+
+  let setup = configuredSetup;
+  if (typeof configuredSetup === "string") {
+    if (configuredSetup.length === 0) {
+      throw new TypeError("Expected server.setup to be a non-empty module specifier.");
+    }
+    const setupPath = await resolveProjectModuleSpecifier(
+      projectRoot,
+      path.join(projectRoot, "evolit.config.js"),
+      configuredSetup,
+    );
+    if (!setupPath) {
+      throw new Error(`Unable to resolve configured server setup ${JSON.stringify(configuredSetup)}.`);
+    }
+    const moduleRecord = await importCompiledModule(setupPath, {
+      projectRoot,
+      mode,
+      sourceMaps: mode === "development",
+      target: "server",
+    });
+    setup = resolveSetupExport(moduleRecord, configuredSetup);
+  }
+
+  if (typeof setup !== "function") {
+    throw new TypeError("Expected server.setup in evolit.config.js to be a function or module specifier.");
+  }
+
+  return normalizeCleanup(await setup({
+    projectRoot,
+    mode,
+  }));
+}

package/src/server.js

@@ -214,6 +214,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
     responseCacheRuntime,
     onDevelopmentEvent: reportDevelopmentEvent,
     managedSourceRoots,
+    evolitConfig,
   });
   const port = getPort(explicitPort);
   const liveReloadServer = mode === "development" ? new WebSocketServer({ noServer: true }) : null;

package/src/urql-ssr.js

@@ -26,7 +26,18 @@ export async function getSsrUrqlAdapter() {
  * Evolit owns only lifecycle here; client creation and URQL configuration stay
  * entirely in the application and @litsx/urql.
  */
-export async function runWithOptionalSsrUrqlScope(callback, options = {}) {
+export async function runWithOptionalSsrUrqlScope(
+  contextOrCallback,
+  callbackOrOptions = {},
+  maybeOptions = {},
+) {
+  const hasRequestContext = typeof contextOrCallback !== "function";
+  const requestContext = hasRequestContext ? contextOrCallback : null;
+  const callback = hasRequestContext ? callbackOrOptions : contextOrCallback;
+  const options = hasRequestContext ? maybeOptions : callbackOrOptions;
+  if (typeof callback !== "function") {
+    throw new TypeError("runWithOptionalSsrUrqlScope() expects a render callback.");
+  }
   const adapter = Object.hasOwn(options, "adapter")
     ? options.adapter
     : await getSsrUrqlAdapter();
@@ -34,7 +45,61 @@ export async function runWithOptionalSsrUrqlScope(callback, options = {}) {
     return callback(null);
   }
 
-  return adapter.runWithUrqlScope(() => callback(adapter));
+  return hasRequestContext
+    ? adapter.runWithUrqlScope(requestContext, () => callback(adapter))
+    : adapter.runWithUrqlScope(() => callback(adapter));
+}
+
+/** Creates the HTTP context passed to a request-scoped URQL resource factory. */
+export function createSsrUrqlRequestContext(request) {
+  let didUseRequestData = false;
+  const trackedRequest = new Proxy(request, {
+    get(target, property) {
+      if (property !== "constructor" && property !== Symbol.toStringTag) {
+        didUseRequestData = true;
+      }
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  const responseHeaders = new Headers();
+  return {
+    request: trackedRequest,
+    responseHeaders,
+    didUseDynamicRequestData() {
+      return didUseRequestData || !responseHeaders.entries().next().done;
+    },
+  };
+}
+
+function responseHeadersToObject(headers) {
+  const values = Object.fromEntries(headers.entries());
+  if (typeof headers.getSetCookie === "function") {
+    const cookies = headers.getSetCookie();
+    if (cookies.length > 0) values["set-cookie"] = cookies;
+  }
+  return values;
+}
+
+/** Applies request-resource response state before Evolit caches the render. */
+export function applySsrUrqlRequestContext(routeResult, response, context) {
+  if (!context) return response;
+  const urqlHeaders = responseHeadersToObject(context.responseHeaders);
+  if (context.didUseDynamicRequestData()) {
+    routeResult.cachePolicy = { mode: "dynamic" };
+  }
+  if (Object.keys(urqlHeaders).length === 0) return response;
+  routeResult.responseHeaders = {
+    ...(routeResult.responseHeaders ?? {}),
+    ...urqlHeaders,
+  };
+  return {
+    ...response,
+    headers: {
+      ...(response.headers ?? {}),
+      ...urqlHeaders,
+    },
+  };
 }
 
 function escapeJsonForHtml(value) {