Catalyst Update | 8/1/2024

There are some big & exciting changes coming to Catalyst, and I wanted to give everyone an early preview of the scope of the changes, why we’re making them, and what value you’ll get out of the other side.

We will be doing independent GH releases for all of these to make it easy to track the changesets and make upgrading/rebasing a little bit easier.

👋 Elimination of OAuth Token/Admin API dependency

Since the beginning of Catalyst, our goal has been to have the storefront powered 100% by our GraphQL API, and not “cheating” by relying on our Admin APIs. This ensures you only have to use one type of API, you don’t have any awkward “REST vs GraphQL” complexity in your application, and it ensures that we have a complete GraphQL Storefront API for everyone, even folks who aren’t using Catalyst.

We have one remaining feature which requires an Admin API call, which is the shipping country dropdown on the cart estimator on the cart page, which requires the use of our V2 Shipping APIs to determine which countries are enabled for shipping.

We will be adjusting this feature to work without an OAuth token, in which case it will gracefully degrade to returning a list of all shipping countries if you do not have an OAuth token specified in your environment; this is a temporary state until we can finish bringing this functionality 100% into GraphQL, at which point we will make it work as expected entirely with GraphQL.

Our reason for doing this is that having a token with Admin API permissions embedded in Catalyst is not a security best practice, and it makes the app harder to automate in terms of deployments (exciting things coming here!). To be clear, it’s totally okay if you choose to use Admin APIs within your Catalyst installation if you have a good reason, but it’s important to us that the out-of-the-box storefront does not require any Admin APIs.

This change is not breaking and does not require any action on your part, but future installations of Catalyst created via our CLI will not include an Admin API token by default. If you wish to use one, you can always generate one in our control panel with the appropriate scopes.

🧩 Refactoring of UI Components to work better with Makeswift and other visual editors

We’ve partnered closely with the Makeswift team to make sure our UI components are going to map nicely to visual editing use cases and be easy to extend in that context. The result of this discussion is a significant refactor of our UI components to “flatten” the props, stabilize the prop APIs, and make it easy to reason about the relationship between a UI component and a visual editing interface.

The benefit of this change for you is that your storefront will be compatible with visual editing via Makeswift, and in the future will be theme-able with Makeswift’s upcoming Vibes product which will allow you to install different versions of these components that are beautiful & ready to use to build real websites. Not only will these components look great out-of-the-box, they’ll also be even easier to style to match your brand than ever before.

This change has already been merged, and you can read more about it here.

🔐 Update to GraphQL Authentication which solves checkout issues & improves security

We have created a new form of authentication for our GraphQL Storefront API which improves our security posture and solves session synchronization issues with headless checkouts.

Our new Customer Access Token for GraphQL is documented here

Once we’ve pulled this into Catalyst, you will need to do a one-time regeneration of your GraphQL token as part of the upgrade.

The benefit you’ll get is an improved security posture, and a better-hosted checkout experience including:

• Logged-in customers maintaining their login state through to checkout (without having to use Customer Login API)
• A synchronized session between storefront & checkout; logging out in one place will log you out in both places
• Support for more security-sensitive features we will add to Catalyst in the future, such as Saved Payment Methods

📈 Refactoring middleware to improve performance and eliminate KV dependency

This one is a little bit earlier in development, and we’re not 100% sure we’ll be able to pull it off yet, but I wanted to give an early preview regardless.

One of the nice features of Catalyst compared to normal Next.js apps is that we have support for completely arbitrary URLs, which maps nicely to how a lot of BC merchants have set up their stores; you can put any entity (e.g. a product) on any URL, and have any URL structure you like without being limited by Next.js’ path-based routing.

The tradeoff is twofold - developer experience, since we do things a little bit magically compared to normal Next.js, and performance, because we use Next.js middleware to do this routing.

We’ve partnered closely with the team at Vercel on solutions to both of these issues, and we’re working on a solution that will move this logic from middleware into a catchall route.

The benefit should be a performance boost and an easier-to-reason-about DX for folks who are used to Next.js.

I don’t expect this to be a breaking change, you should be able to pull it straight in and immediately get the benefit of improved performance; I think this is what will get us to the very impressive fully-static performance that everyone loves about Next.js - while also removing the need to attach a KV datastore to cache URL route information, which will simplify the application and make Catalyst cheaper to operate.

⏰ Timing & what’s next

We’re doing our utmost to ship these changes as soon as we can so that these refactors can be in the rearview mirror and ensure that as many new Catalyst implementations as possible start from this optimal foundation. For those of you that are already implementing, these upgrades might not be trivial, but I hope the above explanation helps articulate our reasons for doing them and the significant value each of them brings on the other side.

While we can’t predict what the future might bring, we don’t anticipate any further shifts of this magnitude as we go forward, so I hope that once we get over this hump Catalyst will have a stable core, amazing performance, sip resources & be inexpensive to host, and come with a kickass visual editor out of the box. ❤️

📢 We want to hear from you!

As always, we’re very interested in your feedback on these changes - we’re building Catalyst for you, so please check in with us on how you’re feeling about these updates and what we can be doing better.