Blitz.js Documentation

Blitz.js is a fullstack framework designed for building database-backed applications ranging from tiny to large scale. It is intended for applications that require one or more graphical user interfaces, such as web or mobile apps.

Key characteristics include:

• Fullstack & Monolithic: Blitz treats the application as a single entity, simplifying reasoning about the app compared to separate frontend/backend deployments. It maintains separation of concerns while providing a unified development experience.
• Convention over Configuration: Blitz provides a pre-configured environment (including ESLint, Prettier, TypeScript, routing, and database setup) to allow developers to start building features immediately. Configuration is optional, and 'escape hatches' are provided for bespoke customization.
• Loose Opinions: While Blitz provides a guided path through conventions, it does not strictly enforce them, allowing developers to deviate from the standard file structure or patterns when necessary.

To implement multitenancy, use a single database where every tenant-specific model includes an organizationId to ensure data isolation.

Key components of the recommended model:

• Organization: The top-level entity that owns all data for an account.
• Membership: A join table that connects Users to Organizations, allowing a user to belong to multiple organizations. It should store the user's role within that specific organization.
• User: Represents the individual, which can have a GlobalRole (e.g., SUPERADMIN for platform owners or CUSTOMER).
• Ownership: When assigning entities (like tasks) to users, assign them to the user's Membership rather than the User directly to maintain the organization context.

model Organization {
  id         Int @id @default(autoincrement())
  name       String
  membership Membership[]
}

model Membership {
  id             Int @id @default(autoincrement())
  role           MembershipRole
  organization   Organization @relation(fields: [organizationId], references: [id])
  organizationId Int
  user           User? @relation(fields: [userId], references: [id])
  userId         Int?
  invitedName    String?
  invitedEmail   String?

  @@unique([organizationId, invitedEmail])
}

enum MembershipRole {
  OWNER
  ADMIN
  USER
}

enum GlobalRole {
  SUPERADMIN
  CUSTOMER
}

model User {
  id             Int      @id @default(autoincrement())
  email          String   @unique
  role           GlobalRole
  memberships    Membership[]
}

The resolver.pipe utility is a functional pipe that allows you to compose complex resolvers by passing the output of one function as the input to the next. This approach reduces the need for explicit TypeScript types and enables clean, one-line composition of validation, authorization, and business logic.

Key behaviors:

• Type Inference: TypeScript types are automatically inferred from one function to the next.
• Input Type Determination: The input type of the entire composed resolver is determined by the input type of the first argument in the pipe. Therefore, you should almost always place resolver.zod() as the first argument.
• Function Signature: Each function in the pipe accepts the data from the previous step as the first argument and the middleware ctx as the second argument.
• Final Result: The output of the last function in the pipe becomes the final resolver result sent to the client.

import { resolver } from "@blitzjs/rpc"
import db from "db"
import * as z from "zod"

export const CreateProject = z.object({
  name: z.string(),
  dueDate: z.date().optional(),
  orgId: z.number().optional(),
})

export default resolver.pipe(
  resolver.zod(CreateProject),
  resolver.authorize(),
  // Set default orgId
  (input, { session }) => ({
    ...input,
    orgId: input.orgId ?? session.orgId,
  }),
  async (input, ctx) => {
    const project = await db.project.create({
      data: input,
    })
    return project
  }
)

After a mutation succeeds, you often need to update the UI to reflect the new data. Blitz provides several ways to manage the cache:

1. setQueryData: Available from the useQuery hook. Use this to manually update the cache with new data. By default, calling this triggers a refetch to ensure synchronization. You can prevent this by passing { refetch: false } as the second argument.
2. refetch: Available from the useQuery hook. Use this to manually trigger a reload of the query data.
3. invalidateQuery: Imported from @blitzjs/rpc. This allows you to invalidate a specific query (by passing its resolver function) from anywhere in your application, even in components that do not own the query.

// Using setQueryData from useQuery
const [product, { setQueryData }] = useQuery(getProduct, { where: { id: 1 } })
// ... inside onSubmit
const product = await updateProductMutation(values)
setQueryData(product)

// Using invalidateQuery from @blitzjs/rpc
import { invalidateQuery } from "@blitzjs/rpc"
import getProducts from "app/products/queries/getProducts"

// Trigger invalidation
invalidateQuery(getProducts)