feat(@netlify/remix-edge-adapter): support Hydrogen Vite sites (#441)

This adds support for Shopify Hydrogen sites that use Remix Vite. See https://github.com/netlify/hydrogen-template.

Author: serhalp

.github/workflows/test.yml

@@ -21,6 +21,11 @@ jobs:
           node-version: 18
           check-latest: true
       - run: corepack enable
+      - name: Install Deno
+        uses: denoland/setup-deno@v1
+        with:
+          # Should satisfy the `DENO_VERSION_RANGE` from https://github.com/netlify/edge-bundler/blob/main/node/bridge.ts#L17
+          deno-version: v1
       - name: Install
         run: pnpm install
       - name: Build

.gitignore

@@ -139,3 +139,6 @@ build/
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+
+# Generated by `deno types`
+/packages/remix-edge-adapter/deno.d.ts

README.md

@@ -14,6 +14,11 @@ are three packages:
 - `@netlify/remix-edge-adapter` - The Remix adapter for Netlify Edge Functions
 - `@netlify/remix-runtime` - The Remix runtime for Netlify Edge Functions
 
+## Hydrogen
+
+Shopify Hydrogen sites are supported and automatically detected. However, only
+[the edge adapter](./packages/remix-edge-adapter/README.md) is supported, and only when using Remix Vite.
+
 ## Development
 
 ### Installation

packages/remix-adapter/README.md

@@ -6,3 +6,6 @@ The Remix Adapter for Netlify allows you to deploy your [Remix](https://remix.ru
 It is strongly advised to use [the Netlify Remix template](https://github.com/netlify/remix-template) to create a Remix
 site for deployment to Netlify. See [Remix on Netlify](https://docs.netlify.com/frameworks/remix/) for more details and
 other options.
+
+Please note that this adapter **does not support Hydrogen**. Hydrogen is only supported via Edge Functions. See
+<https://github.com/netlify/hydrogen-template>.

packages/remix-adapter/src/vite/plugin.ts

@@ -4,23 +4,35 @@ import { join, relative, sep } from 'node:path'
 import { sep as posixSep } from 'node:path/posix'
 import { version, name } from '../../package.json'
 
-const SERVER_ID = 'virtual:netlify-server'
-const RESOLVED_SERVER_ID = `\0${SERVER_ID}`
+const NETLIFY_FUNCTIONS_DIR = '.netlify/functions-internal'
+
+const FUNCTION_FILENAME = 'remix-server.mjs'
+/**
+ * The chunk filename without an extension, i.e. in the Rollup config `input` format
+ */
+const FUNCTION_HANDLER_CHUNK = 'server'
+
+const FUNCTION_HANDLER_MODULE_ID = 'virtual:netlify-server'
+const RESOLVED_FUNCTION_HANDLER_MODULE_ID = `\0${FUNCTION_HANDLER_MODULE_ID}`
 
 const toPosixPath = (path: string) => path.split(sep).join(posixSep)
 
-// The virtual module that is the compiled server entrypoint.
-const serverCode = /* js */ `
+// The virtual module that is the compiled Vite SSR entrypoint (a Netlify Function handler)
+const FUNCTION_HANDLER = /* js */ `
 import { createRequestHandler } from "@netlify/remix-adapter";
 import * as build from "virtual:remix/server-build";
-export default createRequestHandler({ build });
+export default createRequestHandler({
+  build,
+  getLoadContext: async (_req, ctx) => ctx,
+});
 `
 
 // This is written to the functions directory. It just re-exports
 // the compiled entrypoint, along with Netlify function config.
-function generateNetlifyFunction(server: string) {
+function generateNetlifyFunction(handlerPath: string) {
   return /* js */ `
-    export { default } from "${server}";
+    export { default } from "${handlerPath}";
+
     export const config = {
       name: "Remix server handler",
       generator: "${name}@${version}",
@@ -41,12 +53,18 @@ export function netlifyPlugin(): Plugin {
       isSsr = isSsrBuild
       if (command === 'build') {
         if (isSsrBuild) {
-          // We need to add an extra entrypoint, as we need to compile
+          // We need to add an extra SSR entrypoint, as we need to compile
           // the server entrypoint too. This is because it uses virtual
           // modules.
+          // NOTE: the below is making various assumptions about the Remix Vite plugin's
+          // implementation details:
+          // https://github.com/remix-run/remix/blob/cc65962b1a96d1e134336aa9620ef1dad7c5efb1/packages/remix-dev/vite/plugin.ts#L1149-L1168
+          // TODO(serhalp) Stop making these assumptions or assert them explictly.
+          // TODO(serhalp) Unless I'm misunderstanding something, we should only need to *replace*
+          // the default Remix Vite SSR entrypoint, not add an additional one.
           if (typeof config.build?.rollupOptions?.input === 'string') {
             config.build.rollupOptions.input = {
-              server: SERVER_ID,
+              [FUNCTION_HANDLER_CHUNK]: FUNCTION_HANDLER_MODULE_ID,
               index: config.build.rollupOptions.input,
             }
             if (config.build.rollupOptions.output && !Array.isArray(config.build.rollupOptions.output)) {
@@ -57,14 +75,14 @@ export function netlifyPlugin(): Plugin {
       }
     },
     async resolveId(source) {
-      if (source === SERVER_ID) {
-        return RESOLVED_SERVER_ID
+      if (source === FUNCTION_HANDLER_MODULE_ID) {
+        return RESOLVED_FUNCTION_HANDLER_MODULE_ID
       }
     },
     // See https://vitejs.dev/guide/api-plugin#virtual-modules-convention.
     load(id) {
-      if (id === RESOLVED_SERVER_ID) {
-        return serverCode
+      if (id === RESOLVED_FUNCTION_HANDLER_MODULE_ID) {
+        return FUNCTION_HANDLER
       }
     },
     async configResolved(config) {
@@ -74,14 +92,14 @@ export function netlifyPlugin(): Plugin {
     async writeBundle() {
       // Write the server entrypoint to the Netlify functions directory
       if (currentCommand === 'build' && isSsr) {
-        const functionsDirectory = join(resolvedConfig.root, '.netlify/functions-internal')
+        const functionsDirectory = join(resolvedConfig.root, NETLIFY_FUNCTIONS_DIR)
 
         await mkdir(functionsDirectory, { recursive: true })
 
-        const serverPath = join(resolvedConfig.build.outDir, 'server.js')
-        const relativeServerPath = toPosixPath(relative(functionsDirectory, serverPath))
+        const handlerPath = join(resolvedConfig.build.outDir, `${FUNCTION_HANDLER_CHUNK}.js`)
+        const relativeHandlerPath = toPosixPath(relative(functionsDirectory, handlerPath))
 
-        await writeFile(join(functionsDirectory, 'remix-server.mjs'), generateNetlifyFunction(relativeServerPath))
+        await writeFile(join(functionsDirectory, FUNCTION_FILENAME), generateNetlifyFunction(relativeHandlerPath))
       }
     },
   }

packages/remix-edge-adapter/README.md

@@ -3,6 +3,35 @@
 The Remix Edge Adapter for Netlify allows you to deploy your [Remix](https://remix.run) app to
 [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/).
 
+## Usage
+
 It is strongly advised to use [the Netlify Remix template](https://github.com/netlify/remix-template) to create a Remix
 site for deployment to Netlify. See [Remix on Netlify](https://docs.netlify.com/frameworks/remix/) for more details and
 other options.
+
+However, if you are using **Remix Vite**, you can instead deploy your existing site to Netlify by following these steps:
+
+1. Add dependencies on `@netlify/remix-edge-adapter` and `@netlify/remix-runtime`
+2. Use the Netlify Remix edge Vite plugin in your Vite config:
+
+```js
+// vite.config.js
+import { vitePlugin as remix } from "@remix-run/dev";
+import { netlifyPlugin } from "@netlify/remix-edge-adapter/plugin";
+
+export default defineConfig({
+  plugins: [remix(), netlifyPlugin(),
+});
+```
+
+3. Add an `app/entry.jsx` (.tsx if using TypeScript) with these contents:
+
+```js
+// app.entry.jsx or .tsx
+export { default } from 'virtual:netlify-server-entry'
+```
+
+### Hydrogen
+
+Hydrogen Vite sites are supported and automatically detected. However, additional setup is required. See
+<https://github.com/netlify/hydrogen-template> for details.

packages/remix-edge-adapter/package.json

@@ -40,6 +40,7 @@
   ],
   "scripts": {
     "prepack": "pnpm run build",
+    "postinstall": "deno types > deno.d.ts",
     "build": "tsup-node src/index.ts src/vite/plugin.ts --format esm,cjs --dts --target node16 --clean",
     "build:watch": "pnpm run build --watch"
   },
@@ -59,10 +60,10 @@
   "homepage": "https://github.com/netlify/remix-compute#readme",
   "dependencies": {
     "@netlify/remix-runtime": "2.3.0",
+    "@remix-run/dev": "^2.9.2",
     "isbot": "^5.0.0"
   },
   "devDependencies": {
-    "@remix-run/dev": "^2.9.2",
     "@remix-run/react": "^2.9.2",
     "@types/react": "^18.0.27",
     "@types/react-dom": "^18.0.10",

packages/remix-edge-adapter/src/common/server.ts

@@ -2,7 +2,7 @@ import type { AppLoadContext, ServerBuild } from '@netlify/remix-runtime'
 import { createRequestHandler as createRemixRequestHandler } from '@netlify/remix-runtime'
 import type { Context } from '@netlify/edge-functions'
 
-type LoadContext = AppLoadContext & Context
+export type LoadContext = AppLoadContext & Context
 
 /**
  * A function that returns the value to use as `context` in route `loader` and
@@ -49,10 +49,10 @@ export function createRequestHandler({
 
       if (response.status === 404) {
         // Check if there is a matching static file
-        const originResponse = await context.next({
+        const originResponse = await loadContext.next({
           sendConditionalRequest: true,
         })
-        if (originResponse.status !== 404) {
+        if (originResponse && originResponse?.status !== 404) {
           return originResponse
         }
       }

packages/remix-edge-adapter/src/index.ts

@@ -4,3 +4,4 @@ export type { GetLoadContextFunction, RequestHandler } from './common/server'
 export { createRequestHandler } from './common/server'
 export { config } from './classic-compiler/defaultRemixConfig'
 export { default as handleRequest } from './common/entry.server'
+export { createHydrogenAppLoadContext } from './vite/hydrogen'

packages/remix-edge-adapter/src/vite/hydrogen.ts

@@ -0,0 +1,64 @@
+import type { Context } from '@netlify/edge-functions'
+
+/**
+ * The base Hydrogen templates expect a globally defined `ExecutionContext` type, which by default
+ * comes from Oxygen:
+ * https://github.com/Shopify/hydrogen/blob/92a53c477540ee22cc273e7f3cbd2fd0582c815f/templates/skeleton/env.d.ts#L3.
+ * We do the same thing to minimize differences.
+ */
+declare global {
+  interface ExecutionContext {
+    waitUntil(promise: Promise<unknown>): void
+  }
+}
+
+/**
+ * For convenience, this matches the function signature that Hydrogen includes by default in its templates:
+ * https://github.com/Shopify/hydrogen/blob/92a53c477540ee22cc273e7f3cbd2fd0582c815f/templates/skeleton/app/lib/context.ts.
+ *
+ * Remix expects the user to use module augmentation to modify their exported `AppLoadContext` type. See
+ * https://github.com/remix-run/remix/blob/5dc3b67dc31f3df7b1b0298ae4e9cac9c5ae1c06/packages/remix-server-runtime/data.ts#L15-L23
+ * Hydrogen follows this pattern. However, because of the way TypeScript module augmentation works,
+ * we can't access the final user-augmented type here, so we have to do this dance with generic types.
+ */
+type CreateAppLoadContext<E extends {}, C extends {}> = (
+  request: Request,
+  env: E,
+  executionContext: ExecutionContext,
+) => Promise<C>
+
+const executionContext: ExecutionContext = {
+  /**
+   * Hydrogen expects a `waitUntil` function like the one in the workerd runtime:
+   * https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil.
+   * Netlify Edge Functions don't have such a function, but Deno Deploy isolates make a best-effort
+   * attempt to wait for the event loop to drain, so just awaiting the promise here is equivalent.
+   */
+  async waitUntil(p: Promise<unknown>): Promise<void> {
+    await p
+  },
+}
+
+/**
+ * In dev we run in a Node.js environment (via Remix Vite) but otherwise we run in a Deno (Netlify
+ * Edge Functions) environment.
+ */
+const getEnv = () => {
+  if (globalThis.Netlify) {
+    return globalThis.Netlify.env.toObject()
+  }
+  return process.env
+}
+
+export const createHydrogenAppLoadContext = async <E extends {}, C extends {}>(
+  request: Request,
+  netlifyContext: Context,
+  createAppLoadContext: CreateAppLoadContext<E, C>,
+): Promise<Context & C & Record<string, unknown>> => {
+  const env = getEnv() as E
+  const userHydrogenContext = await createAppLoadContext(request, env, executionContext)
+
+  // NOTE: We use `Object.assign` here because a spread would access the getters on the
+  // `netlifyContext` fields, some of which throw a "not implemented" error in local dev.
+  return Object.assign(netlifyContext, userHydrogenContext)
+}