English for Blitz.js Developers

Blitz.js conversations tend to focus on defending its “zero-API” model, where frontend code calls backend functions directly without hand-written REST or GraphQL endpoints, so the vocabulary covers queries, mutations, and how the framework hides the network boundary.

Key Vocabulary

Zero-API layer — Blitz.js’s approach of letting React components import and call backend functions directly, with the framework transparently turning those calls into network requests behind the scenes. “With the zero-API layer, you’re not maintaining a separate REST endpoint for every mutation — the component just imports the function and calls it like it’s local.”

Query resolver — a Blitz.js backend function, colocated with the pages that use it, responsible for fetching and returning data, automatically wired into React Query on the frontend. “This query resolver already handles caching through React Query — you don’t need to add your own fetch-and-cache logic in the component.”

Mutation resolver — a Blitz.js backend function that performs a write operation (create, update, delete) and can be invoked directly from a client component with automatic loading and error states. “Wrap the button handler around this mutation resolver — Blitz gives you the pending state for free, so you don’t need your own isSubmitting flag.”

Colocation — Blitz.js’s convention of placing backend resolver files inside the same feature folder as the frontend pages that consume them, rather than splitting frontend and backend into separate top-level directories. “Because of colocation, the resolver for this page lives right next to it in the same folder — you don’t have to go hunting through a separate api/ tree.”

Authorization middleware (resolver pipe) — a chain of functions wrapped around a query or mutation resolver to handle authentication and authorization checks before the resolver’s core logic runs. “Add the session guard to the resolver pipe instead of checking permissions manually inside the function — that way every consumer of this resolver gets the same enforcement.”

Common Phrases

• “Does this need a full REST endpoint, or can it just be a query resolver called directly from the component?”
• “Is this mutation resolver handling its own error state, or do we need to catch that in the calling component?”
• “Should this resolver live here because of colocation, or does it actually belong in a shared folder?”
• “Is the authorization check happening in the resolver pipe, or did someone put it inside the function body by mistake?”

Example Sentences

Explaining the framework’s philosophy to a new developer: “Blitz’s zero-API layer means you never write a fetch call for this — you literally import the resolver function and call it, and Blitz handles the network request under the hood.”

Reviewing file structure: “Because of colocation, this resolver should be moved next to the page that uses it, not left in a generic backend folder.”

Explaining security review comments: “Put the ownership check into the resolver pipe rather than the top of the function — that way it’s applied consistently and easier to audit.”

Professional Tips

• Use zero-API layer to explain why there’s no visible REST or GraphQL contract in the codebase — it prevents confused searches for endpoint definitions.
• Distinguish query resolver and mutation resolver precisely in review comments, since they have different caching and invalidation behavior in React Query.
• Reference colocation when explaining folder structure to developers used to a strict frontend/backend split — it changes where they should expect to find things.
• Recommend centralizing checks in the resolver pipe during security review, since scattered manual permission checks are harder to audit consistently.

Practice Exercise

1. Explain what the zero-API layer means and how it changes the way a component calls backend logic.
2. Describe the difference between a query resolver and a mutation resolver in terms of what each is used for.
3. Write a review comment asking a teammate to move an authorization check into the resolver pipe.

Navigating Feedback & Collaboration

Let’s be honest – code reviews aren’t always sunshine and rainbows. They can feel critical, even if that’s not the intention. As a Blitz.js developer, particularly when working with a global team, clear and constructive communication is absolutely vital. The goal isn’t to tear down your work but to help you build something better – faster. Think of it less as a judgment and more as a collaborative exploration.

One common area for friction arises when explaining the ‘zero-API’ philosophy. Developers unfamiliar with this approach might ask, “Why aren’t we using a traditional API?” A good response goes beyond simply stating the benefit; it frames the discussion around shared understanding. Instead of a defensive explanation, try something like: “I’ve designed this resolver to directly access the data layer, minimizing external dependencies and reducing potential points of failure – think of it as streamlining our flow and simplifying debugging. We can discuss how that impacts your component’s setup if you’d like to explore alternative approaches.” This approach acknowledges their perspective while gently guiding them towards the core principles. Similarly, when discussing changes in a Pull Request description, avoid jargon like “optimizing resolvers” – instead, be explicit: “Refactored resolver X to improve data retrieval performance and reduce latency by utilizing batch operations. This change aligns with our zero-API strategy by minimizing direct database interactions.”

Another key phrase you’ll hear is ‘resolvers’. While the term itself might seem abstract, it’s crucial to explain their role in a Blitz.js context – they act as intermediaries between your React components and the underlying data layer. When explaining this to someone unfamiliar with the framework, consider phrasing like: “Resolvers are essentially functions that fetch data from our data layer based on the component’s request. They’re the crucial link ensuring we’re only pulling what’s needed, when it’s needed, which is key to maintaining a performant and scalable application.” Crucially, remember to always relate this back to the broader picture – how does this impact the overall architecture?

Finally, don’t shy away from asking clarifying questions. If someone isn’t understanding a particular concept, politely probe: “Could you walk me through your thinking on this?” or “Can you help me understand what concerns you might have about this approach?”. Genuine curiosity and a willingness to collaborate are far more effective than simply correcting someone’s misunderstanding.

// Example Blitz.js Resolver (Illustrative) - demonstrating data layer access
// This is NOT a fully functional resolver but demonstrates the concept
const fetchData = async (query) => {
  try {
    const result = await blitz.data.resolvers.user.get({ id: query }); // Accessing a data layer resolver
    return result;
  } catch (error) {
    console.error("Error fetching user:", error);
    throw new Error("Failed to fetch user data");
  }
};