Handle API routes in Vike

[rtritto]

Alternatives:

• REST-as-RPC approach (recommended)

  • Example of functionRetrieve API:

    // /server/api/functionRetrieve.ts
    import type { Context } from 'hono'
    export function functionRetrieve(c: Context) {
      return c.text('Hello World!')
    }

  • In /server/api directory, create an index.ts file that uses static import of api files and export them as the default export. Eg:

    // /server/api/index.ts
    import { functionCreate } from './functionRetrieve'
    export default {
      functionRetrieve
    }

  • In /server/index.ts, add the router handler of APIs (all APIs will have POST method):

    // /server/index.ts
    import api from './api'
    app.post('/api/:functionName', async (c) => {
      const functionName = c.req.param('functionName') as keyof typeof api
      if (!(functionName in api)) {
        return c.json({ error: 'Function not found' }, 400)
      }
      try {
        return await api[functionName](c)
      } catch (error) {
        console.error(error)
        return c.json({ error: 'Internal server error' }, 500)
      }
    })

• Packages

  • universal-autorouter: add it as dependency
  • universal-autorouter-hono: add it as dev dependency; load API routes in Hono (HMR available)
  • vite-plugin-build-routes: add it as dev dependency; build API routes

Analysis

Show Analysis

## Use case with Vite plugin

Repro can be found in vite-autorouter branch.

Usage (draft and outdated)

Show

// ./vite.config.ts

import vike from 'vike/plugin'
import { vikeNode } from 'vike-node/plugin'
import vikeSolid from 'vike-solid/vite'
import type { UserConfig } from 'vite'
import viteApiAutoloader from 'vite-plugin-api-autorouter/vite'

export default {
  plugins: [
    vike(),
    vikeSolid(),
    vikeNode('server/index.ts'),
    viteApiAutoloader('server/api')
  ]
} satisfies UserConfig

// ./server/index.ts

import path from 'node:path'
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import vike from 'vike-node/hono'
import viteApiAutoloader from 'vite-plugin-api-autorouter/server'

const app = new Hono()

app.use(viteApiAutoloader({
  app,
  prefix: '/api',
  routesDir: path.resolve(import.meta.dirname, 'api'),
  viteDevServer: globalThis.__vikeNode?.viteDevServer
}))

app.use(vike())

const port = +(process.env.PORT || 3000)

serve({
  fetch: app.fetch,
  port
}, () => console.log(`Server running at http://localhost:${port}`))

// vite-plugin-api-autorouter/vite

import fs from 'node:fs'
import path from 'node:path'
import { build, type Plugin } from 'vite'

type PluginOptions = {
  entry: string // File path to bundle
  pattern?: string // File path pattern to bundle
}

export default function bundleFilesPlugin(options: string | PluginOptions): Plugin {
  let isBuild: boolean
  let config: ResolvedConfig
  return {
    name: 'vite-plugin-api-autorouter',
    apply: 'build',
    enforce: 'post',
    configResolved: (config_) => {
      config = config_
    },
    async buildStart() {
      const { entry, pattern = '**/*.ts' } = typeof options === 'string' ? { entry: options } : (options as PluginOptions)

      const entryFull = path.resolve(config.root, entry)
      const outFull = path.resolve(config.root, config.build.outDir)

      const filepaths = fs.globSync(pattern, { cwd: entryFull })

      // Create an input map for Rollup
      const entries: Record<string, string> = {}
      for (const rawFilepath of filepaths) {
        // Normalize file paths for Windows
        const filepath = rawFilepath.replaceAll('\\', '/')
        // Use relative paths as keys to preserve directory structure
        const resolvedFilepath = path.resolve(entryFull, filepath)
        const relativePath = filepath.replace(/\.ts$/, '')
        entries[relativePath] = resolvedFilepath
      }

      // Run a build for each file
      await build({
        configFile: false, // Avoid conflicts with the main Vite config
        build: {
          ssr: true,
          target: 'esnext',
          rollupOptions: {
            input: entries,
            output: {
              dir: outFull, // Directory for this specific file
              format: 'esm',
              sanitizeFileName: false,
              entryFileNames: 'api/[name].mjs', // File name pattern
              chunkFileNames: 'chunks/chunk-[hash].mjs' // Output for chunks
            }
          },
          emptyOutDir: false // Do not clear the output folder for incremental builds
        },
        ...config.resolve && { resolve: config.resolve }
      })
    }
  }
}

