[RFC] New Blitz Toolkit Standalone Zero API Data Layer

[flybayer]

This is an RFC to discuss the specifics of how the zero API data layer will look and work in the new Blitz toolkit.

Prerequisite: Read [RFC] Important Discussion On Possible Blitz Pivot

Fundamental Design Principles

In the current Blitz framework, there are a ton of small design decisions that together add up to a really special DX that so many avid Blitz users rave about. Many of which are not readily apparent to onlookers or casual users. These have all been battled tested in thousands of production applications, and have proven to significantly increase product shipping velocity, have proven to be scalable to large applications, and have changed the game for hiring. No longer do you have to struggle to hire backend engineers capable of building and maintaining production GraphQL setups. Instead you can hire frontend engineers who can now ship backend code because the Blitz design decisions are intuitive to them and easy to use.

With the battle testing, we also now know which decisions weren't great. But the awesome thing is that almost 100% of the things we should change are internal implementations, not developer facing APIs. In most cases, they were implementations that made it difficult to add features y'all have requested. So this is a chance to fix all that and enable us to ship better, more powerful features.

With that said, the most important principle is to preserve the APIs and DX of current Blitz as much as possible. However, this pivot does present an opportunity to tweak some things if there is sufficient desire from Blitz users to do so.

Preserving the APIs also greatly aids the migration path from current blitz to new blitz toolkit, which is a hugely important to make easy.

New Goals

• Standalone library without dependencies on rest of Blitz ecosystem
• Runtime agnostic. Should run in Deno, cloudflare workers, etc.
• Framework agnostic.
• Use HTTP GET for queries by default, which enables easy caching
• Use ETAG for queries to leverage browser APIs improve performance
• Support defining multiple resolvers in a single file
• Be able to throw extra things like Redirects — especially useful in context of Remix.

Implementation

Code

Because current Blitz zero-api is enabled through babel plugins and nextjs compiler, there's not much code we can extract and re-use. So we mostly need an entirely new implementation.

Design

1. Query/Mutation resolver API would stay exactly the same. ((input, ctx) => output)
2. Queries/Mutations folders are no longer magic, so you import into a server setup file
   • This means you can define multiple resolvers in a file and export as named functions
3. Instead of importing resolvers into the components for useQuery, you will specify the name of the query/mutation

Query/Mutation File

// app/projects/queries/getProject.ts  — BUT file named and path is no longer magical, so can be different.
import {resolver, NotFoundError} from "blitz"
import db from "db"
import {z} from "zod"

const GetProject = z.object({
  id: z.number()
})

// Default export is no longer magical, so you can use named exports and multiple exports from a file
export default resolver.pipe(
  resolver.zod(GetProject), 
  resolver.authorize(), 
  async ({id}) => {
    const project = await db.project.findFirst({where: {id}})
    if (!project) throw new NotFoundError()
    return project
  }
)

Add server setup file

// blitz.server.ts — location and name can be anything, but you'll import key APIs from this file
import { setupServer, sessionMiddleware } from "@blitzjs/next"

// queries/mutations folders are no longer "magic".
// You know have to explicitly import into this setup file
import createProject from "app/projects/mutations/createProject"
import updateProject from "app/projects/mutations/updateProject"
// You can now have multiple resolvers in a single file
import * as projectQueries from "app/projects/queries"

// api, gSSP, gSP will be used to wrap everything for auth and middleware
export const { api, gSSP, gSP, Server } = setupServer({
  middleware: [sessionMiddleware],

  queries: {
    ...projectQueries,
  },
  mutations: {
    createProject,
    updateProject,
    deleteProject,
  },
})

export type Server = typeof Server

Then expose your server in an API route

// pages/api/blitz/[...blitz].ts
export { Server as default } from "blitz.server";

Add client setup file

// blitz.client.ts — location and name can be anything, but you'll import key APIs from this file
import { setupClient, clientSessionMiddleware } from "@blitzjs/next";
import type { Server } from "./blitz.server";

