Should Start docs document that import.meta.dirname changes during prerender?

[allohamora]

I ran into a confusing path-resolution issue with TanStack Start + Nitro prerendering.
In server code, I used import.meta.dirname to resolve a project-relative directory:

// src/server/db.ts
import path from 'node:path';
import { migrate } from 'orm';

// import.meta.dirname in the development equals '/project/src/server';
// import.meta.dirname in the prerender equals '/project/.output/server/_ssr'
const MIGRATIONS_DIR = path.join(import.meta.dirname, '..', '..', 'migrations');

migrate(MIGRATIONS_DIR);

This works in the dev environment, but during prerendering, the module is executed from the built server output (.output/server/_ssr), so import.meta.dirname no longer points to the expected path.

This could be fixed by resolving with process.cwd():

// src/server/db.ts
import path from 'node:path';
import { migrate } from 'orm';

// process.cwd() always equals '/project'
const MIGRATIONS_DIR = path.join(process.cwd(), 'migrations');

migrate(MIGRATIONS_DIR);

Should the Static Prerendering docs mention that server code executed during prerendering runs from generated output, so import.meta.dirname should not be assumed to refer to the original file path?

[chrisjcthomas]

Yes, this is an important nuance with Nitro-backed static prerendering that catches people off guard.

Why this happens

During static prerendering, Nitro does not execute your raw TypeScript files in-place. Instead, it:

1. Compiles and bundles the server code into the build output directory (.output/server/_ssr or similar).
2. Spawns a worker/evaluator to run the prerender phase against that compiled bundle.

Because import.meta.dirname (and __dirname) resolves to the directory containing the currently executing file, it evaluates to .output/server/_ssr at prerender time rather than src/server.

Recommended approaches

1. process.cwd() for build/prerender scripts:
   path.resolve(process.cwd(), 'migrations') is the standard workaround if your process is always invoked from the project root during local dev and prerender.

2. Nitro Assets / Storage for runtime portability:
   If this code also runs on production server deployments (e.g. standalone Node server, Docker, serverless), depending on source-tree file paths relative to process.cwd() can fail because migrations/ might not be copied to the deployment directory. In those cases, you can use Nitro's storage or server assets configuration in your Start/Nitro config:

   // app.config.ts / nitro config
   export default defineConfig({
     server: {
       assets: {
         migrations: './migrations',
       },
     },
   });

   And access them via useStorage('assets:migrations').

Opening a PR to note in the TanStack Start Prerendering / Nitro guide that server modules execute from the compiled output directory during prerender would definitely help prevent this confusion.