Support for Custom Server Wrapper and Custom Exports

[rtritto]

Vike currently integrates Universal Deploy, which uses a default serve file as the server wrapper for the Node environment.

A user should be able to create and use a custom server wrapper instead of being forced to use the default one that doesn't support any export.

The Problem: Custom server wrapper & Server entry (dist/server/entry.mjs)

On using a custom server wrapper (e.g. server/entrypoint.ts as export default app), Vike throws the error The server production entry is missing (see #3229) during production runtime.

This happens because the dist/server/entry.mjs generated by Universal Deploy is not being imported. To fix this, dist/server/entry.mjs needs to be imported into dist/server/index.mjs during the build step.

This could be solved with two different approaches injecting virtual:vike:global-entry:server:

1. in Vike's pluginServerEntryInject.ts:

-magicString.prepend(`import "${serverEntryVirtualId}";\n`)
+magicString.prepend(`import "${serverEntryVirtualId}";\nimport "virtual:vike:global-entry:server";\n`)

2. in Universal Deploy's target.ts:

 if (resolvedEntry && id === resolvedEntry) {
-  if (!code.includes("virtual:ud:")) this.warn(`{ entry: "${entry}" } is missing "virtual:ud:catch-all" import.`);
+  const s = new MagicString(code);
+  s.prepend(`import 'virtual:vike:global-entry:server'\n`);  // or use a new UD option like `virtualEntry` to pass `virtual:vike:global-entry:server` from Vike
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true })
+  };
 }

Since Universal Deploy is already integrated into Vike, Vike could easily expose the entry option (see Vike Feature Request that uses universal-deploy PR #31).
Without Universal Deploy disabled (so without the +server file), users are forced to install third-party packages that is just to boot their custom server wrapper.

The Use Case: Custom Exports

Why is a custom server wrapper so important? Because in production environments, developers often need to define custom exports directly from the server bundle. Currently Vike doesn't support custom exports (e.g. exports defined in the +server file are ingnored and replaced with the content of the Universal Deploy's serve)

An use case is with the manual integration in Vercel (see manual integration of Vercel):

1. Vercel Serverless Functions (api/ssr.js)
   To handle standard SSR requests, we need to export the fetch handler:

import app from '../dist/server/index.mjs'  // import the server app
export const GET = app.fetch
export const POST = app.fetch

2. Vercel Cron Jobs (api/cron.js)
   Sometimes we need to run background tasks using the same server context:

  import { getDocuments } from '../dist/server/index.mjs'  // same file of the server app
  const documents = await getDocuments()
  // Do something with the documents
  console.log('Documents:', documents)

A custom server wrapper is essential here, as it would allow developers to gracefully export the server app instance alongside any custom exports needed by the deployment platform.

Reproductions

• vike-with-vercel (example using the feature feat: add entry option to +server #3291)
• minimal-server-vercel (commit cb06121, for further details, see the comments here and here)

References

• Custom target #3201
• Disable build of /dist/server/index.mjs #3219
• Support custom server entry #3221
• +server.js with renderPage() instead of Universal Deploy #3233
• feat: add entry option to +server #3291
• Cron usage with Vike magne4000/vite-plugin-vercel#239

[rtritto]

I found a solution (described below) for the build.
Import dist/server/entry.mjs in the dist/server/index.mjs without using +server and without any changes/patches on vike.
The dist/server/index.mjs built by emit-server-index vite plugin and not by vike with +server enabled.
Now standaloner can include dist/server/entry.mjs in the final bundle (unique dist/server/index.mjs).

// server/entrypoint.ts
import 'virtual:@brillout/vite-plugin-server-entry:serverEntry'
export { default } from './app' // export server app as default

// vite.config.ts
{
  name: 'emit-server-index',
  apply: 'build',
  enforce: 'post',
  config() {
    return {
      environments: {
        ssr: {
          resolve: {
            noExternal: true
          },
          build: {
            rolldownOptions: {
              input: {
                index: 'server/entrypoint.ts'  // build dist/server/index.mjs from server/entrypoint.ts
              }
            }
          }
        }
      }
    }
  }
}

Note: virtual:vike:global-entry:server only exists during the vike build, so in the emit-server-index plugin context I need to use virtual:@brillout/vite-plugin-server-entry:serverEntry (same logic used in pluginServerEntryInject.ts) that is global

@brillout @magne4000 how can I add the /api route in development with vike dev? (The app.fetch should be used like +server.fetch)

[rtritto]

@brillout my use case is equal to telefunc (vike/examples/telefunc) having the /api route instead of the /_telefunc route. In the telefunc example, to start development, the server (node ./server) is used instead of vike (vike dev).
Can we add /api routes on the vike runtime?
Perhaps a new vike's feature on vite.config.ts to expose the vike's server app. By this way we can attach /api routes to the server app.

[rtritto]

@magne4000 WDYT?

[rtritto]

Alternatives:

• Customize server app in development #3339 → closed in favour of Custom server app #3340
• Custom server app #3340 → achieved with the pointer import in +config.server

To load server in development, the pointer import can be used: import:../server/index.ts:default in the +config.server option.

[rtritto]

Once #3341 and #3342 have been completed:

• the Telefunc example can be updated (same logic of +config.photon.server option, see pages/+config.ts)
• I will update the vike-with-vercel example to add it in the vike's documentation

FYI @brillout @magne4000

[brillout]

@rtritto Again, this isn't our plan and we're quite busy with higher priorities. We'll work on this later (most likely #3233, no ETA). In the meantime you can use renderPage() without +server (use vavite) for full control.

If you want to contribute, then spend a substantial amount of time to understand our perspective. Carefully re-read every message we sent you. You can push back, but then make it as clear, as succinct, and as easy as possible for us to understand. We unfortunately all have a hard time trying to understand you, and we have to repeat ourselves quite a lot (I unfortunately feel like you aren't listening).

Thanks for understanding.

[UnknownHawkins]

[brillout]

@UnknownHawkins What's your use case for wanting that?