export const {
  useQuery,
  useQueries,
  useInfiniteQuery,
  useMutation,
  queryClient,
  BlitzProvider,
} = setupClient<Server>({
  middleware: [clientSessionMiddleware],
})

Then import from client setup file to use queries/mutations

// some component or page
import {useQuery, useMutation} from 'blitz.client'

const [project] = useQuery("getProject", { id: 1 });
const [createProjectMutation] = useMutation('createProject')

Your Feedback

Please review and provide any feedback or thoughts you have! I've posted a couple sub-topics below for more discussion regarding API and collaborating with TRPC.

[flybayer]

useQuery API

Which do you prefer? Either way we'll have a codemap that automates the migration from current Blitz.

// Option 1 (strongly typed)
const [project] = useQuery.getProject({ id: 1 });
const [createProjectMutation] = useMutation.createProject()

// OR

// Option 2 (also strongly typed)
const [project] = useQuery("getProject", { id: 1 });
const [createProjectMutation] = useMutation('createProject')

Option 2 is a little closer to the raw react-query API, but that has a slight downside of adding potential for confusion. Whereas Option 1 is very clearly an abstraction over useQuery.

[dbrxnds]

I like option 2, but I think some testing would need to be done as to what happens when you have 100's or 1000's of queries/mutations. Template literal intellisense tends to struggle in those situations.

[flybayer]

@Swapnull the planned setupClient() approach actually supports that :) Like this.

export const blitz = setupClient<Server>({
  middleware: [clientSessionMiddleware],
})

// Then use like this
const [project] = blitz.useQuery('getProject', {id: 1})
``

[jhonnymichel]

I was preferring style 1 until I read the first 2 comments, and they make sense.

useQuery("query") would still be type-safe, right? In this case, 2 is great. It's simpler to write, typescript removes the general issues of using strings as identifiers and that makes using strings (unions, really) quite charming IMO.

[KATT]

Regarding input arguments

You should take into account that one can use the react-query options as well, with or without input.

In both options 1 and 2 it's a bit odd to pass in those options when there's no input:

// Option 1 (strongly typed)
useQuery.getAllProjects(undefined, { refetchOnMount: false });

// OR

// Option 2 (also strongly typed)
useQuery("getAllProjects", undefined, { refetchOnMount: false });

I've toyed with this format in the past:

useQuery("pathName", { input: x, refetchOnMount: false  })

Side-note: in react-query (and in tRPC) we use tuples for the input argument - i.e. useQuery([path, input], reactQueryOptions).

Regarding return type

In the examples above you use [project] - I very much think you should just use what react-query gives you already to make it easier to deal with success/error/loading state, react-query will give you a discriminated union so you can do:

const result = useQuery(...)
if (result.success) {
  return <>{result.data} will be here according to passed in type</>
}
if (result.error) {
  return <>{result.error} will be there</>
}
return <>Loading...</>

[flybayer]

Regarding return type

Blitz api is const [project, rqExtras] = useQuery(getProject, {id: 1}, {refetchInterval: 1}). So we currently get all the extra stuff from RQ too.

By the way, almost all Blitz users use suspense and don't have this branching logic.

[flybayer]

Collaborating with tRPC

Alex (@KATT), the creator of tRPC made a very kind proposal to work together to bring tRPC inline with our Blitz requirements.

Fundamentally it absolutely makes sense try and join forces. tRPC was originally created so that the blitz-style zero-api layer could be used as a standalone library. And now with the new Blitz pivot, we also want our zero-api data layer to be a standalone library. So if we don't join somehow, then users will have to choose and compare between them.

Here's the main differences I think we need to resolve.

Overall API simplification from what trpc currently has to what I have above

Alex already mentioned to me that he's very keen on simplifying the API. Aside from client and server differences, currently tRPC on the client as various config options in different places (createTRPCClient has options and withTRPC has other options). It would be ideal of all of these options are combined into a single setupClient() function that returns a configured withTRPC.

