File Structure

Guiding Principles

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

Example file structure

├── app/
│   ├── api/
│   │   └── stripe-webhook.js
│   ├── components/
│   │   ├── Button.js
│   │   ├── Image.js
│   │   ├── Input.js
│   │   ├── Link.js
│   │   └── Text.js
│   ├── layouts/
│   │   ├── Authenticated.js
│   │   └── Public.js
│   ├── marketing/
│   │   ├── components/
│   │   │   ├── FeatureSection.js
│   │   │   ├── Footer.js
│   │   │   ├── Header.js
│   │   │   ├── Screenshot.js
│   │   │   └── Testimonial.js
│   │   └── pages/
│   │       ├── about.js
│   │       ├── features.js
│   │       ├── index.js
│   │       └── pricing.js
│   ├── pages/
│   │   ├── dashboard.js
│   │   ├── log-in.js
│   │   ├── settings.js
│   │   └── sign-up.js
│   ├── projects/
│   │   ├── components/
│   │   │   ├── Project.js
│   │   │   ├── ProjectForm.js
│   │   │   └── Projects.js
│   │   ├── mutations/
│   │   │   ├── createProject.js
│   │   │   ├── createProject.test.js
│   │   │   ├── deleteProject.js
│   │   │   ├── deleteProject.test.js
│   │   │   ├── updateProject.js
│   │   │   └── updateProject.test.js
│   │   ├── pages/
│   │   │   └── projects/
│   │   │       ├── [id]/
│   │   │       │   └── edit.js
│   │   │       ├── [id].js
│   │   │       ├── index.js
│   │   │       └── new.js
│   │   └── queries/
│   │       ├── getProject.js
│   │       └── getProjects.js
│   ├── tasks/
│   │   ├── components/
│   │   │   ├── Task.js
│   │   │   ├── TaskForm.js
│   │   │   └── Tasks.js
│   │   ├── mutations/
│   │   │   ├── createTask.js
│   │   │   ├── deleteTask.js
│   │   │   └── updateTask.js
│   │   ├── pages/
│   │   │   └── projects/
│   │   │       └── [projectId]/
│   │   │           └── tasks/
│   │   │               ├── [id]/
│   │   │               │   └── edit.js
│   │   │               ├── [id].js
│   │   │               ├── index.js
│   │   │               └── new.js
│   │   └── queries/
│   │       ├── getTask.js
│   │       └── getTasks.js
│   └── tests/
│       ├── userAuthentication.js
│       └── userOnboarding.js
├── db/
│   ├── index.js
│   ├── migrations/
│   └── schema.prisma
├── integrations/
├── public/
│   └── favicon.ico
├── utils/
└── blitz.config.js

app

Contains all your core application code.

• The file structure nested inside app can be anything you want, but we recommend the following:
• Typically you will have two types of "container" directories inside app that can be nested or combined any way you want:
  • entity directories like projects/ and tasks/
  • context directories like marketing/ or admin/.
• Special Folder Names
  • Can exist at any level of the hierarchy inside app.
  • pages/ expose a React component at a URL. Follows the same semantics as the Next.js pages/ directory.
  • api/ expose a Node.js request handler at URL. Same semantics as Next.js pages/api/ directory.
  • queries/ and mutations/ are for your Blitz queries and mutations. Each query and mutation is exposed at a URL corresponding to its file path.

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.

pages

The top level

pages folder and all nested pages folders inside app are merged together at build time. The build will fail if the same route is defined in two places.

• This top level pages directory is optional.
• Has the same semantics as the Next.js pages folder. All files in here are mapped to the url corresponding to their file paths.
• While you can place any route files here, we recommend placing route files inside app. But if you want, you can instead place all your route files in this top level folders instead of being spread out in various directories inside app

api

Same as Next.js

pages/api folder, but not nested inside pages.

And like the

pages directory, the top level api folder and all nested api folders inside app are merged together at build time.

public

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

utils

Contains all those pesky little files and functions every project accumulates

blitz.config.js

A configuration file with the same format as

next.config.js

Other Notes

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