// vite-plugin-api-autorouter/server

import autoloadRoutes from 'universal-autorouter'

export default ({ app, prefix, routesDir, viteDevServer }) => {
  const pattern = process.env.NODE_ENV === 'production' ? '**/*.mjs' : '**/*.ts'
  await autoloadRoutes(app, {
    pattern,
    prefix,
    routesDir,
    viteDevServer
  })
}

Use case with Vike plugin (it's only an example and will not be implemented; see "Use case with Vite plugin")

Use case to create a Vike plugin (eg vike-api-routes) for API routes.

Usage (draft)

Show

```ts
// ./vite.config.ts

import vike from 'vike/plugin'
import { vikeNode } from 'vike-node/plugin'
import vikeSolid from 'vike-solid/vite'
import vikeApiRoutes from 'vike-api-routes/vite'
import type { UserConfig } from 'vite'

export default {
  plugins: [
    vike(),
    vikeSolid(),
    vikeNode('server/index.ts'),
    vikeApiRoutes({
      entry: 'server/api',
      outputDir: 'dist/server/api'
    })
  ]
} satisfies UserConfig
```

```ts
// ./server/index.ts

import path from 'node:path'
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import vikeApiRoutes from 'vike-api-routes/server'
import vike from 'vike-node/hono'

app.use(vikeApiRoutes({
  app,
  prefix: '/api',
  routesDir: path.resolve(import.meta.dirname, 'api')
}))

app.use(vike())

const port = +(process.env.PORT || 3000)

serve({
  fetch: app.fetch,
  port
}, () => console.log(`Server running at http://localhost:${port}`))
```

```ts
// vike-api-routes/vite

import fs from 'node:fs'
import path from 'node:path'
import { build, type Plugin } from 'vite'

interface BundleFilesOptions {
  entry: string // File path to bundle
  outputDir: string // Base output directory (e.g., 'dist')
}

export default function bundleFilesPlugin(options: BundleFilesOptions): Plugin {
  return {
    name: 'vite-plugin-bundle-files',
    enforce: 'post',
    async buildStart() {
      const { entry, outputDir } = options

      const cwd = process.cwd()
      const entryFull = path.resolve(cwd, entry)
      const outFull = path.resolve(cwd, outputDir)

      const filepaths = fs.globSync('**/*.ts', { cwd: entryFull })

      // Create an input map for Rollup
      const entryFilepathFull = {} as Record<string, string>
      for (const filepath of filepaths) {
        // Use relative paths as keys to preserve directory structure
        const resolvedFilepath = path.resolve(entryFull, filepath).replaceAll('\\', '/').replaceAll('[', '\[').replaceAll(']', '\]')
        // const relativePath = path.relative(entryFull, resolvedFilepath)
        const relativePath = filepath.replace(/\.ts$/, '').replaceAll('\\', '/')
        entryFilepathFull[relativePath] = resolvedFilepath
      }

      // Run a build for each file
      await build({
        configFile: false, // Avoid conflicts with the main Vite config
        build: {
          ssr: true,
          target: 'esnext',
          rollupOptions: {
            input: entryFilepathFull,
            output: {
              dir: outFull, // Directory for this specific file
              format: 'esm',
              entryFileNames: '[name].mjs' // File name pattern
            }
          }
        }
      })
    }
  }
}
```

```ts
// vike-api-routes/server

import autoloadRoutes from 'universal-autorouter'

export default ({ app, prefix, routesDir }) => {
  let pattern
  let viteDevServer
  if (process.env.NODE_ENV === 'production') {
    pattern = '**/*.mjs'
  } else {
    pattern = '**/*.ts'
    viteDevServer = globalThis.__vikeNode.viteDevServer
  }
  await autoloadRoutes(app, {
    pattern,
    prefix,
    routesDir,
    viteDevServer
  })
}
```

Related

• [Feature] Add option to bundle the directory of server routes vike-server#35
• An answer [Feature] Add option to bundle the directory of server routes vike-server#35 (comment)
• feat: API middleware vike-server#34
• Improve file system routing for APIs magne4000/universal-middleware#86
• Bundle api directory in `dist` #2025

PS: Feel free to ask anything and/or contribute.

[rtritto]

@Blankeos what do you think?

FYI @SleepyDeb

[brillout]

Official response here.

[rtritto]

Point 1. can be achieved using viteDevServer as parameter:

// ./server/index.ts

// ...
import viteApiAutoloader from 'vite-plugin-api-autorouter/server'
// ...

app.use(viteApiAutoloader({
  app,
  prefix: '/api',
  routesDir: path.resolve(import.meta.dirname, 'api'),
  viteDevServer: globalThis.__vikeNode?.viteDevServer
}))

PS: I updated the first comment ("Usage (draft)" section)

---

Point 2., Vite dedupe chunks in same folder.

Having ./utils/getData that is used by SSR and API routes:

// /utils/getData.ts
export default function getData() {
  return ['Hello', 'World']
}

// /pages/index/+data.ts
import getData from '../../utils/getData'

export const data = () => {
  const data = getData()
  return {
    data
  }
}

// /server/api/user/index.ts
import type { Context } from 'hono'

import getData from '../../../utils/getData'

export default (c: Context) => {
  const data = getData()
  return c.json(data)
}

Separated builds (build for pages as /dist/server/entries/pages_index.mjs + build for API routes as /dist/server/api/user/index.mjs) can't be used because the getData function is bundled in each mjs file.

So we need a single build to create a shared chunk where output will be:

• /dist/server/chunks/chunk-[hash].mjs that exports getData function
• /dist/server/entries/pages_index.mjs that imports getData function from /dist/server/chunks/chunk-[hash].mjs
• /dist/server/api/user/index.mjs that imports getData function from /dist/server/chunks/chunk-[hash].mjs

How the single build can be achieved? Maybe using some vite's hook in the vite's plugin that return the vite config or merge the vite config.

Note: After my reverse of Telefunc, for the single build I didn't find any answer

[rtritto]

Repro of current works: https://github.com/templates-ecosystem/template-vike-solid-daisyui-hono/tree/vite-autorouter

[brillout]

See Telefunc's usage of https://github.com/brillout/vite-plugin-server-entry.

[rtritto]

Package for vite-plugin-api-autorouter was released!

Some points:

1. For API routes files, to get the related dist as directory tree instead of single file, I have to replace the injected Vike config.build.rollupOptions.output.entryFileNames with '[name].mjs'. So now I have same behaviour with server (entries) pages:
   Eg:

   • /dist/server/entries/pages/index.mjs instead of /dist/server/entries/pages_index.mjs
   • /dist/server/entries/pages/user/@id.mjs instead of /dist/server/entries/pages_user_-id.mjs

   The directory tree instead of single file can break some Vike's ecosystem or something else?

2. Files in /dist/server/entries use .mjs extensions.
   Why files in /dist/server/chunks don't use .mjs extensions?

PS: @brillout Thanks for help and support!

[brillout]

Congrats 🚀

[rtritto]

New package universal-autorouter-hono released 🚀
Load (with HMR) inside Hono all API routes using filesystem.
Under the hood, on change of a file handler, inject it into Hono to use HMR (not supported by Hono).

Related Hono feature request honojs/hono#3817

[brillout]

Neat!

[rtritto]

I have a route handler src/server/api/user/index.ts that uses the file /src/utils.ts.

viteDevServer.watcher.on('change', async (file) => {
  // handle file change
})

When I update the file /src/utils.ts, there is an easy way with Vite to get the file src/server/api/user/index.ts that is previously loaded with ssrLoadModule?

[rtritto]

@brillout how is this achieved by Vike?

Example

// /src/pages/index/+Page.tsx
import { getMSG } from '../../utils.ts'

function Page() {
  return (
    <button onClick={() => alert(getMSG())}>Click me</button>
  )
}

export { Page }

// /src/utils.ts
export const getMSG = () => 'Hello Word!'

Steps:

• vike dev
• go to http://localhost:3000
• click the button in the page and an the alert of Hello Word! is displayed
• change the Hello Word! value in getMSG and save file utils.ts
• reload page
• click the button in the page and an the alert message is displayed with the new value

How is the Page reloaded with the new code imported from utils.ts?

[brillout]

https://vite.dev/guide/ssr.html#server-side-rendering-ssr

[rtritto]

I solved using viteDevServer.moduleGraph.getModulesByFile (commit) from https://vite.dev/guide/api-environment-instances.html#separate-module-graphs

[rtritto]

The vite-plugin-build-routes dependency correctly bundles files from directory /server/api to directory /dist/server/api.
On Vercel, in the build step of the deploy, files in the directory /dist/server/api are generated (I checked with ls after vike build) but, on runtime, when the /dist/server/index.mjs needs to dynamically import one file (await import('./api/<FUNCTION>.mjs')) that is contained in /dist/server/api and I get:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/var/task/dist/server/api/<FUNCTION>.mjs' imported from /var/task/dist/server/index.mjs
    at finalizeResolution (node:internal/modules/esm/resolve:263:11)
    at moduleResolve (node:internal/modules/esm/resolve:919:10)
    at moduleResolveWithNodePath (node:internal/modules/esm/resolve:1043:14)
    at defaultResolve (node:internal/modules/esm/resolve:1086:79)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:650:12)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:599:25)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:582:38)
    at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:241:38)
    at onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:542:36)
    at TracingChannel.tracePromise (node:diagnostics_channel:337:14) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///var/task/dist/server/api/<FUNCTION>.mjs'
}

I found that the issue can be related to @vercel/nft and then in vercel.json I added:

{
  "outputDirectory": "dist/client",
+  "functions": {
+    "api/ssr.js": {
+      "includeFiles": "dist/server/api"
+    }
+  },
  "rewrites": [
    {
      "source": "/((?!assets/).*)",
      "destination": "/api/ssr.js"
    }
  ]
}

I did some try and changed the value of includeFiles (eg dist/server/api/**) but nothing.

Source:

• https://dev.to/martinratinaud/nextjs-on-vercel-missing-files-after-build-when-interpolating-file-names-40bl
• https://vercel.com/guides/how-can-i-use-files-in-serverless-functions
• Vercel.json's "includeFiles" with `pages/api` serverless functions vercel/next.js#14807

@brillout do you have any idea?

Edit: I asked help on vercel/next.js#14807 (reply in thread)

[rtritto]

I fixed using another approach (on main post, I added the REST-as-RPC approach) that works like a charm:

• after a route handler file is changed, the server is automatically restarted (no HMR needed)
• API files are directly bundled (no vite-plugin-build-routes needed) with static imports and the default export

[rtritto]

This REST-as-RPC approach whould be better of using Telefunc.

@brillout what do you think?
What are the differences?
Is there any use case to prefer Telefunc?

FYI @magne4000 @nitedani

[brillout]

This RPC approach whould be better of using Telefunc.

I don't understand what you mean.

[brillout]

Ah, I'm seeing your new OP content.

https://telefunc.com/event-based
https://telefunc.com/shield#typescript-automatic
https://brillout.github.io/rules/#try