Keystone: The what and why of wrapping a NextJS client with `@keystone-alpha/app-next`.

[thiagodebastos]

The Custom Server section of the KS5 docs mention @keystone-alpha/app-next for serving a Next.js App on the same server as the API.

What attracted me to this was simplifying my app by maintaining a single NodeJS server.

• Why else would I want to do this?
• What would I gain or lose from doing this?

I’m happy to be pointed to any insightful resources.

I tried digging around the source code and found that app-next provides a wrapper for Keystone app.

[jesstelford]

Great question!

The entire app-* ecosystem within KeystoneJS is based around the idea of deploying everything to a single server.

This is by far not the only way to deploy things, and so comes with some trade-offs:

Pros

• Very simple getting started - setup the app and everything will "Just work"
• Is opt-in with low barrier to entry
• Provides extension points for adding different kinds of apps in the future

Cons

• Your frontend (next.js) and API (Keystone) cannot scale independently
• Depending on the app, your frontend and api code will be executed within the same node.js thread. Ie; server-side rendering in the next.js app will block API requests.
• While it's technically possible to deploy to a serverless environment like this, it's not trivial and reaps almost none of the rewards of serverless
• Side-steps optimisations you may want to take advantage of. ie; in the app-static app, there's no way to deploy your static assets to a globally cached CDN.

You should only use apps (other than the graphql app) when you're comfortable with the above trade-offs. If you grow beyond that, you can eject out of the app ecosystem and setup your own hosting and deployment pipeline to reap the benefits you desire.

[thiagodebastos]

Thank you @jesstelford this is exactly what I was looking for. The standout for me was:

Your frontend (next.js) and API (Keystone) cannot scale independently

Combine that with SSR blocking API requests and you have a recipe for disaster 💸 !

[lucatk]

Hello.
I am just (thinking about) getting started with KeystoneJS and integrating it with my project (which, for now, only consists of a pure NextJS app).
@jesstelford The reasons you gave (especially the cons) makes the all-in-one server approach disqualified for my use case, hence I went to have a look into the custom server docs.
However, how is the approach described in the Custom Server docs different to the approach of using the built-in NextJS Keystone app?
As far as I understand it, even with the Custom Server both Keystone and the NextJS app would still run in the same thread, wouldn't they?

[jesstelford]

Yes you're right - they'd still be within the same node process. The next-app is just a thin wrapper over doing a custom server.

It sounds like you want to keep your Next & Keystone apps running independently; they'd have their own "start" commands, be deployed separately, have their own logging and monitoring, etc.

For example, you might deploy your Keystone app to https://api.example.com, then in your Next app set up the GraphQL client to have uri: "https://api.example.com", and be deployed to https://www.example.com

[develerltd]

You can also use something like nginx infront of both node instances to proxy the /graphql endpoint to the keystone server, while serving up static content and the rest from the nextjs app.