Local (disk)

Register the adapter

There is nothing to install - the adapter lives in @vitnode/core, which you already depend on. Import it and set storage.adapter, exactly as in the Quick start above.

Uploads then land under the current working directory of the API process:

Serve the stored files

Writing a file is not the same as answering a request for it. The adapter exposes a static descriptor - mountPath, root and stripPrefix - so the mount is derived from your publicPath instead of hardcoded in two places.

import { serveStatic } from '@hono/node-server/serve-static'
import { mkdirSync } from 'node:fs'

const staticStorage = vitNodeApiConfig.storage?.adapter?.static
if (staticStorage) {
  mkdirSync(staticStorage.root, { recursive: true })
  app.get(
    staticStorage.mountPath,
    serveStatic({
      root: staticStorage.root,
      rewriteRequestPath: (path) =>
        path.startsWith(staticStorage.stripPrefix)
          ? path.slice(staticStorage.stripPrefix.length)
          : path,
    }),
  )
}

VitNodeAPI({ app, vitNodeApiConfig })

import { serveStatic } from '@hono/node-server/serve-static'
import { mkdirSync } from 'node:fs'

const createVitNodeApi = () => {
  const app = new OpenAPIHono().basePath('/api')

  const staticStorage = vitNodeApiConfig.storage?.adapter?.static
  if (staticStorage) {
    mkdirSync(staticStorage.root, { recursive: true })
    app.get(
      staticStorage.mountPath,
      serveStatic({
        root: staticStorage.root,
        rewriteRequestPath: (path) =>
          path.startsWith(staticStorage.stripPrefix)
            ? path.slice(staticStorage.stripPrefix.length)
            : path,
      }),
    )
  }

  VitNodeAPI({ app, vitNodeApiConfig })

  return app
}

Mount serveStatic before VitNodeAPI on the standalone API: the request then skips the CORS, CSRF, rate-limiter and global middleware, which a static image has no use for. mkdirSync is only there so serveStatic does not warn about a missing root before the first upload.

The TanStack Start app is the same code in a different file, because /api/* on that app is one catch-all route handing the request to the very same Hono application - so the mount belongs inside it, not in the router. serveStatic comes from @hono/node-server, which that app does not depend on yet:

bun i @hono/node-server

pnpm i @hono/node-server

npm i @hono/node-server

Point the URLs at the right origin

The adapter builds absolute URLs as {baseUrl}/{publicPath}/{key}. baseUrl defaults to the configured API origin, so this env var is what decides whether your file URLs are reachable:

NEXT_PUBLIC_API_URL=http://localhost:8000

Pass baseUrl explicitly if the files are fronted by a different hostname than the API itself.

Upload something and verify

Open AdminCP → Core → System → Integrations and use Test storage on the Storage card: it uploads an image and tells you whether the round trip worked.

Then check the file is really on disk and really served:

ls public/uploads
curl -I http://localhost:8000/api/uploads/month_9_2026/admin-storage-test/<uuid>.webp

A 200 means the mount is right. A 404 with the file present on disk means the publicPath and the mount disagree.