void prepare and void dev fail in a fresh clone when app code imports @auth-schema #823

Version

void 1.9.0, better-auth 1.7.22

Problem

The auth guide has apps import the generated tables as @auth-schema, both in app code and in db/schema for foreign keys. Void writes that file, .void/better-auth-schema.ts, but it's gitignored, so a fresh clone doesn't have it. On a fresh clone, both commands that create it fail.

void prepare loads auth.ts to build the schema. If anything auth.ts imports reaches @auth-schema, loading it needs the file it's about to write. For example, a signup hook that looks up a referrer:

// auth.ts
import { getUserByReferralCode } from '@/server/data/users'; // imports userTable from '@auth-schema'

export default defineAuth(({ defaults }) => ({
  ...defaults,
  databaseHooks: {
    user: { create: { after: async (user, ctx) => { /* getUserByReferralCode(…) */ } } },
  },
}));

$ rm -rf .void && pnpm void prepare
■ Cannot find module '@auth-schema' imported from '…/src/server/data/users.ts'

void dev fails even when auth.ts doesn't import @auth-schema, as long as db/schema references userTable the way the guide shows:

$ rm -rf .void node_modules/.vite && pnpm dev
(!) Failed to run dependency scan. Skipping dependency pre-bundling. Error: The following dependencies are imported but could not be resolved:
  @auth-schema (imported by …/src/server/data/users.ts)
error when starting dev server:
Error: Failed to load url ../../.void/better-auth-schema (resolved id: ../../.void/better-auth-schema) in …/db/schema/feature-request.ts. Does the file exist?
    at getWorkerEntryExportTypes (./workers/runner-worker/index.js:252:24)

It looks like the Cloudflare plugin loads the Worker entry (getWorkerEntryExportTypes) while the server starts, before Void's buildStart runs writeAuthDatabaseFiles(). Once .void exists, both commands work. That's why existing checkouts never see the problem, and why a new contributor or a CI job runs into it first.

Workaround

Import the modules inside the hook, not at the top of auth.ts, and run void prepare before the first void dev.

Proposal

• prepare: generate the schema without loading what auth.ts imports. Or, when the file is missing, write it from the default tables first, then regenerate once auth.ts has loaded. Additional fields and plugin tables would only change column lists, not the exports apps import.
• dev: write the auth files before the Worker entry is first loaded, for example in configureServer before Cloudflare's plugin runs, instead of in buildStart.
• Docs: until then, say in the auth guide that auth.ts mustn't import anything that reaches @auth-schema at the top level, and that a fresh clone needs void prepare before void dev.

Related: #677, which added the @auth-schema import to the guide.