File Structure

Guiding Principles

Files that change together should live together.
Minimal requirements, maximum flexibility

Example file structure

├── src/
│   ├── blitz-client.ts
│   ├── blitz-server.ts
│   ├── core/
│   │   ├── components/
│   │   │   ├── Form.tsx
│   │   │   └── LabeledTextField.tsx
│   │   └── layouts/
│   │       └── Layout.tsx
│   ├── auth/
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   └── SignupForm.tsx
│   │   ├── mutations/
│   │   │   ├── login.ts
│   │   │   ├── logout.ts
│   │   │   └── signup.ts
│   │   ├── auth-utils.ts
│   │   └── validations.ts
│   ├── users/
│   │   ├── hooks/
│   │   │   └── useCurrentUser.ts
│   │   └── queries/
│   │       └── getCurrentUser.ts
│   ├── projects/
│   │   ├── components/
│   │   │   ├── Project.tsx
│   │   │   ├── ProjectForm.tsx
│   │   │   └── Projects.tsx
│   │   ├── mutations/
│   │   │   ├── createProject.ts
│   │   │   ├── createProject.test.ts
│   │   │   ├── deleteProject.ts
│   │   │   ├── deleteProject.test.ts
│   │   │   ├── updateProject.ts
│   │   │   └── updateProject.test.ts
│   │   └── queries/
│   │       ├── getProject.ts
│   │       └── getProjects.ts
│   └── pages/
│       ├── api/
│       │   └── stripe-webhook.ts
│       ├── 404.tsx
│       ├── _app.tsx
│       ├── _document.tsx
│       ├── index.test.tsx
│       ├── index.tsx
│       ├── auth/
│       │   ├── login.tsx
│       │   └── signup.tsx
│       └── projects/
│           ├── [id]/
│           │   └── edit.tsx
│           ├── [id].tsx
│           ├── index.tsx
│           └── new.tsx
├── db/
│   ├── index.ts
│   ├── schema.prisma
│   └── seeds.ts
├── integrations/
│   └── sentry.ts
├── public/
│   ├── favicon.ico*
│   └── logo.png
├── test/
│   ├── setup.ts
│   └── utils.tsx
├── README.md
├── next.config.js
├── vitest.config.ts
├── package.json
├── tsconfig.json
├── types.ts
└── yarn.lock

`src`

Contains all your core application code.

The file structure nested inside src/ can be anything you want, but we recommend the following:
- First layer folders to be a "domain context", like core/, projects/, users/, billing/, etc.
- All other folders like components/ and hooks/ go inside one of the above domain context folders
queries/ and mutations/ are for your Blitz queries and mutations. Each query and mutation is exposed at a URL corresponding to its file path.
blitz-client.ts and blitz-server.ts contain Blitz Toolkit setup.
pages has the same semantics as the Next.js pages folder. All files in here are mapped to the url corresponding to their file paths.

`db`

Contains database configuration, schema, and migration files. db/index.js exports your initialized database client so you can use it anywhere in your app.

`integrations`

Contains third-party integration code. Ex: auth0.js, twilio.js, etc. These files are a good place to instantiate a client with shared configuration.

`api`

Any file inside the folder src/pages/api is mapped to /api/* and will be treated as an API endpoint instead of a page. They are server-side only bundles and won't increase your client-side bundle size.

`public`

All files in here are served statically from your app's root URL

Other Notes

All top level folders are automatically aliased. So for example you can import from src/projects/queries/getProject from anywhere in our app.

Topics