Agnostic UI

[okbel]

Agnostic UI

Since Next.js Commerce came out one of our goals was to make it provider-agnostic. Today we're able to ship the first stable iteration of the agnostic UI.

Why

Frontend applications can be divided into two entities UI and Data. The UI accounting for the visual components and interactivity and the Data accounting for the application state and content.

Following these principles, the UI can be represented as a pure function of state or content. The less side-effects our components have, the more we can deterministically predict our application and build with confidence.

In order to make Next.js Commerce ready for multiple providers we needed a way to normalize data and inject it into the UI with the least amount of changes and with solid defaults.

That's why we built a set of wrappers and helper functions to create stable providers that the UI can trust.

Considerations

• framework/commerce contains all types, helpers and functions to be used as base to build a new provider.
• Providers will now live under framework's root folder and they will extend Next.js Commerce types and functionality.
• Features API is to ensure feature parity between the UI and the Provider. The UI should update accordingly and no extra code should be bundled. All extra configuration for features will live under features in commerce.config.json and if needed it can also be accessed programatically.
• Each provider should add its corresponding next.config.js and commerce.config.json adding specific data related to the provider. For example in case of BigCommerce, the images CDN and additional API routes.
• Providers don't depend on anything that's specific to the application they're used in. They only depend on framework/commerce, on their own framework folder and on some dependencies included in package.json
• We recommend that each provider ships with an env.template file and a [readme.md](http://readme.md) file.

Features API

For feature parity between providers we added the Features API. This new addition means that you are now able to turn some features on and off based on your needs or the capabilities of the provider. This is particularly needed if a certain provider does not have e.g wishlist functionality, or other features.

The configuration for features should be expressed at commerce.config.json in each provider folder. If you need to turn something off for your application independently of the chosen provider, you can achieve this by modifying the final commerce.config.json at the root folder level.

Enhanced Folder Structure

Both framework and components folders are structured by functionality. This means that all related to a specific subset of functionality will live within that folder.

Common commerce functionality includes: products, wishlist, customer, cart, auth .

These tokens by functionality are important because we might not want to build features and add them to the bundle, so it's easier to ignore them per folder.

Summary of Updates

• Agnostic UI components - The components no longer depend on the commerce provider.
• New helpers and types to build new providers under framework/commerce
• New commerce.config.json added.
• New Provider: Shopify - https://shopify.demo.vercel.store/
• Minor updates: Improved variants selection, Color selection (check icon color changes if the color is lighter) and Cart UX.

Wiki

How to change providers

• Update the providerselected in commerce.config.json and set it to the new provider:

{
  "provider": "bigcommerce"
}

• Change the paths defined in tsconfig.json and update the @framework paths to point to the right folder provider:

"@framework": ["framework/bigcommerce"],
"@framework/*": ["framework/bigcommerce/*"]

• Add the right environment variables for the selected provider.

How to create a new provider

• We'd recommend to duplicate a provider folder and add your providers SDK.
• If you succeeded building a provider, submit a PR so we can all enjoy it.

How to turn Features on and off

NOTE: The selected provider should support the feature that you are toggling. (This means that you can't turn wishlist on if the provider doesn't support this functionality out the box)

• Open commerce.config.json
• You'll see a config file like this:

{
  "provider": "bigcommerce",
  "features": {
    "wishlist": false
  }
}

• Turn wishlist on by setting wishlist to true.
• Restart the app and the wishlist functionality should be back on.

Future updates

• Custom Checkout Support - Some providers support custom checkouts, and we want to add a beautiful checkout experience. Given that we already have Features API this will not be hard to achieve.
• Shared Node.js APIs - No API routes per provider, unifying and bringing more agnostic to the API. Additionally this could unlock more performance optimizations.
• More Providers - We now have a solid base to build providers. No excuses to open a PR.
• Hybrid Recipes - We can create combo providers, e.g: a CMS plus an eCommerce and more! 🤯
• More Creativity - Having this predictability over data means that we are going to be able to shuffle the UI and create different experiences based on certain scenarios. From an architectural standpoint this is one of the things that I'd like to unlock the most.

---

We're incredibly thankful to the amazing people that contributed to Next.js Commerce. We're pretty stoked with this release and excited to unlock the future of commerce.