Keep our existing resolver api: (input, ctx) => output

This is one of those subtle design decisions that makes Blitz really special. With this API, resolvers are vanilla functions. There's no factory function you have to use like query() or mutation(). And so resolvers are simple to understand, highly composable, and easy to test.

It's also a big DX win that whatever you return from the function is exactly what you get on the client. There's no special object format you must return (instead of return {data: stuff, ctx} it's return stuff).

This is a case where the return {data, ctx} totally makes sense and seems like a more flexible, robust long term decision (in probably the majority of programming it would be the right choice!). However it does degrade the DX in this context. In the 10 months of battle testing the current blitz api has had, there have been zero reasons or issues with the return data api. So I feel pretty strongly about this. (Blitz users please chime in if you feel otherwise!)

No separate input validation function

This is a sub-part of the previous point. To be honest, I really like the idea of enforcing input validation. It's certainly a boon for security. When I was crafting the current Blitz API, I kept trying to add a separate input validation function like trpc has, but ultimately I couldn't get a chef's kiss out it.

I think the main concrete example I can use on why I don't like a separate input validation function is the following:

This is is my most used resolver.pipe setup in my blitz apps:

export const getProject = resolver.pipe(
  resolver.zod(GetProject),
  resolver.authorize(),
  setDefaultOrganizationId,
  enforceSuperAdminIfNotCurrentOrganization,
  async ({ id, organizationId }) => {
    const project = await db.project.findFirst({
      where: { id, organizationId },
    });
    if (!project) throw new NotFoundError();
    return project;
  }
);

The setDefaultOrganizationId is essentially a second input validation function. It reads input and ctx. And if input.organizationId does not exist, it sets it from ctx.session.orgId. And in the process, it modifies the type of input to add organizationId. This is something I think you can't do with the current trpc API.

That said, enforcing input validation is an excellent idea. Can we do this even with the .pipe API? I'm pretty sure we can. Inside the implementation of resolver.pipe, we can track some metadata. resolver.zod would signal to .pipe that input has been validated. At the end of the .pipe chain, if we see nothing has signaled input validation, then we throw an error. We can document the API so custom validation functions can use it too.

Keep Blitz ctx Typing

The user defines the base Ctx type globally somewhere in their code. (pipe functions can still modify ctx type with this setup). This is requirement to avoid query() and mutation() factory functions.

// types.ts
import type { DefaultCtx, SessionContext } from "blitz"

declare module "blitz" {
  export interface Ctx extends DefaultCtx {
    session: SessionContext
  }
}

Keep existing Blitz error handling

Once again this is something very special about Blitz. You can throw an error on the server and catch the error in a React ErrorBoundary. I don't fully understand the tRPC error handing, so not sure if this is currently possible or not.

There are a few rough edges with the current Blitz implementation that should be smoothed out. (Blitz users, if you have any specific cases of bad DX/problems on this, please share!)

Blitz middleware

We need both client middleware and server middleware. We will run server middleware everywhere including getServerSideProps, regular API routes, etc.

Our current API is (req, res, next) => ?, but I think your tRPC middleware API is better. I originally used our current API because it matches Koa's API. But adapters can easily resolve differences.

Middleware needs access to req and res (I can't tell if tRPC supports this already).

I still need to investigate if/how this should leverage the new Nextjs middleware feature.

Blitz needs it's own "user entrypoints"

In order to support our new modular system, we need to own our createServer() and createClient() APIs. I don't think this directly affects tRPC, but I think it's important to mention nevertheless.

Timing

Alex you mentioned you are offline middle of next week until the 10th of January. That's not ideal because we are wanting to move very fast and ship the new basic toolkit mid-late January. So I guess let's iron out as much as we can until you go offline.

[darioielardi]

First of all, let me say that I'm a huge fan of both Blitz and tRPC and I've always wanted to see a combined effort from the two projects. I love the idea of a framework agnostic Blitz Toolkit and a tRPC-powered api layer would make it perfect IMHO.

Honestly, no matter what the implementation differences are gonna be, I'll be very willing to refactor all my tRPC projects and start every new one with the Blitz Toolkit.

But since I'm here, this is my take on the points above.

Global vs factory created context

The most important thing to me here is to achieve context type narrowing per-procedure, based on authentication and other things, which I see is achievable with both the implementations.

I'm usually against global module augmentation, because for example it's inconvenient in an Nx monorepo setup.

Also, I think a context factory function works a bit better for dependency injection. I definitely prefer to have my prisma client/services/user-specific dependencies injected in the context for every request and access them from the ctx object rather than absolute import stuff from around the project. That said, as pointed out before, this can also be achieved with the resolver.pipe api, and even if it's a bit more verbose it wouldn't be a real problem.

Resolver pipe vs procedure factory

I really can't see any big difference here. Both achieve everything we need, as both act as wrappers to provide input validation and context type info. I probably like more the resolver.pipe api visually speaking but that's really not a strong argument.
The only thing I definitely have a preference for, is the ({ input, ctx }) => {...} resolver api, for the reasons @KATT already mentioned.

Let me know if there's anything else I can do to help all of this to become reality!

[mgreenw]

I am a contributor to and user of tRPC and I have loved using it and being part of the community! +1 to everything people have said above: I think Blitz and tRPC would be a great match as I think they are solving the same problem with a very similar technical solution. I think merging the communities would be awesome so more people can benefit from the best parts of these awesome projects.

@KATT I probably seem like an insensitive jerk for saying this, but let's come up with a planned solution before you go offline. The implementation can wait, but we need the design nailed down so we move forward with all our other work. Otherwise we'll lose just under 3 important weeks of progress. Worst case we'd go ahead and start on new library.

@flybayer I really admire your enthusiasm to start work, but this needs to be done slowly, deliberately, and correctly for both communities. I really don’t think it’s realistic or a good idea to finalize API design before xmas / new years, especially when so many community members are on vacation or otherwise away from technology during this period (I am currently on vacation). I just really want to avoid a Python 2 -> 3 -like transition (obviously a different scale but the analogy applies), which would be the worst case for everyone.

Technical Comments

When I do this new major, I'm gonna have to force my users to do helluva refactoring.

I am less excited about this than @darioielardi — I think tRPC has a pretty great API, and while I think it makes sense to improve it to support blitz with new features + overall API simplification, I would prefer to avoid a huge refactoring if possible unless there are compelling technical improvement reasons to do so. This is similar to @paulm17’s thoughts but from the tRPC side 😅

Specifically, the idea of a flat router as @KATT mentioned above probably makes sense to avoid some of the “big router” problems that we have seen with tRPC. That being said, it is really nice from a DX perspective to not have to touch multiple files to add one query / mutation, so any solution that reduces imports / exports while maintaining the middleware & context approach would be ideal.

I don’t have a strong preference for the pipe vs input api, though the input/resolve api has been working really well for me. I would love to see some more thoughts on why pipe is better than input/resolve, otherwise I don’t see a compelling reason to use pipe. For beginners, I think the input/resolve is really simple, and continues to be clear as an app grows while allowing every technical use case.

+1 on ({ ctx, input }) -- positional params are bad for DX and stymie future options that could be added.

I definitely have more comments but need to sign off (I haven’t had time to read all the other comments) — I’m looking forward to see where this goes in 2022 and hope that the process can slow down enough for everyone to have input and so this can be the best possible path for both communities.

[darioielardi]

I just want to point out that I'm very willing to refactor my tRPC powered projects not only because I'm excited about this, but also because I think revisiting the tRPC api design is the only way to fix the performance issues we have with big routers.

[KATT]

To expand on the performance issues with big routers in tRPC:

• It makes the feedback loop sluggish once you have a lot of procedures
  • At ~70 procedures it takes a few seconds on my machine to get an update of a change of an input/output param
• The bottleneck for this, I believe, is that because of the recursive nature of the .merge() the current design. I need to properly test this with the new API design ideas to see make sure we get a better outcome.
• It's nothing that affects runtime, it only affects the developer experience

[dineshgadge]

I haven't gone through tRPC internals, but can an adapter be created which responds to the blitz way of accessing things but uses tRPC under the hood?

[paulm17]

Question regarding query and mutation imports.

Do I have to explicitly input each query/mutation as an import in the server file?

What does one do when they are going to have > 100+ files of these types strewn about within their application? And in multiple directory depths. 👀

[flybayer]

Do I have to explicitly input each query/mutation as an import in the server file?

Yes. Unfortunately this is the tradeoff of going with a compilerless approach. Potentially Next will add SWC plugin support, at which time we might could bring back the current magical import experience, but I don't think we can count on this.

For migration, our codemod will make all those imports for you.

For normal development flow, our cli blitz generate query would generate both the file, and add the import.

[JohannesKlauss]

Would this allow for the possible creation of a rpc sdk generation tool, so that one can create a SDK library to use for a react-native app calling the same service for example?

[flybayer]

@JohannesKlauss yes, but it doesn't even need code generation! Your mobile app will just have the same client setup file as the web app.

export const {
  useQuery,
  useQueries,
  useInfiniteQuery,
  useMutation,
  queryClient,
  BlitzProvider,
} = setupClient<Server>({
  middleware: [clientSessionMiddleware],
  url: 'path-to-your-blitz-app'
})

[jpmelnik]

I'm just starting to develop a production ready app with the Amazing Blitz. What's is your recommendation: Continue or just move to Nextjs? How much time does you need to develop the Toolkit? Thanks.

[flybayer]

Continue! We have to automate the migration as much as possible for all the existing users, so you'll benefit from that too.

[flybayer]

Update Dec 23

We are strongly considering keeping the current magical import for queries and mutations (where you import the query/mutation directly into your components). In which case you would not have to import every query and mutation into a single setup file. We can do this with a custom webpack loader instead of babel, so it won't interfere with the Next.js swc compiler. The underlying implementation difference is that currently each resolver is a separate nextjs api route, but the new way would consolidate all into a single nextjs api route.

The new way would work out of the box with Vite. And we would ship react-native support at the start too.

We would also support a "non magical" way like described in this RFC for alternative uses.

As for the tRPC collaboration, Alex and I have had some extensive discussions. As of now it looks like we'll probably use the tRPC core backbone for the network layer, but have our own "developer interface". This will allow us to have the stylistic differences we both care about while not duplicating efforts on the network backbone which is where a lot of the hard work is, especially for things like websockets.

[paulm17]

We are strongly considering keeping the current magical import for queries and mutations (where you import the query/mutation directly into your components). In which case you would not have to import every query and mutation into a single setup file.

This is awesome. It's a win for DX, as the simpler you can make it. The quicker adoption you'll see. It's one of the reasons why I really appreciate BlitzJS. I don't have to work about it.

This will allow us to have the stylistic differences we both care about while not duplicating efforts on the network backbone which is where a lot of the hard work is

For those on the sidelines worrying, this is really good news. Can't wait to see what developments there are by the end of Jan.

The new way would work out of the box with Vite

So as someone who tries not to keep up with everything (don't want fatigue). How would Vite fit in with webpack, swc, rust, etc? Or is this a possible https://vite-plugin-ssr.com/ integration for other frameworks?

[flybayer]

The way I understand it, vite is built on esbuild. I had a long conversation with @brillout, author of vite-plugin-ssr. He's a great guy and very keen to collaborate and even help build out the new features we want to build.

[dineshgadge]

This update is music to my ears!

[fungilation]

Wow, did I hear websockets? For new projects that requires realtime pushed UI updates, I'm looking towards things like Hasura, Supabase and Dgraph instead for realtime subscriptions. Having this in future standalone Blitz is a key feature add to me 👏🏼 and a game changer for real time apps, which currently cannot use Blitz with Prisma (not exclusively anyways)

[paulm17]

Wow, did I hear websockets? For new projects that requires realtime pushed UI updates, I'm looking towards things like Hasura, Supbase and Dgraph instead for realtime subscriptions. Having this in future standalone Blitz is a key feature add to me 👏🏼

You can use websockets today using centrifugo or feathersjs. That said, it will only give you real-time comms and it's a bit of work to get working. If Brandon releases something more akin to those you mentioned, where actual queries to the database are updated in real-time whenever an event happens. That would be a game changer in relation to something like Prisma. More over, I think with Relay there is a Recoil-Relay implementation that gives real-time to stores as well. This too is interesting in an of itself.

I know Brandon has 👀 something over at Redwood with respect to their new ORM implementation. I'm kinda meh about the whole thing, but if the wrapper includes realtime. Yes, then the work is worth it. Not sure what @flybayer is thinking though.

[eric-burel]

Hi guys, now you are pivoting toward a reusable toolkit, I'll try to share a bit more about what we have been done in our own framework, Vulcan, because we have many problems in common and also tried to have a framework agnostic approach.

At Vulcan we have this kind of setup, for GraphQL:

• vulcan-model/vulcan-schema proposes a schema-based approach: you declare your data structure in JS basically
• vulcan-crud defines basic CRUD operations and a mini-ORM interface to the database (I am introducing this package in order to support also REST and sockets in the future, though atm we use on graphql)
• vulcan-mongo provides an implementation of the ORM for Mongo
• vulcan-graphql generates CRUD resolvers and mutations from a data schema, written in a simpl-schema like syntax. It also exposes the raw graphql query definitions for client/server.
• You can pass Mongo-like selectors, so that data is filterable/sortable easily. The
• vulcan-react-hooks exposes useMulti, useSingle, useCreate, useUpdate and useDelete hooks. You pass them a model and they translate it into the right query automatically: useSingle({model: Authors}) for instance.
• In the future, we'll improve them a bit to make them closure: useProjects = makeUseMulti<Project>(), so that the hooks have better names + typings

Packages can be found here: https://github.com/VulcanJS/vulcan-npm

So basically we have been having the same objectives, differences lies there:

• we use GraphQL, so that the API layer is agnostic to our framework
• we don't support custom mutations and custom resolvers with this system, only CRUD. We used to have a custom mutation system in Meteor, so that's doable, but never tried to type it
• we expect user to use normal Apollo GraphQL resolvers and mutations for custom behaviour, nowadays it's possible to set it up in order to have typings and stuff, eventhough it may be a tad difficult
• there is zero magic, no Webpack stuff, no Babel etc. I want to keep it as easy to maintain as possible, and leave "magic" at the framework level. We know how difficult those feature can be to maintain, because of the total instability of the ecosystem of build tools. They could also lock-out of modern dev tooling, like Meteor have never been able to work with Storybook or Jest due to its build system, despite it being technically superior to Webpack.

[fleck]

We can do this with a custom webpack loader instead of babel, so it won't interfere with the Next.js swc compiler.

Are there any worries about Next.js or the JS ecosystem in general potentially moving away from webpack? Would it make sense to first ship a "no magic" API and then later ship a compiler assisted API?

[flybayer]

Yeah, our foundation will be "no magic". The magic will be a layer on top, and perhaps optional.

[sunw31]

Above first, thanks for your hard work!
May i ask a question?which is the future of blitzjs?

1.nextjs + blitz-toolkit + nestjs
2.nestjs + blitz-toolkit
3.nextjs + blitz-toolkit

Personally I want to choose 1.

[paulm17]

I think it's going to be 3. If you look at the URL at the very top. It goes into NestJS territory, so I think the reasonable idea is to phase out the requirement of it over time. There's already a server with blitz, so why not use it?