File Convention

How QUESTPIE discovers your files and wires them into the runtime — naming rules, layouts, and discovery mechanics.

QUESTPIE uses your file system as the source of truth. Drop a file in the right directory, run codegen, and it's part of your app. No manual registration.

Directory Categories

Each directory maps to a category of entity:

Directory	Entity	Export Style	Key Derivation
`collections/`	Collections	Default or named	Factory arg → export name
`globals/`	Globals	Default or named	Factory arg → export name
`routes/`	Routes	Default	Filename → camelCase/slash path
`jobs/`	Jobs	Default	Filename → camelCase
`routes/` (raw)	Routes	Default	Filename → slash-separated path
`services/`	Services	Default	Filename → camelCase
`emails/`	Email templates	Default	Filename → camelCase
`blocks/`	Blocks	Named exports	Factory arg → export name
`messages/`	i18n messages	Default	Filename → locale key
`migrations/`	DB migrations	Default	Array (ordered)
`seeds/`	DB seeds	Default	Array (ordered)

Name derivation

Factory string args are entity identities for collections, globals, blocks, views, and components. They are converted from kebab-case to camelCase:

Mermaid

Rendering diagram...

Only hyphens are camelized. Underscores are preserved, so global("site_settings") generates the key site_settings, not siteSettings.

Single-File Conventions

Some configs are single files, not directories:

File	Factory	Purpose
`questpie.config.ts`	`runtimeConfig({...})`	DB, plugins, adapters
`modules.ts`	`export default [...]`	Module dependencies
`config/auth.ts`	`authConfig({...})`	Auth configuration
`config/app.ts`	`export default appConfig({...})`	App-level config (context, locale, tenant scoping)
`config/admin.ts`	`adminConfig({...})`	Admin sidebar, dashboard, branding, locale
`config/openapi.ts`	`openApiConfig({...})`	OpenAPI and Scalar UI options
`fields.ts`	`export default { ...customFields }`	Custom field type definitions

Layouts

By-Type (default)

Group files by entity type:

Mermaid

Rendering diagram...

By-Feature

Group files by domain:

Mermaid

Rendering diagram...

Mixed

Both layouts can coexist. Codegen scans all configured paths.

Nested Namespacing

Routes support nested directories:

Mermaid

Rendering diagram...

Discovery Process

Scan — Codegen walks the configured directories
Match — Files matching the category pattern are picked up
Import — Each file is imported and its exports are read
Key derivation — Factory string arg → export name → filename (camelCase)
Merge — Project entities + module entities are merged
Emit — Generated types and runtime wiring in .generated/

The `#questpie` Import

Collection and global files use #questpie as an import alias:

import { collection } from "#questpie/factories";

This resolves to the generated app context, giving the builders access to field types and relation targets for autocompletion. It's configured via TypeScript path mapping.

Codegen — What gets generated
Modules — Module composition
Plugins — Plugin system
Project Structure — Full layout reference

On this page