feat: improve core to support vercel

example/app-cloudflare/package.json

@@ -16,10 +16,10 @@
     "@photonjs/core": "workspace:",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
-    "wrangler": "^4.15.1"
+    "wrangler": "^4.19.1"
   },
   "dependencies": {
-    "@universal-middleware/core": "^0.4.7",
+    "@universal-middleware/core": "^0.4.9",
     "awesome-framework": "workspace:",
     "hono": "^4.7.8"
   }

example/app-cloudflare/testRun.ts

@@ -25,6 +25,11 @@ function testRun(cmd: `pnpm run ${string}`) {
     expect(await response.text()).toBe('The API Route')
   })
 
+  test('/standalone', async () => {
+    const response: Response = await fetch(`${getServerUrl()}/standalone`)
+    expect(await response.text()).toBe('The /standalone Route')
+  })
+
   test('/bar', async () => {
     const response: Response = await fetch(`${getServerUrl()}/bar`)
     expect(await response.text()).toBe('bar')

example/app-cloudflare/vite.config.ts

@@ -1,4 +1,4 @@
-/// <reference types="@photonjs/core/api" />
+/// <reference types="@photonjs/core" />
 /* The Vite plugin cloudflare() will be replaced by this:
 import cloudflare from '@photonjs/cloudflare'
 */
@@ -10,7 +10,7 @@ export default defineConfig(({ mode }) => {
   return {
     // No photon server entry is defined, it will fallback to a virtual entry
     photon: {
-      handlers: {
+      entries: {
         // foo entry declares its route with `enhance` directly inside the file
         foo: 'src/middlewares/foo.ts',
         // bar entry route is declared here, and `enhance` is not used

example/app-hono-cloudflare/package.json

@@ -16,7 +16,7 @@
     "@photonjs/core": "workspace:",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
-    "wrangler": "^4.15.1"
+    "wrangler": "^4.19.1"
   },
   "dependencies": {
     "awesome-framework": "workspace:",

example/app-hono-cloudflare/server.ts

@@ -1,16 +1,12 @@
 // Will be moved to @photonjs/hono
 import { apply, serve } from '@photonjs/core/hono'
-import awesomeFramework from 'awesome-framework/universal-middleware'
 import { Hono } from 'hono'
 
 async function startServer() {
   const app = new Hono()
 
-  apply(
-    app,
-    // Adds the framework's middlewares
-    awesomeFramework,
-  )
+  // awesomeFramework will automatically be injected by apply
+  apply(app)
 
   return serve(app)
 }

example/app-hono-cloudflare/vite.config.ts

@@ -1,4 +1,3 @@
-/// <reference types="@photonjs/core/api" />
 /* The Vite plugin cloudflare() will be replaced by this:
 import cloudflare from '@photonjs/cloudflare'
 */

example/awesome-framework/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@photonjs/core": "workspace:",
-    "@universal-middleware/core": "^0.4.7",
+    "@universal-middleware/core": "^0.4.9",
     "@universal-middleware/sirv": "^0.1.20"
   },
   "devDependencies": {
@@ -21,6 +21,7 @@
     "./entry-client": "./dist/entry-client.js",
     "./render": "./dist/render.js",
     "./vite": "./dist/vite/index.js",
+    "./standalone": "./dist/photon/entries/standalone.js",
     "./universal-middleware": {
       "types": "./dist/photon/entries/prod.d.ts",
       "development": {

example/awesome-framework/src/photon/entries/standalone.ts

@@ -0,0 +1,21 @@
+import { enhance } from '@universal-middleware/core'
+
+const standaloneMiddleware = enhance(
+  async () => {
+    return new Response('The /standalone Route', {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/plain',
+      },
+    })
+  },
+  // enhance() adds meta data (a Universal Middleware in itself is just a Request => Response function)
+  {
+    name: 'awesome-framework:standalone',
+    path: '/standalone',
+    method: 'GET',
+  },
+)
+
+// This middleware will be used as a standalone handler, which means it is not included by `./universal-middleware` export
+export default standaloneMiddleware

example/awesome-framework/src/photon/middlewares/logger.ts

@@ -1,8 +1,8 @@
 import { enhance, MiddlewareOrder } from '@universal-middleware/core'
 
 export const loggerMiddleware = enhance(
-  (request: Request) => {
-    console.log('Request:', request.url)
+  (request: Request, ctx: Universal.Context) => {
+    console.log('Request:', request.url, 'Context:', ctx)
   },
   // enhance() adds meta data (a Universal Middleware in itself is just a Request => Response function)
   {

example/awesome-framework/src/vite/photonPlugin.ts

@@ -3,9 +3,29 @@ import type { Plugin } from 'vite'
 
 export function photonPlugin(): Plugin[] {
   return installPhoton('awesome-framework', {
+    // Enables full installation of all Photon plugins
     fullInstall: true,
+
+    // Disables code-splitting functionality for testing purposes
+    codeSplitting: {
+      framework: false,
+    },
+
+    // Always use those middlewares for all entries defined by Photon
     resolveMiddlewares() {
       return 'awesome-framework/universal-middleware'
     },
+
+    // Configuration for entry points used by Photon
+    entries: {
+      standalone: {
+        // Unique identifier for this entry point. Is resolved by Vite
+        id: 'awesome-framework/standalone',
+
+        // Sets composition mode to 'isolated', preventing it from
+        // being composed with middlewares defined in `resolveMiddlewares`
+        compositionMode: 'isolated',
+      },
+    },
   })
 }

package.json

@@ -3,7 +3,7 @@
     "========= Build": "",
     "build": "pnpm run build:photon && pnpm run build:awesome-framework",
     "build:photon": "pnpm --recursive --filter {packages/*} run build",
-    "build:awesome-framework": "cd example/awesome-framework/ && pnpm run build",
+    "build:awesome-framework": "pnpm --filter {example/awesome-framework} run build",
     "========= Test": "",
     "test": "test-e2e",
     "========= Formatting": "",
@@ -22,5 +22,10 @@
     "playwright": "^1.52.0",
     "prettier": "^3.2.5"
   },
+  "pnpm": {
+    "overrides": {
+      "@types/node": "^20.17.32"
+    }
+  },
   "packageManager": "[email protected]"
 }

packages/adapter-cloudflare/package.json

@@ -23,16 +23,16 @@
     "release:commit": "release-me commit"
   },
   "dependencies": {
-    "@cloudflare/vite-plugin": "^1.0.12",
+    "@cloudflare/vite-plugin": "^1.5.0",
     "@photonjs/core": "workspace:^",
-    "@universal-middleware/cloudflare": "^0.4.8"
+    "@universal-middleware/cloudflare": "^0.4.10"
   },
   "devDependencies": {
     "@brillout/release-me": "^0.4.3",
-    "@cloudflare/workers-types": "^4.20250515.0",
-    "@universal-middleware/core": "^0.4.7",
-    "@universal-middleware/h3": "^0.4.9",
-    "@universal-middleware/hono": "^0.4.10",
+    "@cloudflare/workers-types": "^4.20250604.0",
+    "@universal-middleware/core": "^0.4.9",
+    "@universal-middleware/h3": "^0.4.12",
+    "@universal-middleware/hono": "^0.4.15",
     "crossws": "^0.3.5",
     "h3": "^1.15.1",
     "tsup": "^8.4.0",

packages/adapter-cloudflare/src/adapters/dev.ts

@@ -1,14 +1,15 @@
 import type { ExportedHandlerFetchHandler } from '@cloudflare/workers-types'
+import { createIncompatibleServerError, createMissingApplyError, createMissingExportError } from '../utils/errors.js'
 
 export function asFetch(app: unknown, id: string): ExportedHandlerFetchHandler {
   if (!app) {
-    throw new Error(`[photon] Missing export default in ${JSON.stringify(id)}`)
+    throw createMissingExportError(id)
   }
 
   const server = (app as Record<symbol, string | undefined>)[Symbol.for('photon:server')]
 
   if (!server) {
-    throw new Error('[photon] { apply } function needs to be called before export')
+    throw createMissingApplyError()
   }
 
   switch (server) {
@@ -30,7 +31,5 @@ export function asFetch(app: unknown, id: string): ExportedHandlerFetchHandler {
       }
   }
 
-  throw new Error(
-    `[photon] Clouflare target is not compatible with server "${server}". We recommend using "hono" instead.`,
-  )
+  throw createIncompatibleServerError(server)
 }

packages/adapter-cloudflare/src/adapters/h3.ts

@@ -1,13 +1,14 @@
 import type { ExportedHandlerFetchHandler, Response } from '@cloudflare/workers-types'
 import type { apply as applyAdapter } from '@universal-middleware/h3'
 import { toWebHandler } from 'h3'
+import { createMissingDependencyError } from '../utils/errors.js'
 
 async function tryImportCrossws() {
   try {
     const { default: wsAdapter } = await import('crossws/adapters/cloudflare')
     return wsAdapter
   } catch (e) {
-    throw new Error('crossws is not installed', { cause: e })
+    throw createMissingDependencyError('crossws', e)
   }
 }
 

packages/adapter-cloudflare/src/plugin.ts

@@ -1,13 +1,9 @@
-/// <reference types="@photonjs/core/api" />
 import { cloudflare as cloudflareVitePlugins, type PluginConfig } from '@cloudflare/vite-plugin'
-import { isPhotonMeta } from '@photonjs/core/api'
-import { supportedTargetServers } from '@photonjs/core/vite'
+import { supportedTargetServers, targetLoader } from '@photonjs/core/vite'
 import type { Plugin } from 'vite'
 
 const moduleId = 'photon:cloudflare'
-const virtualModuleId = `\0${moduleId}`
 
-// TODO: create actual virtual Target Entries for each server
 export function cloudflare(config?: Omit<PluginConfig, 'viteEnvironment'>): Plugin[] {
   return [
     {
@@ -19,88 +15,52 @@ export function cloudflare(config?: Omit<PluginConfig, 'viteEnvironment'>): Plug
             photon: {
               // @cloudflare/vite-plugin has its own dev server
               devServer: false,
+              codeSplitting: {
+                target: false,
+              },
+              // Should be set to the value of cloudflareVitePlugins -> viteEnvironment.name
+              // defaultBuildEnv: 'cloudflare',
             },
           }
         },
       },
     },
-    supportedTargetServers('cloudflare', ['hono', 'h3']),
-    {
-      name: `${moduleId}:resolver`,
-
-      async resolveId(id, importer, opts) {
-        if (id.startsWith(moduleId)) {
-          const resolved = await this.resolve(id.replace(/^photon:cloudflare:/, ''), importer, opts)
-
-          if (!resolved) {
-            return this.error(`[photon][cloudflare] Cannot resolve ${id}`)
-          }
-
-          return {
-            ...resolved,
-            id: `${virtualModuleId}:${resolved.id}`,
-          }
-        }
-      },
-
-      // TODO add tests
-      async load(id) {
-        if (!id.startsWith(virtualModuleId)) return
-        const actualId = id.slice(virtualModuleId.length + 1)
-
-        const info = this.getModuleInfo(id)
-
-        if (!isPhotonMeta(info?.meta)) {
-          return this.error(`[photon][cloudflare] ${actualId} is not a Photon entry`)
-        }
-
+    ...targetLoader('cloudflare', {
+      async load(id, { meta }) {
         const isDev = this.environment.config.command === 'serve'
 
-        if (info.meta.photon.type === 'server') {
-          // `server` usually exists only during build time
-          if (info.meta.photon.server) {
-            return {
-              // language=ts
-              code: `import serverEntry from ${JSON.stringify(actualId)};
-import { asFetch } from "@photonjs/cloudflare/${info.meta.photon.server}";
+        // `server` usually exists only during build time
+        if (meta.server) {
+          return {
+            // language=ts
+            code: `import serverEntry from ${JSON.stringify(id)};
+            import { asFetch } from "@photonjs/cloudflare/${meta.server}";
 
-export const fetch = asFetch(serverEntry);
-export default { fetch };
-`,
-              map: { mappings: '' },
-            }
+            export const fetch = asFetch(serverEntry);
+            export default { fetch };
+            `,
+            map: { mappings: '' },
           }
+        }
 
-          if (isDev) {
-            return {
-              // language=ts
-              code: `import serverEntry from ${JSON.stringify(actualId)};
-import { asFetch } from "@photonjs/cloudflare/dev";
-
-export const fetch = asFetch(serverEntry, ${JSON.stringify(actualId)});
-export default { fetch };
-`,
-              map: { mappings: '' },
-            }
-          }
-        } else {
+        if (isDev) {
           return {
             // language=ts
-            code: `import handler from ${JSON.stringify(actualId)};
-import { getRuntime } from "@universal-middleware/cloudflare";
+            code: `import serverEntry from ${JSON.stringify(id)};
+import { asFetch } from "@photonjs/cloudflare/dev";
 
-export const fetch = (request, env, ctx) => {
-  return handler(request, {}, getRuntime(env, ctx))
-};
+export const fetch = asFetch(serverEntry, ${JSON.stringify(id)});
 export default { fetch };
 `,
             map: { mappings: '' },
           }
         }
 
-        return this.error(`[photon][cloudflare] Unable to load ${actualId}`)
+        return this.error(`[photon][cloudflare] Unable to load ${id}`)
       },
-    },
+    }),
+    supportedTargetServers('cloudflare', ['hono', 'h3']),
+    // FIXME do not enforce ssr env?
     ...cloudflareVitePlugins({ ...config, viteEnvironment: { name: 'ssr' } }),
   ]
 }

packages/adapter-cloudflare/src/utils/errors.ts

@@ -0,0 +1,28 @@
+import { PhotonBugError, PhotonConfigError, PhotonDependencyError, PhotonUsageError } from '@photonjs/core/errors'
+
+// Utility functions for common error scenarios
+export function createMissingExportError(id: string): PhotonUsageError {
+  return new PhotonUsageError(`Missing export default in ${JSON.stringify(id)}`)
+}
+
+export function createMissingApplyError(): PhotonUsageError {
+  return new PhotonUsageError('{ apply } function needs to be called before export')
+}
+
+export function createIncompatibleServerError(server: string): PhotonConfigError {
+  return new PhotonConfigError(
+    `Cloudflare target is not compatible with server "${server}". We recommend using "hono" instead.`,
+  )
+}
+
+export function createMissingDependencyError(dependency: string, cause?: unknown): PhotonDependencyError {
+  return new PhotonDependencyError(
+    `${dependency} is not installed. Please install ${dependency} to use this functionality with Cloudflare.`,
+    { cause },
+  )
+}
+
+export function assert(condition: unknown): asserts condition {
+  if (condition) return
+  throw new PhotonBugError()
+}