Alberto Vena

A discovery workshop we ran last year with a mid-market DTC brand, somewhere around hour three. The team was replatforming to Shopify, the architecture conversation had drifted toward Hydrogen, and one of the senior people in the room said something we hear in some form on most of these calls. *One day, we might want a custom account portal. Or a loyalty experience we can't fully picture yet. We need the flexibility.*

The room agreed. There was nothing on the current roadmap that Liquid couldn't handle. There was no integration that would have failed. The day-one storefront could have been built on the Shopify online store in a quarter of the time and a fraction of the cost. None of that mattered, because the conversation had stopped being about the day-one storefront. It had quietly become a conversation about a future that nobody could describe, and the team was about to commit twelve months and substantial budget to it.

Most of the headless decisions we sit in on aren't engineering decisions. They're decisions about a future that may never arrive, paid for in present-day complexity. And in 2026, that complexity is heavier, and harder to recover from, than it was three years ago.

## The Future That May Never Arrive

By the time most brands ask whether they should go Hydrogen, the answer has already been shaped by everything except their own roadmap. Competitor sites they admire. Agency pitches that lean prestige. An internal champion who built a Hydrogen storefront somewhere else and wants to do it again. A creeping fear that staying on Liquid is the basic choice, the choice an ambitious brand wouldn't make.

The decision arrives pre-loaded into the workshop. What was supposed to be an architecture conversation becomes a search for justifications: features that *might* need Hydrogen, hypothetical capabilities that *might* be useful, edge cases that *might* not fit Liquid. The reasoning is real. The framing isn't. We aren't asking what the brand needs to build; we're asking what's wrong with the platform we've already decided we don't want.

Once you notice that pattern, the next question becomes the harder one: what are people actually buying when they buy Hydrogen?

## What Hydrogen Costs You

A Hydrogen build moves a large amount of work *from* Shopify *onto* you. That transfer is the real price tag, and most proposals quantify the upside without quantifying the transfer.

Start with the CMS. On a Liquid theme, the Shopify online store *is* the CMS: sections, blocks, theme settings, the metaobject system. Editors know how to use it. Engineers don't have to build it. Hydrogen ships none of that. You pick a CMS, integrate it, and operate it—Sanity, Contentful, or whatever else fits the editorial workflow your merchandising team actually does. The picking is the easy part. The hard part is everything downstream: templates, scheduled publishing, metaobject integrations, the dozens of small editorial conveniences that Online Store gives you for free.

Then the apps. Backend apps still work fine: order management, fulfillment, tax, payments. Anything that interacts with the storefront is a different story. Reviews, wishlists, swatch pickers, the merchandising UI a search vendor ships alongside their integration—every one of those rebuilds from scratch, even when the vendor publishes an SDK. The SDK gives you primitives. It doesn't give you the convenience of a theme editor toggle. Multiply that across the ten or fifteen apps a typical brand depends on, and the engineering bill starts getting scary.

Then infrastructure. The hosting that disappeared the day you went on Shopify reappears the day you go on Hydrogen. Deploys, environments, performance regressions, edge runtime quirks, the slow accretion of platform-operations work that someone on your team has to own. It rarely shows up in the original estimate, because at planning time it looks like a flat cost. It isn't. It compounds.

And then the team. A Liquid team and a Hydrogen team aren't the same team. If you have one and need the other, that's a hiring program, an upskilling track, and acceptance that some people on your current team won't make the transition. We've seen brands try to soft-pedal this and end up with a storefront nobody internally feels confident touching.

Every one of these is survivable. The question is whether the thing you're getting in exchange is worth carrying the burden.

## The Headless Bet Got Worse, Not Better

This hasn't always been our point of view on the Hydrogen-vs-Liquid debate.

We're a deeply technical team, and Hydrogen had every reason to win us over. A modern stack on top of Shopify's commerce engine. Real developer experience after a decade of Liquid's idiosyncrasies. The promise of working inside Shopify's ecosystem without inheriting its frontend constraints. On paper, joyful to work with. We were genuinely excited, and on the early projects we recommended it on, we built it well.

Then the bill came in. Not on day one, mind you, but quietly across the first eighteen months. Apps that didn't translate. Editorial workflows that had to be rebuilt because the headless CMS didn't behave the way merchandising teams expected. The slow widening of the operational surface area, where every quarter we'd find ourselves explaining a new piece of infrastructure to clients who thought they were buying a storefront. We changed our mind, and we changed our advice with it.

The ecosystem-level case has gotten worse alongside our own reading of it. Shopify's visible investment has moved elsewhere: AI surfaces, agentic commerce, the merchant-facing tools that drive their next phase of growth. Hydrogen release cadence has softened. Public commitments have softened. The volume of new documentation, the number of dotdev sessions, the velocity of the surrounding ecosystem, all of it has cooled relative to where it was in 2022. Fewer brands going Hydrogen means fewer frontend app vendors investing in headless SDKs, which means more rebuild-from-scratch work for whoever's still going there. The flywheel isn't spinning the way it used to.

The wider industry hype that carried headless—composable, MACH, the whole storefront-as-frontend pitch—has moved on too. The buzzword stack today is AI. The peers and prestige signals that made Hydrogen feel inevitable in 2022 don't push the same way now. None of that, on its own, is a reason to reject the architecture. But replatforming locks you in for years, and trajectory matters as much as the current snapshot. The right answer in 2022 isn't automatically the right answer today.

## When Headless Is (Actually) Justified

This isn't a piece against Hydrogen. There are real reasons to go headless on Shopify in 2026. They're narrower than the proposals suggest, but they exist—and if you're in one of them, the costs above are a tradeoff worth making.

There are technical constraints you can't change on a Liquid-rendered storefront. URL structures locked in for SEO reasons, theme-layer behaviors that don't reach the surface you need. If the constraint is real and material to the business, Hydrogen gives you back the control.

There are storefronts so unconventional they don't fit the Homepage / PLP / PDP / Checkout shape Shopify themes assume. A generative AI storefront. An interactive editorial layer. An experience that isn't really a page in the traditional sense. If the storefront experience *is* the product, and not a wrapper around the product, Liquid will fight you and Hydrogen will fit.

There's multi-backend routing. A storefront that has to front Shopify in one market and a different commerce backend in another (e.g., Salesforce, a legacy bespoke platform, a marketplace integration) behind a single customer experience. Liquid wasn't built for that. Hydrogen can be.

There's merchandising and personalization deep enough that integration with tools like Nosto or Algolia becomes the structural concern. When the duplication of HTML and styling across Liquid blocks is a bigger problem than the platform itself, the equation flips.

And there are brands that are partially publications: content workflows closer to a newsroom than a merchandising calendar, where the editorial complexity needs a frontend the online store editor can't accommodate. Crossover commerce-content sites have always sat awkwardly on Shopify.

These are legitimate use cases, but having one of them is a reason to consider Hydrogen, not a mandate.

Treating Hydrogen as a default for ambitious brands is how the present pays for a future that may never arrive.

## The Question You Should Be Asking

The decision improves the moment you replace the platform question with a present-tense business question.

Not *what might we want to build one day*. That question never resolves; the right answer is always "we don't know," and headless will always look like insurance against that uncertainty. Insurance you pay for upfront, every quarter, regardless of whether you ever make a claim.

The question that resolves is the present-tense one: *what are we trying to do that Liquid won't let us do, now or in the next twelve months?* If you can name the constraint—a specific roadmap item that hits a wall, a real cost of staying on Liquid that shows up in numbers, an experience your customer needs that the theme layer can't deliver—the headless conversation gets useful fast. If you can't, the conversation is happening in the wrong register.

Replatforming is already a big, messy project. (Anyone who tells you otherwise is lying.) Adding an architecture choice that nobody can defend in present-tense business terms is how messes become disasters.

## Choose the Platform You Can Defend Now

A Hydrogen yes, in 2026, should feel like accepting a limitation as much as gaining a capability.

More often than not, the limitations you're accepting are larger and more durable than the capability you're gaining: a CMS to operate, a frontend app catalog to rebuild, infrastructure to maintain, a team to retool. Some brands are in the rare position where the capability outweighs all of that. Most aren't.

If the tradeoff still reads as worth it after you've evaluated the pros and cons, go for it. Otherwise, Liquid isn't the cautious choice. It's the right one.

If you're in the middle of this decision and want a second opinion from a team that's lived it on both sides, [we should probably talk.](https://nebulab.com/contact-us)

Is Shopify Hydrogen Worth It in 2026?

A couple of weeks ago, Shopify released the [Summer ’24 Edition](https://www.shopify.com/editions/summer2024). Since its humble beginnings in the [summer of ’22](https://www.shopify.com/editions/summer2022#audiences), Editions has evolved into a major biyearly marketing initiative the Shopify team uses to update their customers and the larger commerce industry about the latest product announcements, upcoming functionality, and the general direction the platform is taking.

The splashy landing pages are then coronated by several official events, earned media (including, yes, the very article you’re reading), and fringe industry gatherings aimed at creating more hype around the platform and, by extension, the hundreds of industry players that live in its shadow and participate in its ecosystem.

And since everyone and their dog has an opinion on Editions, we thought we’d be remiss not to share our take on the most exciting announcements.

In the following paragraphs, you’ll find a recap of our favorite announcements from the Shopify Summer ’24 Edition, along with our opinions on what they mean for the future of the ecosystem.

Let’s get into it!

## You Get a Market, You Get a Market, Everybody Gets a Market

Historically, internationalization on Shopify has been challenging. For a long time, brands that wanted to start selling in other countries were forced to set up expansion stores that were, effectively, completely independent of the main store. This forced brands to sync their product catalog, settings, inventory, apps, etc., across all their stores–a Sisyphean task that often required installing clunky apps.

Then, in late 2021, [Shopify released Shopify Markets](https://www.shopify.com/news/global-by-default-shopify-markets-becomes-new-global-commerce-hub-for-merchants), a game-changing feature for brands looking to sell internationally. Markets allowed brands to sell to multiple countries from a single Shopify store while still controlling product catalogs, pricing, shipping, and other configurations on a per-country basis. Markets simplified international selling on Shopify dramatically and was acclaimed positively by both agencies and brands.

One year later, [Shopify released B2B](https://www.shopify.com/enterprise/blog/b2b-on-shopify), making it easier for brands to sell wholesale. Shopify B2B allowed merchants to manage company profiles, configure B2B-specific payment methods and terms, and set up dedicated price lists. It came at a time when more brands were looking at B2B to drive profitable growth and allowed brands to manage their wholesale operations from the same platform they knew and loved for DTC.

Until now, Markets and B2B have been entirely independent, each functioning according to different rules and concepts and configured in their respective UIs. Add to this Shopify POS, [which was launched in 2013](https://www.shopify.com/news/shopify-launches-revolutionary-point-of-sale-system) and also operated as a completely separate sales channel. Understandably, this created friction for merchants, who needed to navigate a complex maze of settings and rules to determine how their brand shows up in different channels.

![](https://cdn.sanity.io/images/kqgmf0g2/production/d624cc7cae90e895dd78cf1ee360266218b672ea-1280x720.jpg?fit=clip)

In the Summer ’24 Edition, Shopify announced that [Markets will become a unified home](https://www.shopify.com/editions/summer2024#markets) to manage all of your brand’s expansion efforts, whether you’re talking about new countries, B2B, or POS. For each channel, you can now configure the product catalog, availability, pricing, and much more from a single UI, and you can even combine different types of markets (e.g., all retail stores in the UK).

This not only gives brands an unprecedented amount of flexibility, but it also dramatically reduces the operational effort of maintaining multiple sales channels.

Finally, Shopify also announced that [each market will be able to use a separate business entity](https://www.shopify.com/editions/summer2024#multiple-business-entities) for payments. This long overdue change often prevented international brands from adopting Markets, forcing them to use expansion stores with all their quirks and limitations.

Our team was pretty excited about this change: It brings much-needed consistency to several areas of the platform and unlocks a range of use cases that were not possible before, such as having completely different themes for different markets or having complete control over the product catalog available to retail stores. It all _feels_ right, as evidenced by the ecosystem’s overwhelmingly positive response.

The new Markets experience is not available to the public yet, but you can [sign up](https://www.shopify.com/editions/summer2024#markets-top-10) to get notified when it will be released.


## New Shopify POS Functionality Gives Your Retail Stores Superpowers

Besides Markets, Shopify has put a lot of effort into making sure that all the different sales channels they offer to merchants are fully integrated. In the process, they’ve resolved some annoying gotchas and inconsistencies that had bothered merchants for years and unlocked new, exciting use cases.

POS got a lot of love in this regard. First of all, the POS hardware is now available in nine new countries–Belgium, Denmark, Germany, Ireland, Italy (yay!), the Netherlands, New Zealand, Spain, and the UK. In the last few years, we’ve seen pretty strong demand for Shopify’s POS devices in Europe, so it’s great to finally be able to offer them to merchants–Shopify’s hardware is excellent, and we can’t wait to experiment with it a bit more.

Secondly, Shopify is also enabling truly unified shopping experiences with two new features that bridge the gap between online and offline:

* [Ship to store](https://www.shopify.com/editions/summer2024#ship-to-store), which boosts Shopify’s existing BOPIS (Buy Online, Pickup In Store) functionality by allowing customers to choose their favorite pickup location regardless of inventory availability. When the product is unavailable, Shopify will seamlessly orchestrate delivery to the customer’s chosen pickup point.
* [Ship from store](https://www.shopify.com/editions/summer2024#ship-from-store), which allows merchants to use their stores as last-mile fulfillment networks. Online orders will appear on the retail store’s POS interface, from which store operators can fulfill the orders or, if unable, delegate fulfillment to another location or back to a standard fulfillment center.

![](https://cdn.sanity.io/images/kqgmf0g2/production/4b3bebec01781cec89054946a6bb6a758e528894-1280x720.jpg?fit=clip)

Finally, POS became more intelligent and more integrated with the rest of the Shopify ecosystem. This includes functionality such as:

* [One-tap digital receipts](https://www.shopify.com/editions/summer2024#digital-receipts-with-opt-ins), which can be delivered by email, text, or, if the customer has a Shop Pay account, to the Shop app.
* The ability to [collect personal information](https://www.shopify.com/editions/summer2024#require-info-at-checkout) such as name and email, marketing opt-ins, and sales staff attribution at checkout.
* Automatic integration with your store’s [return rules](https://www.shopify.com/editions/summer2024#return-rules), which reduces the likelihood of out-of-policy returns.

Combined, these features allow brands to make the most of their physical stores, reducing fulfillment costs, improving the customer experience, and helping brands collect more zero-party data. In an era when all merchants are trying to do more with less, this is the sort of innovation that we like to see from Shopify.

## Checkout Is Getting a Flexibility Boost 

Shopify’s checkout has long been a significant component of the platform’s value proposition and, at the same time, one of its biggest weaknesses. While it’s great for merchants to be able to delegate compliance concerns or checkout CRO to Shopify, the lack of customizability in the checkout flow has prevented specific categories of brands from implementing their ideal customer experience or, in some instances, from adopting Shopify altogether.

Some of this rigidity is by design: Shopify doesn’t want brands to shoot themselves in their metaphorical foot by making changes that could negatively impact their conversion rates. Finding the right balance between flexibility and compliance with industry regulations is also challenging, especially with the new limitations imposed by [PCI DSS v4](https://www.shopify.com/partners/blog/checkout-compliance).

That said, Shopify has been doing some great work on this front over the last few years by adopting a two-pronged approach: They’ve been opening up the checkout to more types of customizations and more elaborate use cases, but they’ve also been forcing merchants to use a set of standardized APIs (dubbed [Checkout Extensibility](https://www.shopify.com/enterprise/blog/checkout-extensibility-winter-editions)) to alter their checkout flow.

![](https://cdn.sanity.io/images/kqgmf0g2/production/bf8f13000bd1a4fc566adcfea2f55adb32bde12a-1280x720.jpg?fit=clip)

In the latest Edition, Shopify has continued on this path by releasing a slew of new features and customization APIs for their checkout:

* [Checkout Blocks](https://www.checkoutblocks.com/), a third-party app that allowed merchants to apply complex customizations to their checkout in a no-code UI, has been acquired by Shopify and is now free for all Shopify Plus merchants. It’s a fantastic product, and we couldn’t be happier for [Gil](https://www.linkedin.com/in/gilgreenberg/) and his team!
* Checkout will soon support [split shipping](https://www.shopify.com/editions/summer2024#split-shipping), allowing customers to see when an order will be split into multiple shipments and pick a different shipping method for each shipment. On a similar note, it’s now possible to [capture partial payments](https://www.shopify.com/editions/summer2024#payment-per-fulfillment) when part of an order is fulfilled.
* In a move that will undoubtedly be appreciated by brands outside the US, Shopify is now offering the ability to implement third-party integrations for [pickup points](https://www.shopify.com/editions/summer2024#3p-pickup-points-api) (not available yet) and [address autocompletion](https://shopify.dev/docs/api/checkout-ui-extensions/unstable/targets/utility/purchase-address-autocomplete-suggest), as well as to collect region-specific [address fields](https://www.shopify.com/editions/summer2024#region-specific-addresses) and different forms of [tax ID](https://www.shopify.com/editions/summer2024#tax-id-fields) for individual and business customers.
* Developers can now use the [Checkout Branding API](https://shopify.dev/docs/apps/build/checkout/styling) (available to Shopify Plus merchants only) to configure the checkout flow’s overall styling and UI elements. Additionally, they can [pre-fill the address at checkout](https://www.shopify.com/editions/summer2024#prefilled-addresses), which is handy for gift and wedding registries and other non-traditional shopping experiences.

These changes, most of which are targeted at international brands or brands with complex use cases such as marketplaces, give merchants some much-needed flexibility while still allowing Shopify to guarantee compliance and retain control over the end-user experience. 

In fact, we were working with a couple of brands waiting for some of this functionality to switch to Shopify, and we can’t wait to try it in the wild.

## Analytics, Controls, and Automation for Operators That Mean Business

Last but not least, Shopify announced a range of new features aimed at larger, more sophisticated brands that need greater visibility into and control over their businesses.

The spotlight goes to the [new Shopify Analytics](https://www.shopify.com/editions/summer2024#rebuilt-analytics), which allows merchants to build advanced custom reports and dashboards and, soon, query their data directly using ShopifyQL. Combined, these two features unlock much greater flexibility when it comes to business analytics, reducing the need for merchants to roll out and maintain dedicated business intelligence infrastructure.

![](https://cdn.sanity.io/images/kqgmf0g2/production/b489a739028c98fd8168cafd505dd0874b2b0c52-1280x720.jpg?fit=clip)

Organization settings and staff access also received some love. While the details are not completely fleshed out yet, it looks like companies will soon be able to [manage multiple stores from a unified interface and](https://www.shopify.com/editions/summer2024#organization-settings) assign staff access through a [Role-Based Access Control (RBAC) system.](https://www.shopify.com/editions/summer2024#role-based-access-control)

Finally, Shopify is releasing several improvements for Shopify Flow, their built-in task automation platform. Flow is becoming more powerful (thanks to features such as the ability to [send direct requests to the Admin API](https://www.shopify.com/editions/summer2024#send-admin-api-in-flow)), easier to use (see the [improved UX for working with metafields](https://www.shopify.com/editions/summer2024#custom-data-for-flow)), and more convenient to debug when something goes wrong (with a [better search experience](https://www.shopify.com/editions/summer2024#search-runs-for-flow) and [manual reruns](https://www.shopify.com/editions/summer2024#manual-reruns-in-flow)).

While Flow still leaves a lot to be desired (how much longer until we can use the result of an API call inside Flow?!), it’s a robust product for automatic basic tasks in a low-code environment. In fact, we’ve been able to use it in several instances where we would have previously reached for a custom app or an external automation platform, such as Zapier.

## Hydrogen Gets The First-Class Treatment: Visual Editor and B2B Storefronts

On the headless front, much work went into creating consistency between Hydrogen’s off-the-shelf capabilities and what brands can do with Online Store.

The most prominent announcement here was the new [Hydrogen Visual Editor](https://www.shopify.com/editions/summer2024#hydrogen-visual-editor), based on an open-source solution called Utopia. The editor, which is yet to be released, will allow marketers to manage the content of their storefronts through a visual page builder.

Furthermore, the new visual editor _actually updates the underlying code_ of your storefront rather than loading content through a client-side network call. This comes with several benefits, including much faster page load times and all the goodies of Git-based version control.

In the past, we’ve had to roll out similar features manually through solutions such as Sanity and Builder.io, so it’s great to have this out of the box and officially supported by Shopify. That said, we were surprised that Shopify didn’t just acquire an established player in the space, such as [Pack](https://packdigital.com/) or [Instant](https://instant.so/), and integrated their solution natively.

We’re also still waiting for the day when Shopify will decide to unify its content management solutions, using the same technology across Online Store and Hydrogen. Perhaps this is a small step in that direction.

![](https://cdn.sanity.io/images/kqgmf0g2/production/257a779594efae973c9a1d3fe3c5d84b98eb04e0-1280x720.jpg?fit=clip)

In addition to the Visual Editor, it is now possible to launch [headless B2B storefronts](https://shopify.dev/docs/storefronts/headless/bring-your-own-stack/b2b)–a feature that was previously only available for Online Store. There’s even a [Hydrogen B2B template](https://github.com/Shopify/hydrogen/tree/main/examples/b2b) that you can leverage to speed up time-to-market if you wish.

These are the major announcements, but Shopify also announced [many additional improvements to Hydrogen](https://hydrogen.shopify.dev/update/summer-editions-24-announcing-the-hydrogen-visual-editor-and-a-ton-of-dx-improvements), such as an optimistic cart API for instantaneous cart updates, official support for Vite, native integration with Shopify Analytics and the Customer Privacy API, better environment variable management, and improved SEO tooling.

One of the main problems with headless Shopify architectures has been the feature and capability gap between Hydrogen and Online Store. There are still inconsistencies to figure out, especially when it comes to the app ecosystem. Still, with some of these announcements, it feels like we’re getting closer, which is excellent news for all merchants that need a more sophisticated storefront than what Liquid themes allow.

## There’s Much More…

In this article, we have deliberately omitted a lot of stuff, cherry-picking the announcements and capabilities that were most relevant to the work we typically do with our clients. We didn’t talk about the [improvements to Shopify Magic](https://www.shopify.com/editions/summer2024#ai-for-commerce) or all the work Shopify is doing around [third-party sales channels and Shop](https://www.shopify.com/editions/summer2024#connect-with-customers), their own marketplace. If you run a Shopify brand, we encourage you to check out [the official Editions site](https://www.shopify.com/editions/summer2024#connect-with-customers) to ensure you’re not missing anything!

That said, it’s clear that Shopify plans to continue pushing in all directions. For smaller brands, they are rolling out features that allow them to do more with less, leveraging the strength of Shopify’s ecosystem and economies of scale.

For larger brands, they’re making the platform more flexible to support more complex use cases. At the same time, though, they’re also creating consistency and feature parity across different flavors and sales channels to minimize the amount of gotchas and “insider knowledge” required to navigate the Shopify universe.

Given the size of that ecosystem, it’s an uphill battle, but if anyone has the market traction and R&D budget to pull this off, it’s Shopify–and we’re excited to be part of the ride.

Shopify Summer ’24 Edition: Are Things Getting Serious?

Daniel Bergholz

If you have used Shopify before, you’ve probably fallen in love with the Theme Editor. With its flexible content management options and smooth editing experience, this little piece of functionality is one of the reasons why brands love Shopify so much, and among the aspecs that make the platform so user-friendly compared to its competitors.

But if you decide to go headless, you might be appalled to find that the Theme Editor is not available on Hydrogen. In this case, you will need to either manage your content through code–a solution that dramatically slows down the pace at which you can make content changes–or implement your own content management solution.

In this article, we’ll show you how to do just that: by using Sanity, one of the most renowned and established headless content management solutions available today, we’ll give you quick walkthrough of how you can create a visual content management experience for your headless Hydrogen store.

Let’s dive in!

## Creating Our Content Schema

First of all, let’s create a new Hydrogen application:

```
$ npm create @shopify/hydrogen@latest
```

Now, sign into [Sanity](https://www.sanity.io) and create a new project. When asked how you want to set up your project, pick “From scratch with CLI”:

![](https://cdn.sanity.io/images/kqgmf0g2/production/6e5f37b582d5a25e0f14746437677f4f367331d5-1999x1165.png?fit=clip)

Your project and a public production dataset will be created. You will also receive instructions on setting up Sanity Studio for a JavaScript codebase.

![](https://cdn.sanity.io/images/kqgmf0g2/production/2a13ec2cd76a56f54e53e28442d682c9e82fb222-1999x1371.png?fit=clip)

Now, run the Sanity Studio setup command within the Hydrogen codebase, and name the resulting folder `studio`:

```
$ npm create sanity@latest -- --project [YOUR PROJECT ID] --dataset production --template clean
```

This should be the end result:

![](https://cdn.sanity.io/images/kqgmf0g2/production/3f411a4035a00219d829c4ce4387d89184246170-626x684.png?fit=clip)

All the files generated for Sanity Studio

Next, let's create a new document in Sanity to display later in Hydrogen. How about a promotional banner? Open `studio/schemaTypes/index.ts` and create the `banner` type:

```
import {defineField, defineType} from 'sanity'

const banner = defineType({
  name: 'banner',
  title: 'Banner',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Title',
      type: 'string',
    }),
    defineField({
      name: 'content',
      title: 'Content',
      type: 'text',
    }),
  ],
})

export const schemaTypes = [banner]
```

Now run Sanity Studio locally, open [http://localhost:3333/](http://localhost:3333/), and create a few banners:

```
$ cd studio && npm run dev
```

![](https://cdn.sanity.io/images/kqgmf0g2/production/5038e128559f997b3b660faa780ac95a05aa43f4-1999x1234.png?fit=clip)

Et voilà, our content is available in Sanity! Now, it’s time to connect Hydrogen to Sanity, so that we can actually retrieve and display the content.

## Connecting Hydrogen to Sanity

We now need to connect our Hydrogen store to Sanity to retrieve this data and display it on the homepage. Let's install the official integration package in the root folder:

```
$ npm i hydrogen-sanity
```

Add a couple of environment variables to `.env`:
```
SANITY_STUDIO_PROJECT_ID=[YOUR PROJECT ID]
SANITY_STUDIO_DATASET=[YOUR DATASET NAME, USUALLY "production"]
SANITY_STUDIO_URL="http://localhost:3333"
```

Update the `server.ts` file from the root to include the Sanity Loader:

```
// ...all other imports
// Add imports for Sanity Loader and Preview Session
import {createSanityLoader} from 'hydrogen-sanity'

// Inside the default export
export default () => {
  // ... Leave all other functions like the storefront client as-is

  // (Prerequisite) If not already initialized, create a `withCache` handler...
  const withCache = createWithCache({cache, waitUntil, request})

  // 1. Configure the Sanity Loader and preview mode
  const sanity = createSanityLoader({
    withCache,
    client: {
      projectId: env.SANITY_PROJECT_ID,
      dataset: env.SANITY_DATASET,
      apiVersion: env.SANITY_API_VERSION || '2023-03-30',
      useCdn: process.env.NODE_ENV === 'production',
    },
  });

  // 2. Make Sanity available to all action and loader contexts
  const handleRequest = createRequestHandler({
    // ...other settings
    getLoadContext: () => ({
      // ...other providers
      withCache,
      sanity,
    }),
  })
}
```

Your Sanity client will now be available in `context.sanity` in all your Remix loaders!

## Retrieving Content from Sanity

Let’s try to visualize the banners we have created previously. 

Inside the homepage `app/routes/_index.tsx`, add a Sanity query to the loader function:

```
export async function loader({context}: LoaderFunctionArgs) {
  // ...other storefront queries

  const banners = await context.sanity.loadQuery(`*[_type == "banner"]`);

  return json({
    // ... storefront queries
    banners,
  });
}
```

And inside the same file, modify the UI to display the data we’re retrieving:

```
export default function Homepage() {
  const {banners} = useLoaderData<typeof loader>();

  return (
    <div className="banner-container">
      {banners.data.map((banner) => (
        <div key={banner._id} className="banner">
          <h2>{banner.title}</h2>
          <p>{banner.content}</p>
        </div>
      ))}
    </div>
  );
}
```

And here you go! We’ve added a bit of CSS to make the preview look nicer:

![](https://cdn.sanity.io/images/kqgmf0g2/production/9b20bed734c392865e89a5ec55bf3c2bf569c1a3-1534x416.png?fit=clip)

Obviously, this is a very basic example–in the real world, you’ll have a much richer content schema. You may even allow your content editors to compose pages however they want by creating a 1:1 mapping between your Sanity schemas to React components, adding live previews, etc.

The sky’s the limit, and we encourage you to check out [the Sanity documentation](https://www.sanity.io/docs) to learn about all the possibilities!

## Keep Up with The Ecosystem

In this article, we have rolled our custom Hydrogen-Sanity integration, but the Remix and Hydrogen ecosystem are evolving rapidly. In fact, Sanity used to offer ready-made templates for integrating with Hydrogen, but they’ve since been archived. Shopify also just announced that they will be [releasing their own visual editor very soon](https://hydrogen.shopify.dev/update/summer-editions-24-announcing-the-hydrogen-visual-editor-and-a-ton-of-dx-improvements), in which case it might be worth switching over!

All of this to say, make sure to stay on top of what’s happening in the ecosystem and follow the latest best practices if you don’t want to be left behind. And if you _do_ deviate from those best practices, make sure that you always have a good reason for doing it!

How To Integrate Your Shopify Hydrogen Store with Sanity CMS

Marco Trincardi

There’s nothing more frustrating than trying to complete a puzzle, only to realize you’ve misplaced one of the pieces and there’s no way to finish the thing.

But what if you could _build_ that custom piece, designing it with all the right knobs and holes, allowing you to complete the puzzle? Imagine you could also paint it to perfectly complement the puzzle’s design. How amazing would that be?

Well, for real-world puzzles, you’re probably out of luck. But when it comes to computer systems, that’s pretty much what middleware does: just like your custom-built puzzle piece, middleware is custom software that streamlines the connection between different business applications, systems, or APIs, allowing them to communicate and collaborate effectively.

In e-commerce, middleware is usually found in enterprise applications, where companies often need to connect their proprietary systems to third-party vendors. However, middleware is not just for e-commerce giants: in specific scenarios, smaller brands can also use middleware to enhance the agility and robustness of their e-commerce setup.

In this article, we will explore the typical use cases for middleware software, the pros and cons of building your own, and how to do it correctly.


## When Does an E-Commerce Brand Need Middleware?

When you’re a large enterprise company, you typically have a dedicated IT department that handles system integration, and the responsibility for deciding when to buy or build middleware software lies with this department. In this case, you don’t need to worry about making such decisions.

But if you’re a smaller brand, you might be unsure when to think about middleware. Here are a couple of scenarios:


* You have found the perfect 3PL provider, but they don’t support your e-commerce platform out of the box.
* You want to use your existing ERP integration to generate invoices for your B2B e-commerce customers. However, the way your platform’s connector sends order data to the ERP is incorrect, and the resulting invoices are unusable.

In both cases, you could buy or build middleware software to integrate with the new system or adjust your existing integration. Just as a custom piece connects different sections of a puzzle, the middleware will bridge your different vendors together, ensuring they produce the desired results.

In general, whenever you want to insert yourself between different applications to streamline or adjust their data flow, middleware is the right solution.

With that said, adding middleware to your infrastructure is not free: let’s look at the complexity it can create and how to manage it.

## Middleware Seems Easy Until It Isn’t

Most of the time, your first middleware implementation is easy to build. You start from a well-identified business need, and the project goes almost flawlessly. Once online, you might find some edge cases that were not covered, but it’s usually pretty simple to address them. Everything’s under control, and everyone on your team is happy.

After a few weeks or months, you identify new business needs that are not satisfied by your existing system. Since the first iteration went well, you feel confident adding new functionality to the middleware–perhaps by integrating with a new external system.

As you work to reconcile the different data schemas, you feel like you’re getting pulled in too many directions: data management becomes more complicated, caching and scalability problems start popping up, and not even the people who built your middleware stack are quite sure of the data transfer flows anymore.

Back to the puzzle metaphor, the knobs and holes are the communication channels, while design and color are the data model that needs to be blended. You have already put many different knobs and colors in one giant puzzle piece, and every time you need to connect to a new part of the puzzle, you keep changing it, adding knobs and holes, and trying to blend the colors harmoniously.

What was simple and neat in the beginning has become increasingly complex over time.

It’s also interesting to note that the perception of middleware complexity does not increase linearly. Usually, it has a discontinuity point: everything seems smooth and easy, but once you reach the discontinuity, everything suddenly becomes complex and demanding. In technical literature, this condition is called _complexity creep_.

So, where does this complexity come from, and how can you manage it?

## Managing the Complexity of Middleware

Now that you understand the inevitable complexity of middleware, it’s time to look at a few ways to keep it under control. Drawing from years of experience, we've honed some practical strategies to manage and mitigate these challenges effectively.

Let's take a look!


### #1: First of All, Do You Really Need Middleware?

This might sound counterintuitive since this entire article is about middleware, but the best way to keep complexity under control is not to create it in the first place, and the most cost-effective middleware is the one that doesn’t exist.

This isn’t always possible, and middleware software is sometimes a necessary evil. However, we’ve often seen retailers reach for complex custom solutions when the stock functionality of their e-commerce platform or fulfillment provider would have worked just as well.

Before jumping into a middleware project, evaluate your vendors’ capabilities carefully–ideally, reach out to their support team and see if they can suggest any alternatives that will work out of the box.

Even when there are no alternatives, consider whether reframing your original request might lead to a much simpler solution: sometimes, the cost and effort involved in buying/building and maintaining your middleware doesn’t justify the return on that investment.

As a rule of thumb, if you can’t build a compelling business case around your middleware stack, and the only reason you’re building it is to make your life slightly easier, it’s probably better to hold off on the project until you can identify a pressing need.


### #2: Acquire a Bird’s-Eye View of Your Workflows

When you decide to build middleware, start the project by mapping the existing business processes. Don’t just focus on the process impacted by your middleware; instead, make sure to also cover upstream, downstream, and adjacent dependencies.

Sound too abstract? Let's make it more concrete with our ERP example:

1. First, describe what is happening in your internal and external software applications from when the order is made to when the invoice is sent.
2. Then, expand upstream, asking questions such as: “What are some of the promotions or discounts that could be applied to the order? How do we reflect that in the invoice?”
3. Finally, expand downstream, asking questions such as: “Does the invoice generation process only impact the ERP? How does it affect our CRM, supply chain or legacy systems?”

Back to the jigsaw puzzle metaphor, this process is like acquiring a view of the entire puzzle, and not just of the knobs and holes that surround our custom piece. Building this comprehensive understanding of your business workflows not only aids in your current middleware project but also helps you anticipate and manage future complexity.

The best part is that it doesn’t take ages to create this map: at Nebulab, we usually run a dedicated eight-hour workshop, remotely or in-person, to build the first version; we then spend a couple of hours now and then when we need to update it.

### #3: Adopt an Evolutionary Approach

Having a broad view of your business workflows doesn’t mean you have to build your entire middleware stack in one sitting. Quite the contrary!

The best approach is to build incrementally, one use case at a time, and get feedback from real-world usage. This feedback is essential to guide you in future development, refine your processes, and spark new ideas. It also makes it easier and more sustainable, reducing the chance that a middleware bug will severely impact your customer experience.

See it this way: The broader view tells you which direction to go, while the evolutionary approach tells you to put one foot before the other rather than making giant leaps. You have a complete vision of your puzzle, but you still build your custom piece one knob at a time.

## Your Middleware Is Critical Software

Once created, your middleware will become a central component of your brand’s tech stack: most likely, it handles your customer, order, or shipment data; it’s a critical piece of your customer experience, and it will negatively impact your operations in case of malfunction.

Because of this, middleware development should be considered mission-critical and treated accordingly: involve established vendors and highly skilled developers–ideally, someone with a track record of building high-traffic systems and who knows how to create resilient, high-quality software through best practices and automated testing.

In e-commerce, these competencies are rare. If you don’t have them in-house or in your partner network, [feel free to reach out!](https://nebulab.com/contact-us) We’ve supported tens of brands just like yours in designing, building, and maintaining their middleware solutions, and we know what it takes to make this journey as smooth as possible.


How To Design and Maintain E-Commerce Middleware

For a long time, Shopify has been considered as the eCommerce platform for SMBs: easy to set up and maintain, with the largest ecosystem of integrations and service providers in the industry, the original promise of Shopify was to [arm the rebels](https://shopifyrebellion.gg/), giving every entrepreneur everything they need to launch an online store. This value proposition attracted millions of small businesses to the platform.

Historically, the downside of Shopify’s ease of use has been its lack of flexibility: Shopify has always been a featured-packed but ultimately closed platform, unable to offer the technical sophistication of competitors catering to the enterprise eCommerce space, such as [Salesforce Commerce Cloud](https://www.salesforce.com/products/commerce/) and [commercetools](https://commercetools.com/). Enterprise requirements demand a much more open and extensible architecture, which was at odds with Shopify’s promise of power and simplicity.

But in the last couple of years, Shopify has used its traction to push hard upmarket, with products such as [Hydrogen](https://nebulab.com/blog/shopify-hydrogen) and [Commerce Components](https://www.shopify.com/commerce-components) that are meant to appease the needs of the enterprise segment. The result is two-fold:

* Shopify has been eating into the market of its enterprise competitors. For enterprise brands, Shopify is a compelling product with incredible traction.
* SMBs have been taking an interest in more advanced architectures, such as headless and composable commerce, that Shopify did not offer before.

The fact that Shopify offers three different architectures, their original Online Store product plus Hydrogen and Commerce Components, and two commercial offerings, Shopify and Shopify Plus, often leaves operators confused and prone to analysis paralysis. In the worst-case scenario, we see brands make the wrong choice, leading to a more complex and fragile architecture than they were prepared for.

In this article, we want to provide a map for anyone looking to navigate Shopify’s different offerings and flavors so that you can make the right decision for your brand and maximize the return on your investment.

Let’s dive in!

## Online Store: Small but Mighty

Let’s start with the most basic and popular option: Online Store.

In technical terms, Online Store is Shopify’s monolithic commerce product, meaning that your e-commerce platform and storefront are bundled in the same package. When you go with Online Store, you can customize your store in two ways: by editing your theme (either through Liquid templates or the Theme Editor) or by installing apps from Shopify’s App Store.

In other words, when you use Online Store, Shopify controls and delivers your entire commerce experience end-to-end. This creates a streamlined experience for you and your Shopify developers: the Theme Editor will allow you to make most content changes yourself. Certain Shopify themes will even auto-update to the latest version–as long as you haven’t modified them too heavily–so you won’t need to use developer hours for theme updates.

![](https://cdn.sanity.io/images/kqgmf0g2/production/05cb8d62586c75912162aeed16bccd3b447caef5-1600x1052.jpg?fit=clip)

The most significant advantage of using Online Store, however, is the size of the ecosystem you will be able to access: pretty much every Shopify App has been built with Online Store in mind, which makes it incredibly simple to add new functionality to your store with a click of a button. The same goes for agencies and system integrators: most developers in the Shopify ecosystem are used to working with Online Store architectures, so it will be much easier to find someone to help you.

What’s the catch, then?

Well, as we mentioned in the introduction, larger brands have scoffed at this flavor of Shopify because it lacks flexibility and technical sophistication. As your store grows, you might start bumping into certain limitations that make it hard to keep a high quality bar: apps that don’t play nice with each other, performance issues that cannot be easily mitigated, and new features that cannot be implemented without unreliable workarounds.

To be fair, some of these issues are not caused by Online Store per se, but rather by an inexperienced development or marketing team that abuses the plug-and-play nature of this architecture and ends up shooting themselves in the feet.

However, it’s undeniable that Online Store offers less control to Shopify merchants than the alternatives, so let’s look at what else Shopify has to offer!

## Hydrogen: Let’s Lose Our Heads

[Hydrogen](https://nebulab.com/blog/shopify-hydrogen) is Shopify’s headless ecommerce product, and it was their first answer to more complex customization needs. Released in late 2021, the Hydrogen framework gives brands complete control over their shopping experience, allowing them to build custom frontends with literally no limitations.

In practice, the way Hydrogen works is that, rather than building a theme, which you then upload to Shopify, you create your Hydrogen storefront as a completely standalone JavaScript/React application that leverages a set of pre-built components provided by Shopify. This custom storefront will still use Shopify’s Storefront API to power most of its functionality, but because you control the entire codebase, you can easily implement custom functionality that Shopify’s backend doesn’t support and create richer customer experiences.

You can deploy Hydrogen apps on [Shopify Oxygen](https://shopify.dev/docs/custom-storefronts/oxygen), Shopify’s free hosting solution, or any other hosting platform that supports JavaScript, such as [Vercel](https://vercel.com/).

As we’ve already mentioned, the main upside of Shopify Hydrogen is control: with a headless store, the sky is quite literally the limit, and whether you can accomplish something mostly depends on how many resources you want to invest into the project. This flexibility allows brands to really push the boundaries of digital commerce and offer lightning-fast, highly engaging user experiences. By giving you more granular control, headless storefronts also make it easier to fine-tune your site’s speed and customize your integrations.

On the other hand, this level of control is not for everyone: if you want to go with Hydrogen, you need to ensure your development team has experience with headless solutions. Otherwise, you’re bound to create more problems than you’re solving. You can also expect the development and maintenance of your Shopify store to become a bit more complicated as you lose access to some of Online Store’s let-me-do-that-for-you functionality.

![](https://cdn.sanity.io/images/kqgmf0g2/production/a6338ec311c8c4db7308b78bed520d05dd67fbc0-1600x1052.jpg?fit=clip)

The other significant downside of going with Hydrogen is losing access to a big part of Shopify’s ecosystem: as we’ve mentioned earlier, most Shopify apps, and even many of Shopify’s internal features, have been built for Online Store shops. Hydrogen stores can forget about the Theme Editor and one-click app installations; instead, you will need to pick content management and other technology providers that offer an API, and then [implement and maintain those integrations yourself.](https://hydrogen.shopify.dev/integrations)

But what if not even headless commerce cuts it, perhaps because you have an existing eCommerce infrastructure that you want to migrate to Shopify more gradually, or because eCommerce is just one part of a much larger retail setup? 

Those are the kinds of problems that Commerce Components was built to solve.

## Commerce Components: The Composable Way

[Commerce Components](https://www.shopify.com/commerce-components) is Shopify’s answer to the rise in popularity of composable commerce, especially among enterprise merchants.

On the surface, composable architectures are not dissimilar from headless architectures: rather than having everything in one place, your Shopify storefront is implemented and hosted separately from your eCommerce stack and interacts with it through APIs. _Unlike_ in a headless architecture, however, you’re not just integrating with one service provider, but stitching together a plethora of them by picking the best-in-class provider in each category.

Let’s look at a practical example: the first component Shopify is making available as a standalone offering is Shop Pay, their accelerated checkout. That means you can use Shop Pay as your checkout even if you don’t use Shopify for Product Information Management (PIM) or as your Order Management System (OMS).

![](https://cdn.sanity.io/images/kqgmf0g2/production/0ae4e563810428092df43dce23463b6af5070fc2-1600x1052.jpg?fit=clip)

For large merchants, this is a very compelling proposal: it’s much easier to integrate smaller pieces of Shopify as needed rather than uprooting their entire tech stack. For Shopify, it’s a powerful way to get a foot in the door and eventually win more of a merchant’s business–as they’ve reiterated repeatedly in their recent earnings calls.

It’s crucial to note Shopify is very new to the composable space, and it will most likely take a while before Commerce Components becomes a first-class citizen in their ecosystem. Right now, it’s being used by some very large retailers, such as [Glossier](https://www.glossier.com/), but Commerce Components is a recent offering, and there’s still not much information about it. All Commerce Components deals need to go through Shopify’s sales team and are being discussed on a case-by-case basis–you can’t just sign up on your own and start building.

As cool as it may sound, the complexity of a composable architecture is not for the faint of heart. Think headless development, but times ten, because now you need to stitch together even more pieces. This architecture typically requires a dedicated engineering team, and it’s most often adopted by brands that treat technology as a first-class citizen: if you don’t have a CIO, CTO, or VP of Technology, Commerce Components is _almost certainly_ not for you.

If, on the other hand, you’re an enterprise brand running on a legacy infrastructure that you’d like to modernize, Commerce Components allows you to do so progressively and without dramatically disrupting your existing workflows or technology.

## So, Which One Should You Use?

If you still have doubts at this point, here’s a quick cheatsheet to understand what Shopify version to go with depending on your ecommerce store’s maturity:

* If you’re below $100M in annual GMV, just stick with Online Store. The simplicity of having everything in one unified package and the power of Shopify’s ecosystem will more than compensate for the lack of flexibility.
* If you’re beyond $100M in annual GMV and constantly running into technical limitations with Online Store, you might want to start evaluating Hydrogen. However, make sure to pick a partner that can support you and will not be scared by digging into the more technical aspects of running your store.
* If you’re a large/enterprise ($300-400M+ in annual GMV) retailer with a complex infrastructure and an established engineering discipline and want to either migrate to Shopify or integrate specific pieces of Shopify’s offering, Commerce Components might be a good fit.

With that said, keep in mind that these recommendations are a floor, not a ceiling: we have worked with small/medium brands that were ambitious and technical-savvy enough to go with Hydrogen well below the $100M/year threshold, and we’ve worked with brands doing $300M/year through Online Store. Any choice you make should be made in the context of _your_ business needs and capabilities–that’s where picking a strong technical partner with a broad understanding of these offerings can have a considerable impact.

If you need any help making a decision, we’d love to help! Our team has extensive experience working with brands from pre-revenue to $500M/year, and can advise on the best technical architecture for your brand. [Feel free to reach out!](https://nebulab.com/contact-us)


Comparing Shopify’s Online Store, Hydrogen, and Commerce Components

If you have been working with Shopify’s Hydrogen framework for some time, you might still have some scars after the
[migration from Hydrogen v1 to Hydrogen v2](https://nebulab.com/blog/shopify-hydrogen-v2-updates).

One of the major changes in Hydrogen v2 was the transition from a custom-built React framework to
[Remix](https://remix.run/), a relatively new framework that is seeing a lot of traction thanks to its streamlined
developer experience, its reliance on Server-Side Rendering and its deep focus on web standards.

Remix was a significant improvement over Shopify’s in-house React framework, and allowed Hydrogen stores to benefit
from a much larger ecosystem of Remix docs, plugins and system integrators. We’ve discussed the benefits at length in
[our blog post covering the migration](https://nebulab.com/blog/shopify-hydrogen-v2-updates).

Unfortunately, the migration process from Hydrogen v1 to Hydrogen v2 was also incredibly complex. So much so, that many
large brands were better off re-building their storefront from scratch with Hydrogen v2 rather than attempting to port
their existing codebase. This caused a lot of discontent and frustration with Shopify’s decision, which didn’t seem to
fully appreciate the complexity of maintaining a complex headless architecture.

Now, it _feels_ like history might be repeating itself: Remix just announced a new major release. Remix v2 comes with
several new features and improvements to the developer experience that Hydrogen developers will also benefit from.
However, Hydrogen teams are also worried that the transition to Remix v2 might be their latest time-suck and source of
frustration.

But is that really the case, or are things better this time around?

In the past few weeks, we’ve been following the Remix community and trying to unpack the implications of this release
for Hydrogen. Let’s see what this release actually means for you, and how you can make the best of it!

## What’s New in Remix v2 for Hydrogen Devs?

Let’s start by taking a look at the changes and new features in Remix v2 that are most relevant for Hydrogen developers.

Keep in mind that you can always read the [release announcement](https://github.com/remix-run/remix/releases/tag/remix%402.0.0)
if you want to see the complete list of changes!

### New Dev Server with HMR and HDR

If you’ve used a more established React framework such as Next.js, you’re probably familiar with HMR even though you
might not know the acronym. HMR, which stands for Hot Module Replacement, is the feature that allows the page to update
instantaneously and reflect any changes you make to your code. It’s a handy functionality when you’re actively
developing a new page, or making small visual tweaks that you want to preview in real time.

Historically, Remix did not offer support for HMR: that meant you had to manually refresh the page whenever you made
a change to your client-side or server-side code, which was old-school and time-consuming.

Luckily, that’s not the case anymore! Remix v2 ships with a new dev server that supports HMR and Hot Data Reloading
(HDR), the equivalent of HMR for server-side code. Whenever you make a change to your Hydrogen app, it will be
propagated immediately to your browser. Client-side state is also maintained, so that you can continue interacting with
the app without restarting any user flows from scratch (e.g., if you’re in the middle of checkout).

It has support for hot module replacement (HMR) and hot data reloading (HDR). The announcement is available
[on YouTube](https://www.youtube.com/watch?v=79M4vYZi-po).

On earlier versions of Remix, whenever there was a code change, you would have to manually refresh the page to see the
new changes (pretty old-school tech). Now, that is unnecessary and HMR will not reset client-side state between updates.
And HDR can be described as HMR for data loaders. With HDR you can make changes to your server code and see those
updates reflected in your UI immediately without resetting client-side state, just like HMR.

### Native Support for PostCSS and Tailwind and PostCSS

As you probably know, Hydrogen uses [Tailwind](https://tailwindcss.com/) as the default CSS framework.

Unlike more traditional CSS frameworks (such as Bootstrap), Tailwind relies heavily on CSS post-processing to generate
your final CSS build: it scans all your files, understands which Tailwind classes need to be generated, and then
generates just the classes you need. This allows you to minimize the amount of CSS you’re shipping to the client while
also allowing you to do incredible things, like attaching [arbitrary CSS properties](https://tailwindcss.com/docs/adding-custom-styles#arbitrary-properties).

Before Remix v2, you would have to run any CSS transformations in a separate process, e.g. with
[Tailwind’s CLI interface](https://tailwindcss.com/blog/standalone-cli), then import the final CSS file into your Remix
app. This worked, but wasn’t really a smooth development experience.

Remix v2 adds out-of-the-box support for [Tailwind directives and PostCSS](https://remix.run/docs/en/main/start/v2#built-in-postcsstailwind-support),
a popular CSS processor that Tailwind integrates natively with. If you’re using Hydrogen, all the relevant configuration
is generated for you: simply bootstrap your app, and your Tailwind styles will just start compiling automagically!

Check out Remix’s documentation about [PostCSS](https://remix.run/docs/en/main/styling/postcss) and
[Tailwind](https://remix.run/docs/en/main/styling/tailwind) for more details.

### Server-Side Streaming with `defer`

This one is a game-changer. Remix v2 aims to provide first-class support for React 18's SSR streaming capabilities
through the `defer` helper.

When you return a `defer` function call in a route loader, you are initiating a streamed response. This is very
useful when serving lower-priority data that may take longer to load. After all, you don’t want your users to wait on
slow data if more important content is ready to display on the page!

Here’s an example of what streaming looks like on the server:

```javascript
import { defer } from "@remix-run/node";

export async function loader ({ request }) {
  // Product info query is small, cached aggressively, ad
  // high priority for the user. Let’s go ahead and let it
  // resolve since it’s fast!
  let productInfo = await getProductInfo (rewquest);

  // Product reviews query is large and cache is more lax.
  // Let’s initiate the query but not wait for it to resolve.
  let productReviewsPromise = getProductReviews (request);

  // With defer, we initiate a streaming response. This allows
  // the user to access the resolved data (`productInfo`) as
  // soon as it’s available, while the unresolved product
  // reviews are loaded in the background.
  return defer ({
    productInfo,
    productReviewsPromise,
  });
}
```

The corresponding client-side code would then leverage the `Await` component, which is built on top of
[React’s `<Suspense />` API](https://react.dev/reference/react/Suspense):

```javascript
import { Await } from "@remix-run/react";

function ProductRoute () {
  let {
    // Product info has already resolved. Render immediately!
    productInfo,
    // Product reviews might not be ready yet 🤔
    productReviewsPromise,
  } = useLoaderData ();

  return (
    <div>
      <h1>{productInfo.name}</h1>
      <p>{productInfo.description}</p>
      <BuyNowButton productId={productInfo.id} />
      <hr />
      <h2>Reviews</h2>
      <React.Suspense fallback={<p>Loading reviews…</p>}>
        <Await resolve={productReviewsPromise} errorElement={<ReviewsError />}>
          {(productReviews) =>
            productReviews.map ((review) => (
              <div key={review.id}>
                <h3>{review.title}</h3>
                <p>{review.body}</p>
              </div>
            ))
          }
        </Await>
      </React.Suspense>
    </div>
  )
}

// Error fetching the data? Slow connection and timed out?
// Show an error message *only* for reviews. The rest
// of your product UI is still usable!
function ReviewsError () {
  let error = useAsyncError (); // Get the rejected value
  return <p>There was an error loading reviews: {error.message}</p>;
}
```

This was a framework-agnostic example, but Hydrogen is already leveraging `defer`. On the home page, for instance,
recommended products are streamed rather than being loaded immediately:

```typescript
export async function loader ({context}: LoaderArgs) {
  const {storefront} = context;
  const {collections} = await storefront.query (FEATURED_COLLECTION_QUERY);
  const featuredCollection = collection.nodes[0];
  const recommendedProducts = storefront.query (RECOMMENDED_PRODUCTS_QUERY);

  return defer ({featuredCollection, recommendedProducts});
}
```

For more examples of how Hydrogen leverages Remix features to optimize data handling, you can take a look at
[this article](https://hydrogen.shopify.dev/update/improving-data-handling-in-hydrogen-and-remix).

### Flat Routing by Default

Older versions of Remix use subfolders to nest route segments. This leads to a lot of directory nesting, and also makes
it harder to navigate the directory tree.

Remix v2 embraces [flat routing](https://remix.run/docs/en/main/start/v2#file-system-route-convention) instead. With
flat routing, all your routes are in the same directory, which makes it easy to find them at a glance. For example,
here’s the new folder structure in a Hydrogen application based on Remix v2:

![](https://cdn.sanity.io/images/kqgmf0g2/production/59ae846180e55976494ef64fb35b7ee854107044-698x1370.png?fit=clip)

There’s a bit more to it, so we encourage you to check out [Remix’s documentation](https://remix.run/docs/en/main/start/v2#file-system-route-convention)
about the change to fully understand the new folder structure.

Since not everyone will love this change, you can also maintain the current approach by installing the
`@remix-run/v1-route-convention` package and adding the following to your `remix.config.js`:

```javascript
const {
  createRoutesFromFolders,
} = require ("@remix-run/v1-route-convention");

/** @type {import ('@remix-run/dev').AppConfig} */
module.exports = {
  future: {
    // makes the warning go away in v1.15+
    v2_routeConvention: true,
  },

  routes (defineRoutes) {
    // uses the v1 convention, works in v1.15+ and v2
    return createRoutesFromFolders (defineRoutes);
  },
};
```

## How to Upgrade Your Hydrogen Application to Remix v2

Now, this is the part you were all waiting for! How difficult is it to upgrade an existing Hydrogen application to Remix
v2? Luckily for you, not very difficult.

The typical approach for performing major upgrades to your application’s dependencies typically involves creating a
separate, long-lived feature branch, working on the upgrade in isolation, and then releasing it all in one go.

![](https://cdn.sanity.io/images/kqgmf0g2/production/a7da987d49c9126fa8f5bc3dd60f94bbf867eea6-1516x634.png?fit=clip)

This approach, which is still very widespread, has several drawbacks:

- It is time-consuming, because it requires a lot of work and frequent rebases.
- It is prone to error, because you’re releasing a lot of changes in one deployment.
- It is all-or-nothing, because it prevents you from adopting new features before the upgrade.

Remix aims to fix this problem through [Future Flags](https://remix.run/docs/en/main/start/future-flags). Future flags
allow developers to incrementally adopt new features and then seamlessly upgrade their application, eliminating the need
for long feature branches and scary deployments.

Conceptually, the way they work is very simple: the Remix team releases Remix v2 features in Remix v1, but puts them
behind a feature flag that you need to manually enable in your Remix configuration. Then, when Remix v2 is released, the
Remix team simply removes all future flags and turns them into default behavior. This allows you to integrate one
feature at a time as it’s released by Remix, rather than doing it all in one pass.

![](https://cdn.sanity.io/images/kqgmf0g2/production/79ff3d1e16ca4fb2421871fa9cce3b5ba6a56599-1999x441.png?fit=clip)

For instance, here are the future flags for Remix v2:

```javascript
/** @type {import ('@remix-run/dev').AppConfig} */
module.exports = {
  //…
  future: {
    v2_dev: true,
    v2_meta: true,
    v2_headers: true,
    v2_errorBoundary: true,
    v2_routeConvention: true,
    v2_normalizeFormMethod: true,
  },
};
```

If you are on the latest version of Remix v1, your `remix.config.js` looks like the one above, and you’re not getting
any errors, you should be able to safely upgrade to Remix v2 by following the [official upgrade guide](https://remix.run/docs/en/main/start/v2).

If you haven’t enabled those future flags yet, then we strongly recommend doing so in the next few weeks so that you
can have a smooth upgrade path in front of you.

Note that the Hydrogen team still needs to officially release support for Remix v2, but thanks to future flags,
most of Hydrogen’s code is already compatible. All you need to do is upgrade the dependency in `package.json`, remove
the future flags in `remix.config.js`, and you should be good to go!

## What’s Next for Remix and Hydrogen?

In our work so far, we found the developer experience offered by Hydrogen through Remix is miles ahead of what we had in
Hydrogen v1. With a few lines of code, it’s possible to develop rich e-commerce experience while also abiding by web
standards and following modern UX practices. Because of that improvement, we’re very excited for the future of this
synergy!

The Remix team recently [announced](https://remix.run/blog/open-development) that they want to be more transparent about
their plans for the framework, but the [public roadmap](https://github.com/orgs/remix-run/projects/5) doesn’t offer a
lot of information yet. That means it’s still early to tell what other features might be coming up that Hydrogen
developers can benefit from.

One initiative on our radar is the [work](https://remix.run/blog/remix-v2#what-about-rsc) done by the Remix team to
integrate React Server Components (RSC). Unfortunately, this will take some more time, as RSC are still unstable and
won’t be included in Remix just yet as a result.

If you were waiting for more features or stability in order to start using Hydrogen, today is the best time to give it a
try! We’re sure you will be pleasantly surprised.

What Does Remix v2 Mean for Shopify Hydrogen Developers?

At the end of 2022, the entire frontend community was surprised by an unexpected announcement: [Shopify acquired Remix](https://shopify.engineering/remix-joins-shopify). At first glance, this news offers little information; after all, Shopify is famous for investing many resources into open-source projects. However, after further research, the reason for this merger became clear: Remix is deeply aligned with Shopify’s new framework: Hydrogen.

Shortly after the big news, the dev team behind Hydrogen [made another announcement](https://hydrogen.shopify.dev/roadmap/): the entire framework was being re-created from scratch using Remix, thus giving birth to Hydrogen v2. While the upgrade path will likely be a struggle for existing Hydrogen v1 users, Hydrogen v2 offers several benefits over its predecessor.

In this article, we’ll look at some of the most significant enhancements Hydrogen v2 brings to the developer experience, what they mean for your user experience, and how you can start adopting them in your storefront.

## A Brief Primer on Remix

To fully comprehend Hydrogen’s latest changes, we must first understand Remix.

For those unfamiliar with it, Remix is an up-and-coming Javascript framework based on React. It was developed by Kent C. Dodds, Ryan Florence, and Michael Jackson, all well-known contributors to the Javascript open-source community.

Unlike the previous generation of React frameworks such as Next.js, Remix is full-stack, monolithic, and fully server-side-rendered, and it will feel like a breath of fresh air to all the Ruby on Rails and Laravel lovers. In fact, Remix’s primary goal is to merge the benefits of the “old Web” with the smooth developer experience React offers. This way, developers get higher productivity, simpler code, better SEO, less backend-frontend communication overhead, smaller client bundles, and near-instantaneous page transitions.

![](https://cdn.sanity.io/images/kqgmf0g2/production/030082583dd37bf225378d98322d8b1993cf3e0b-2960x2400.png?fit=clip)

When developing the first version of Hydrogen, Shopify created a framework very similar to Remix in spirit: it was React-based, but it was also rendered on the server. This was a surprising choice back in the early days of Hydrogen, but it did make a lot of sense in retrospect: anyone who has tried to implement an eCommerce storefront quickly found that the dynamic nature of eCommerce doesn’t play well with static site generation and client-side rendering.

In October 2022, Remix announced that Shopify was acquiring it. As part of the deal, Shopify will offer continuous support to Remix’s authors to continue developing the framework, and Remix is becoming the React framework powering Hydrogen. On their side, Hydrogen’s development team can now delegate most of the core framework functionality to Remix, focusing only on Hydrogen-specific functionality.

## The Main Changes in Shopify Hydrogen v2

Even though the Shopify developer community (and Shopify themselves, [in some places](https://github.com/Shopify/hydrogen/blob/2023-04/packages/hydrogen/CHANGELOG.md#202317)) dubbed this release “Hydrogen v2”, this isn’t technically correct: Hydrogen simply follows calendar versioning, with each version number being a combination of the date and month of the release (e.g., v2023.1.0). However, for the sake of simplicity, we will refer to “Hydrogen v2” as the version of Hydrogen that uses Remix.

As you might expect, this release introduces _a lot_ of changes. In fact, pretty much everything in the framework has changed, meaning developers with an existing Hydrogen storefront have a whole bunch of rewriting to do.

### Retrieving Data with Loaders

The most significant change–which will affect pretty much every route in your project–is the introduction of Remix’s `loader` function.

The `loader` function is where all of your data retrieval logic is stored. The `useShopQuery` and `useQuery` hooks from Hydrogen v1, responsible for querying the Shopify Storefront API, have been replaced with `loader` in Hydrogen v2.

For example, imagine building a product detail page with a product options selector. In a typical React storefront, you would need to store the selected options in a state entry:

![](https://cdn.sanity.io/images/kqgmf0g2/production/e553a7b7b1f1e0d77e3cd95a9ecef7a1893b29c9-1200x520.png?fit=clip)

The problem with this implementation is that this component also needs to change the URL whenever a new variant is selected, so that users can easily bookmark or share the URL to the correct product variant. Unfortunately, there is no “native” way of achieving this with React. You would need to create a function that alters the URL when the user changes their selection.

With Remix, just like Ruby on Rails or Laravel, you can solve this by simply taking advantage of Web fundamentals. In this case, whenever the user selects a new product option, you simply direct them to a new URL, and the `loader` function gets executed again, querying the desired product variant from the Storefront API.

![](https://cdn.sanity.io/images/kqgmf0g2/production/3217fe54a31e57a20a6240808dd00e4937c4f7eb-1200x856.png?fit=clip)

The benefits of this new implementation are clear: we achieve the same outcome with less code and fewer abstractions to learn.

This approach was used to refactor all the major components in Hydrogen: the cart, analytics, SEO, and session management were rebuilt from scratch, resulting in a much more straightforward developer experience and a less steep learning curve!

[Learn more about the `loader` function in the Remix guides.](https://remix.run/docs/en/1.16.1/route/loader)

### Mutating Data with Actions

While the `loader` is used to _retrieve_ data, the `action` function is to _mutate_ data. As a consequence of segregating business logic into loaders and actions, you can now remove a bunch of code, especially client-side logic and state.

As an example, take a look at what the default `AddToCart` component looks like in the Hydrogen v1 demo store:

![](https://cdn.sanity.io/images/kqgmf0g2/production/253be981f9a0861351e4e2bcba39e77df56fec53-1374x2904.png?fit=clip)

And now, look at the same component in the Hydrogen v2 demo store:

![](https://cdn.sanity.io/images/kqgmf0g2/production/5c38c039f5c5132d9b9ba34c6d19d0b0075b7f0b-1424x1786.png?fit=clip)

As you can see, a lot of state management and querying logic has been removed in favor of a more straightforward implementation that relies on Web fundamentals such as... Web forms! This simplifies your code and makes your online store more resilient to network issues and more accessible to screen readers and old devices.

[Learn more about the `action` function in the Remix guides.](https://remix.run/docs/en/1.16.1/route/action)

### Handling Errors with Error Boundaries

A common and annoying problem with React applications is isolating errors. Typically, when you get any error on the frontend, the whole UI breaks, and the website becomes unusable. This is obviously not a desirable experience for our customers.

By taking advantage of Remix’s [nested routes](https://remix.run/docs/en/1.16.1/guides/routing#what-is-nested-routing), you can use [nested error boundaries](https://remix.run/docs/en/v1/guides/errors#nested-error-boundaries). If you export an error boundary function from a nested route and an error occurs, the error will be isolated, and the rest of your application will remain usable. This allows you to offer the best possible UX, even when things go wrong:

![](https://cdn.sanity.io/images/kqgmf0g2/production/e73f3849c1e52c9a44c721ff4b43976455174ab8-1207x1685.png?fit=clip)

[Learn more about error handling in the Remix guides.](https://remix.run/docs/en/1.16.1/guides/errors)

### Speeding Up Page Loads with Streaming

By using Remix’s [defer](https://remix.run/docs/en/1.16.1/guides/streaming#using-defer) function, you can easily decide which parts of your page should be rendered right away and which parts can be streamed after the page has loaded:

![](https://cdn.sanity.io/images/kqgmf0g2/production/d1fc77778b2760be478d391326acc7ede28f1abe-1207x1685.png?fit=clip)

This technique allows you to easily defer the loading of lower-priority parts of your UI, such as a “Related products” section on your PDP, making for a better user experience and faster loading times.

[Learn more about streaming in the Remix guides.](https://remix.run/docs/en/1.16.1/guides/streaming)

### Speeding Up User Interactions with Optimistic UI

Optimistic UI is a powerful technique that lets you completely hide loading states from the end user. For instance, when a user clicks on your Add to Cart button, rather than waiting for the cart to be updated on the server, you might immediately display the new item in the user’s cart. Then, if an error occurs, you can revert the state and display an error to the user:

![](https://cdn.sanity.io/images/kqgmf0g2/production/1cdb09cad49d184358eb840920173250a2061bc1-1250x800.png?fit=clip)

While not available yet, Hydrogen’s development team plans to adopt optimistic UI in all the standard components. Because Hydrogen is powered by Remix, you will also have the opportunity to use the same pattern in any custom user interactions you offer on your storefront.

[Learn more about optimistic UI in the Remix guides.](https://remix.run/docs/en/1.16.1/tutorials/jokes#optimistic-ui)

### Oxygen Is now Available to All Shopify Plans!

Although there was no official announcement, this is massive news for all Shopify developers! Hydrogen’s official deployment platform, [Oxygen](https://shopify.dev/docs/custom-storefronts/oxygen), which was only available to Shopify Plus users, is now available to all Shopify plans.

Oxygen is an excellent tool for engineers who want a seamless deployment and hosting experience. By keeping your storefront within Oxygen, you can not only reduce your infrastructure costs, but also have access to a fantastic developer experience that includes:

* Preview environments for testing changes in isolation.
* Custom environments (e.g., if you want a staging area).
* Version control and GitOps for your storefront.
* A Content Delivery Network (CDN) powered by Shopify.
* Support for both backend and frontend code.
* CI/CD via GitHub Actions and the Hydrogen channel.

If you’re familiar with Vercel, you’ll find that Oxygen offers a very similar development experience, but more accurately tailored to the needs of Shopify developers.

## Migrating from Hydrogen v1 to Hydrogen v2

If you are using Hydrogen v1 today, there’s a [handy migration guide](https://shopify.dev/docs/custom-storefronts/hydrogen/migrate-hydrogen-remix) in the Hydrogen docs that you can follow to upgrade your storefront.

The process takes a lot of effort, but the guide is comprehensive and accurate, so you should be able to upgrade your Hydrogen app by simply following the steps outlined.

## Is Hydrogen Ready for Production Use Yet?

That depends on your risk tolerance!

On a technical level, both Hydrogen and Oxygen are most definitely production-grade products, and they are being used successfully in the wild by large Shopify stores such as [Allbirds](https://hydrogen.shopify.dev/case-studies/allbirds). The developer experience is pleasant and powerful, and Shopify’s hosting infrastructure will easily handle any production load you throw at it.

On the other hand, it’s unclear whether Hydrogen will see any more extensive refactorings, such as the one we’ve just witnessed. As an example, [Remix v2](https://remix.run/docs/en/main/pages/v2) will be released soon, bringing many improvements over its predecessor, but also requiring developers to upgrade to a new API and file naming convention. These changes will most likely affect Hydrogen users as well. It’s also unclear what synergies Shopify will create between Hydrogen and [Commerce Components](https://www.shopify.com/commerce-components), but we expect some movement there.

![](https://cdn.sanity.io/images/kqgmf0g2/production/e038f0246b07a894d83a8ae5cb1d3fe545d2bc6a-2960x2335.png?fit=clip)

Another factor to consider is how long it will take for the Shopify app ecosystem to catch up to Hydrogen’s philosophy. While some Shopify apps don’t need to worry about the frontend at all, others will have to expose an API or JavaScript SDK of some sort to be usable with a headless commerce architecture. We expect the situation to improve over the coming years, but there’s still a long way to go, and many Shopify apps today cannot be used with Hydrogen.

Overall, Hydrogen is well worth a try if you have the engineering firepower. It solves a significant number of problems for Shopify developers and gives brands unmatched flexibility in building a custom storefront, allowing them to create shopping experiences that would be very hard to replicate with Liquid themes.

However, if you’re a small brand and don’t have the resources to invest in experimental technology, you’re probably better off sticking with Liquid themes until Hydrogen becomes a true first-class citizen in the Shopify ecosystem.

Shopify Just Released Hydrogen v2. What’s In It for You?

While the total penetration of headless commerce in the US is still low, we have witnessed an increase in headless builds in recent years. And even though [we don’t believe headless is the end-all solution to all eCommerce problems](https://nebulab.com/blog/headless-commerce), we think it’s about time the industry realized the power of this architecture and started using it responsibly.

The only way for Shopify users to go headless for a long time was to implement their own single-page application from scratch, using a JavaScript library such as React (and hopefully a framework, such as Next.js). Shopify does provide SDKs to make the API integration work slightly more manageable, but that was about it: until recently, there was very little being done for performance, state management, personalization, or SEO.

In November 2021, Shopify released a developer preview of [Hydrogen](https://hydrogen.shopify.dev/), their new framework meant to address precisely these problems. Here at Nebulab, we’ve recently had the chance to take Hydrogen for a spin, and we want to share our learnings.

## What is Hydrogen?

Hydrogen is an open-source, React-based framework that can be used to build custom storefronts on the Shopify platform. It provides a lot of useful functionality:

* A sensible structure for your application code.

* eCommerce-specific components and pages.

* An SDK and hooks to interact with Shopify’s GraphQL-based [Storefront API](https://shopify.dev/api/storefront).

* It uses [Tailwind CSS](https://tailwindcss.com/) for styling.

* It’s optimized for high-performance builds.

Combined, these features almost entirely eliminate the amount of boilerplate code engineers need to write to build their storefronts and allow engineers to spend most of their time on functionality that truly moves the needle.

![Shopify Hydrogen website](https://cdn.sanity.io/images/kqgmf0g2/production/9865cb4da04e7cd861e38c97cc7015d8ea7a1e22-2560x2512.png?fit=clip)

## What are the pros of using Hydrogen?

For Shopify stores that want to go headless, Hydrogen is a huge help. As we’ve mentioned, it abstracts away all the complexity of integrating with the Shopify API and developing your storefront’s skeleton: all you need to do is clone the Hydrogen [demo store](https://shopify.dev/custom-storefronts/hydrogen/getting-started/templates#demo-store-template), configure it, then focus on styling and custom functionality. This alone is a huge productivity boost, and the developer experience has been outstanding in our experiments.

It’s also important to note that Hydrogen is officially developed and supported by Shopify, which should provide peace of mind to brands looking for a stable, robust solution that’s not going anywhere. While some Shopify-specific Next.js templates already existed before Hydrogen, they were mostly small, community-sponsored projects, which made them unsuitable for enterprise use.

## What are the cons of using Hydrogen?

Seasoned developers know that productivity comes with a hidden cost: the more a tool tries to abstract away technical complexity, the more opinionated it is. When it comes to Hydrogen, it’s exceptionally opinionated:

* It uses React server components.

* It uses streaming server-side rendering (SSR).

* It has built-in components, hooks, and caching mechanisms.

* It’s heavily coupled with Shopify’s Storefront API.

* If you need complete control over your React application, Hydrogen is most likely not a good candidate for you.

You should also know that some of these features are bleeding edge in the React ecosystem, and because Hydrogen is tightly coupled with Shopify, the community around it is still relatively small. Hydrogen brands can expect to have a harder time finding online resources and support, and they will have to tap into a smaller pool of agencies and engineers than if they used a more popular framework. That said, much of that will likely change as Hydrogen gains popularity.

Finally, most Shopify Apps and plugins were built to integrate with Liquid templates and won’t be compatible with Hydrogen (or other headless architectures, for that matter). If you rely heavily on specific apps and your app doesn’t provide an API your engineers can integrate with, you’ll need to switch to a headless-friendly alternative or build the functionality yourself.

## Can Hydrogen be used without Shopify Plus?

It’s complicated. The official answer is yes: since Hydrogen is an open-source project whose source code is available to anyone, and because none of the API endpoints it uses are restricted to Shopify Plus customers, at first glance, the framework can be used without Shopify Plus.

In reality, things are more nuanced.

![Shopify Oxygen documentation](https://cdn.sanity.io/images/kqgmf0g2/production/a893aabf4ed6f21f992598100837e4856353c79f-2560x1620.png?fit=clip)

First of all, there’s the matter of hosting your Hydrogen application. Plus users can host their Hydrogen app on [Shopify Oxygen](https://shopify.dev/custom-storefronts/oxygenhttps://shopify.dev/custom-storefronts/oxygen), Shopify’s proprietary hosting solution, which provides native support for directing users who visit your Shopify domain to your Hydrogen storefront.

If you don’t use Shopify Plus, you should still be able to deploy your Hydrogen app to other platforms, but it won’t be a painless experience. For example, Vercel has published a blog post announcing the availability of a [zero-configuration deployment for Hydrogen](https://vercel.com/changelog/hydrogen-projects-can-now-be-deployed-with-zero-configuration). But when we tested it, we had to manually tweak the environment variables used by Hydrogen to match the names used by Oxygen. This was a minor inconvenience overall, but it shows how support for Hydrogen is still in its infancy.

Once you’ve figured out the hosting, it’s time to deal with domains and DNS records. If you manage your domains through Shopify, Shopify will attempt to redirect any requests to your [myshopify.com](http://myshopify.com/) domain to your Hydrogen storefront, which will completely break the checkout. This could be easily solved by using a [routing domain](https://help.shopify.com/en/manual/domains/domain-type/routing-domain) which, ironically, is only available to Shopify Plus customers. (When we reached out to Shopify engineering about this catch-22-esque paradox, they seemed utterly taken aback by this realization.) The current solution is to set up your Liquid storefront to redirect to your Hydrogen storefront via JavaScript, which is far from ideal.

Another aspect to consider is support: in our experience, if you’re not a Shopify Plus customer, you’re only going to get extremely limited technical support from Shopify, with most requests being redirected to Shopify’s Discord community. No one in the Discord community seems to have much experience with Hydrogen, except for Shopify’s own employees, whose presence in the community is very erratic.

To be fair, Shopify did tell us that they are working to address these challenges and make Hydrogen truly available to non-Plus customers. However, _when_ this will happen exactly is unknown.

To sum it up, if you’re not on Shopify Plus and don’t have an experienced engineering team or agency backing you up, we would advise against using Hydrogen right now: you run the risk of spending weeks or months of development only to run into deal-breaking roadblocks.

![Shopify Discord](https://cdn.sanity.io/images/kqgmf0g2/production/ce5f2c4f4565702286b8a1df6cd0d17d418c8538-2560x2068.png?w=450)

## Who should be using Hydrogen?

Shopify’s Hydrogen framework is the perfect solution for online stores that are already running headless, or are planning to go headless, can count on a robust engineering team, and want to lean into a powerful, officially-supported solution that will spare them from boilerplate work. The developer experience is enjoyable, and most React engineers will be more than happy to work on a Hydrogen app.

If, on the other hand, you don’t have an experienced engineering team or don’t want to deal with the complexity that comes with a headless solution, Hydrogen is not a good choice: as much as it simplifies things, it will still require much more upkeep than a Liquid-based Shopify build.

At this point, Hydrogen is also a less-than-ideal solution for brands not on Shopify Plus due to missing functionality and limited support from Shopify. That is likely to change as the framework matures and becomes more widely available, so keep an eye out for any announcements from Shopify (and from us!).

If you’re considering going headless with Hydrogen or other frameworks, and are unsure of the implications, [feel free to reach out](https://nebulab.com/contact-us)! Our team has extensive experience and will help you make the choice that best supports your digital strategy.

Everything You Need to Know About Shopify Hydrogen

Alessandro Desantis

With unlimited digital estate, DTC brands can tell their stories, announce, entertain, educate, and keep their name front and center in customers’ minds, all of which is very hard to do in the limited shelf space afforded by wholesale partners. Now that even die-hard digitally-native brands are going omnichannel in pursuit of reach and profitability, **it’s paramount to double down on the exclusive capabilities of each channel to create complementary experiences—for DTC, content is one of the most obvious levers to pull**.

A slew of platforms has emerged over the past decade that promise to offer the definitive solution to all content management pains. These solutions provide functionality that covers the entire content management lifecycle, from writing to publishing, presentation, and SEO, but they do it in very different ways. In fact, we’ve seen at least four generations of content management tooling emerge in these years, all of which coexist today, serving different use cases and market segments.

For eCommerce operators, finding a North star to follow in this vastness can be tricky, and engineering teams are usually not much better off. If you haven’t been exposed to all these tools and understand the nuances of each, it’s easy to get lured in by the promise of unlimited flexibility and endless automation, only to find yourself stuck with a complex piece of software that requires weeks of integration work, or doesn’t play nice with your editorial workflow.

In this article, we will provide an overview of the content management space, as seen from the perspective of an eCommerce brand. You will learn the different types of tools you can use, their advantages and limitations, and some practical recommendations about which tool to adopt depending on your goal, use case, and growth stage. The goal is to equip you with all the knowledge you need to make an informed decision for your eCommerce brand.

## The four generations of content management

Different content management solutions have been launched in the last twenty years. While there’s no universal taxonomy, we can classify them under four categories: monolithic CMSs, headless CMSs, site builders, and page builders. In the following paragraphs, we’ll explore these different solutions, their pros and cons, and the leading players in each space.

### Monolithic CMSs

Monolithic CMSs were the first content management solution to emerge in the market. **These tools take over your entire content experience by handling every single aspect**: they provide an interface that allows you to edit and publish your content and present the content to your audience via a public-facing website.

You’ve probably heard about [WordPress](https://wordpress.org/), arguably the most popular CMS in the world. Initially built for blogging, WordPress has been expanded over the years to encompass an incredible number of use cases, allowing you to publish blogs, entire websites, and even online stores. It’s estimated that WordPress powers over 43% of all websites.

![WordPress website](https://cdn.sanity.io/images/kqgmf0g2/production/908b2d57d03ec193412387c8af8d151b6df2393b-2560x2136.png?fit=clip)

**Monolithic CMSs have been around for over fifteen years, and they’ve stood the test of time**. They offer a user-friendly, streamlined content editing experience and many plugins and apps that make them easy to repurpose for different use cases. Since they have a considerable market share, they also boast rich ecosystems of system integrators.

However, they also come with some limitations: th**ese content management systems are meant for content-centric websites, not for eCommerce brands.** They usually take over your entire website and don’t play nice with other parts of your tech stack. This makes them a less-than-ideal choice for a DTC brand, which needs to present the content on their storefront or even enrich it with dynamic data such as product information.

### Headless CMSs

Headless CMSs were built to solve precisely these limitations. **Compared to monolithic solutions, headless CMSs are much more nimble**: a headless CMS only provides an interface to define your content structure and manage your content. Presenting your content is up to you, and typically requires a design and engineering team to integrate the headless CMS into your existing frontend.

[Contentful](https://contentful.com/) has long been the primary contender in the headless CMS space, but many competitors have launched their solutions over the years: [Prismic](https://prismic.app/), [DatoCMS](https://datocms.com/), and [Sanity](https://sanity.io/) are among the most popular alternatives, offering slightly different functionality such as custom editorial workflows/UIs and internationalization, and wildly different price points.

![Contentful homepage](https://cdn.sanity.io/images/kqgmf0g2/production/551c31bc9b5a60be3f663151ba0172e06f790da5-2560x1810.png?fit=fill)

**Headless CMSs enable brands to treat content as data, making it fully portable and allowing them to present their content wherever they want**. Most headless CMSs also connect to your backend: for instance, an eCommerce brand will be able to pull product and pricing information from Shopify and include it right in the middle of an editorial piece. Such functionality allows you to blur the lines between content and commerce, making for a much richer customer experience.

Headless CMSs are still very popular thanks to their flexibility, but they come with their own limitations: mainly, **they require design and engineering work when marketers want to integrate new types of content into a company’s existing digital properties, or whenever they want to make visual changes to the existing experience**. This may be problematic for brands operating with low budgets or in high-velocity environments.

### Site builders

While site builders are not technically new (Webflow was born in 2012, one year before Contentful), they’ve seen a recent surge in popularity. You can think of site builders as a modern take on monolithic CMSs: like monolithic solutions, site builders also take over your entire website. However, **they offer more modern and advanced functionality**, such as support for drag-and-drop editing across your entire website, responsive design, custom code, API access, and integrations with popular third-party design and development tools. Almost all site builders also include a native headless CMS, or will optionally integrate with a third-party headless CMS.

The most popular site builder is [Webflow](https://webflow.com/), which is often used by SaaS companies to manage their marketing websites, or by eCommerce brands to spin up self-contained editorial experiences. Webflow also allows creating gated content and building Zapier-esque workflow automation. A recent competitor is [Framer](https://framer.com/), which allows designers to build, test and publish websites straight from Figma wireframes.

![Webflow homepage](https://cdn.sanity.io/images/kqgmf0g2/production/0082e34207f075b05269676c871a8d0d49b1601a-2560x2034.png?fit=fill)

**If your team has limited technical experience or you don’t want to use your engineering bandwidth, using a site builder can be an excellent way to quickly spin up new editorial experiences that will meet the standards of the modern Web.** And if you need to implement deeper customizations or complicated workflows, your engineers can still make those adjustments at a reasonable pace.

The main disadvantage with site builders is that, for all their flexibility, **they will still be pretty self-contained, and they’re hard to integrate with other digital properties.** Maintaining brand consistency will also be more challenging since your design system will live both in your site builder and across any other frontends you have. This is fine if you’re building a standalone experience such as a microsite, but can hurt your brand reputation when used for integrated experiences such as a company blog.

### Page builders

After coming full circle with site builders, the content management pendulum is swinging the other way once again with page builders. Like site builders, page builders also offer drag-and-drop editing, built-in headless CMSs, and all the modern developer tooling you might expect. **Unlike page builders, site builders try to be non-obtrusive: rather than taking over your entire website, they allow you to model specific pages or sections of it.** For example, you might let your eCommerce platform power your product catalog and checkout experience while your page builder powers your site navigation and blog.

The most popular page builder is [Builder.io](http://builder.io/), used by several eCommerce brands such as Everlane, J.Crew, and Harry’s. It allows you to use their native visual editor or to import your own components, connects with several third-party data sources, offers built-in A/B testing, and lets you publish your content across the Web, mobile, and wherever else you want. An early-stage contender is [Plasmic](https://plasmic.app/), which offers a very similar feature set, but pairs it with a more modern UX.

![Builder.io homepage](https://cdn.sanity.io/images/kqgmf0g2/production/29e681ed0cb541c8da8d8c65119b10cfe3f08b8d-2560x1528.png?fit=clip)

**Page builders can be an excellent compromise between headless CMSs and site builders**: they allow you to easily integrate your content into your existing digital properties in a non-obtrusive, brand-consistent way, and they offer a visual interface that helps non-technical stakeholders to quickly iterate on both content and presentation.

However, they are not a one-size-fits-all solution. **While an essential page builder integration can be a reasonably low-effort process for your engineering team, getting page builders right can be a complex initiative.** Once you start bringing in your own UI components, performing search engine optimization, running A/B tests, integrating with external data sources, or implementing rich user interactions, the level of complexity goes up dramatically, and keeping everything running smoothly can be a challenge.

## Evaluating the right solution for your brand

As you’ve seen, there’s no easy answer: each eCommerce CMS has its pros and cons, which you should weigh against your company’s stage, requirements, and technical savviness. The three main factors we keep into account when picking a solution for our clients are:

* **Business goals**: what do you want to achieve with your content? This is closely tied to where you’ll want to place your content, which in turn informs your choice of tooling. Are you looking to inform, inspire, or convert? (Often, it will be a mix of these, which is perfectly fine—just make sure you cover all your bases!)

* **Span of control**: site builders give operators maximum flexibility to change whatever they want, whenever they want it. This is both a blessing and a curse: a non-designer making design changes can quickly become a disaster. What’s the sweet spot between not enough and too much control for your team?

* **Implementation effort**: page builders are more complex to integrate than headless CMSs, which in turn are more complex to integrate than a monolithic CMS. Do the benefits outweigh the extra effort of integrating the solution with your tech stack?
Apparel brand and Nebulab client [Huckberry](https://huckberry.com/), for instance, relies heavily on their blog, [The Journal](https://huckberry.com/journal). The Journal is a fully integrated part of Huckberry’s shopping experiences: articles typically feature one or more Huckberry products, which users can add to their cart with a simple click. It’s a very conversion-centric approach.

![Huckberry’s blog, The Journal](https://cdn.sanity.io/images/kqgmf0g2/production/7ce46f90390f88961bbc568a2fafc78deb24b464-2560x2512.png?fit=clip)

Travel brand [Away](https://awaytravel.com/), on the other hand, publishes the travel and lifestyle magazine [Here](https://www.heremagazine.com/). Away’s magazine has a laid-back, inspirational approach with its content, and you can hardly notice that a DTC brand is behind the project.

![Away’s magazine, Here](https://cdn.sanity.io/images/kqgmf0g2/production/85383a0a4b600d7279c82359e0f0da9edf9209b8-2560x1664.png?fit=clip)

### Picking tools vs. building infrastructures

**Rather than only adopting one solution, we recommend creating a content management infrastructure, i.e., a suite of tools that integrate and build on top of each other.** For example, here’s a typical journey a DTC brand might undergo:

1. As a first step, they adopt a headless CMS, which allows them to decouple content and presentation. They use their headless CMS as the source of truth for all their content and integrate it with their existing digital properties (e.g., their product pages).

2. At some point, the marketing team starts complaining that they can’t make visual changes to how the content is presented on their product pages without asking the engineering team. This leads the team to integrate a page builder for specific website sections (e.g., the PDP and the blog). The page builder is connected to their headless CMS, which is still used for managing the actual content.

3. The brand eventually outgrows the page builder as well: the marketing team wants to start experimenting with standalone experiences such as microsites for contests, promotions, and product launches. This is when the team adopts a site builder, giving marketing full power to launch new properties with little to no engineering assistance.

**As marketing teams gain more freedom, brands need to create checks and balances to avoid brand dilution.** This can mean having a content inventory that is continuously monitored for consistency, ensuring the same person is orchestrating all digital experiences, or having a full-fledged design system that can be applied across different platforms. **Ultimately, how much centralization you need depends on your brand’s scale and your reliance on content.**

## Our favorite CMSs for eCommerce brands

At Nebulab, we have helped tens of brands design, launch and optimize their content stack, and we have developed some pretty strong opinions on which CMS platforms to use:

* **Monolithic CMS:** [WordPress](https://wordpress.org/). As mentioned, we rarely pick monolithic CMSs for eCommerce brands—but when we do, we go with WordPress. It has a beautiful, intuitive UX and an incredibly vast ecosystem of plugins and integrations, making it a good fit for many use cases and deployment options.

* **Headless CMS:** [Sanity](https://sanity.io/). A few years ago, we would have recommended Contentful or Prismic ([and we have](https://nebulab.com/blog/five-no-code-ecommerce-management-tools#the-best-headless-cms-prismic)). Ever since we’ve had a chance to try Sanity, we fell in love with its flexibility. While traditional headless CMSs force users to use a standardized UI for managing content, Sanity’s content studio is open-source and can be tailored to your content management needs and editorial workflows.

* **Page builder:** [Plasmic](https://plasmic.app/). While Builder.io has been around for slightly longer, Plasmic offers a more modern UI for their editing backend. With that said, the two tools are incredibly similar, so we encourage you to experiment with both and see which one you prefer.

* **Site builder:** [Webflow](https://webflow.com/). Even though products like Framer offer a more streamlined experience for non-technical users, Webflow remains an incredibly powerful tool if you know how to use it. With support for custom workflows and gated content, your team can quickly spin up rich micro-sites that cover various use cases.

As always, your mileage may vary. Before committing to a solution, you should thoroughly assess your present and anticipated requirements and experiment with different setups to build a stack that can scale with you as your needs evolve. If you need any advice or want to speed up the process, [we’re happy to help](https://nebulab.com/contact-us)!

Building Content Infrastructures for eCommerce Brands

As funding for headless commerce platforms reached a staggering [$1.6 billion](https://www.forbes.com/sites/forbestechcouncil/2021/05/11/why-is-headless-commerce-getting-16-billion-in-funding/?sh=5322b28f513a) in 2021, these systems aren’t to be ignored. But how exactly do they compare to the so-called traditional “monolithic” eCommerce platforms, and when should you pick one over the other?

This guide will explore the headless commerce model, its benefits, how it differs from the all-in-one monolithic commerce system, and when it’s a good option for your brand.

## What is headless commerce and how does it work?

Headless commerce is an eCommerce architecture where the frontend layer, or presentation layer, is decoupled from the backend commerce functionality.

Before we continue, let’s review the key differences between the frontend and backend:

* **Frontend:** This is the user interface. Customers see and interact with the frontend, whether they’re accessing your eCommerce site, shopping app, digital kiosk or other shopping channels.

* **Backend:** The backend is the behind-the-scenes, technical side of an eCommerce store the customer doesn’t see. The backend includes the technologies and tools that run in the background to ensure customers can shop and [have smooth checkouts](/blog/one-page-checkout-with-spree).

In headless commerce, the frontend and backend systems communicate via Application Programming Interfaces (APIs). This approach allows you to update the frontend, the customer-facing part of your site, independently of the backend and even use different development frameworks. This separation of concerns offers several benefits which we’ll explore below.

Examples of headless eCommerce solutions are Commerce Layer, Swell, and Nacelle.


## 4 benefits of headless commerce

![Woman lying on a couch and using a laptop](https://cdn.sanity.io/images/kqgmf0g2/production/96998b94bc1edf8908d27f5af24b1a34e88c56a8-1200x797.jpg?fit=clip)

Platforms that adopt a headless architecture offer several benefits compared to monolithic, or so-called traditional eCommerce platforms. Here are the top four advantages.

### 1. Omnichannel capabilities

In an omnichannel eCommerce experience, customers can start shopping on one channel or device and transition seamlessly to a different channel while the brand retains key information: common examples are a customer completing their purchase online, but selecting in-store pickup, or a customer buying something in-store and having the order show up their online order history.

Headless commerce makes it easy to serve the [74% of shoppers](https://www.salesforce.com/content/dam/web/en_us/www/documents/research/salesforce-state-of-the-connected-customer-4th-ed.pdf) who use multiple channels to shop: because the same backend system can serve multiple storefronts, you can easily adapt customer touchpoints and shopping experiences to serve your eCommerce website, your mobile app, social media pages, and even physical locations. All will be completely integrated and feel seamless for your customers to interact with.

### 2. Technical flexibility

By decoupling backend and frontend, headless platforms allow your development team to pick the frontend stack, including third-party providers, that they’re most productive with. A headless architecture allows you to adopt your favorite content management system (CMS) to create rich editorial experiences, or elevate your storefront through progressive web apps (PWAs). This enables you to create engaging digital experiences that don’t face the limitations of traditional monolithic frontends.

When done right, headless architectures even allow you to refactor or completely replace entire parts of your backend with little to no impact on your frontend experience(s), which allows you to move and experiment much more quickly.

### 3. Superior personalization

Most monolithic eCommerce platforms severely limit your ability to personalize the customer experience by forcing you to work with proprietary templating language and preventing you from accessing customer data. With [80% of customers](https://www.epsilon.com/us/about-us/pressroom/new-epsilon-research-indicates-80-of-consumers-are-more-likely-to-make-a-purchase-when-brands-offer-personalized-experiences) indicating they prefer brands that offer tailored experiences, eCommerce personalization is now table stakes for modern brands.

Headless platforms allow you to not only leverage basic eCommerce data, such as a customer’s profile and order history, but even augment it with brand-specific data points of your own. This allows you to create shopping experiences that feel built for your customer, boosting customer engagement, conversion rates and AOV.

### 4. Blazing fast performance

Storefronts that leverage a headless eCommerce platform can typically be deployed as static sites and put behind a global content delivery network (CDN) such as Cloudflare. In the hands of a capable development team, this can lead to incredible performance that would be hard to achieve with a monolithic platform.

A 2019 study by Portent has found that improving your loading speeds can boost your conversion rates [anywhere from 1.5X to 2.5X](https://www.portent.com/blog/analytics/research-site-speed-hurting-everyones-revenue.htm)! If your eCommerce site loads slowly, you are leaving lots of money on the table—literally.

## 3 drawbacks of going headless

![Four programmers working at same office's table](https://cdn.sanity.io/images/kqgmf0g2/production/0afcfb4759febba635d79b5004c9a4cf4c8c2242-1200x800.jpg?fit=clip)

In some cases, a headless build can lead to an unnecessarily complex architecture that causes more problems than it solves. Evaluating which eCommerce platform to use for your business needs is a complex process that should take into account both short-term and long-term factors as well as your budget and internal capabilities.

Here are three drawbacks of headless eCommerce platforms.

### 1. Technical capabilities

Launching a headless storefront requires you to create an in-house engineering team or hire an eCommerce agency for the long term. Headless sites require more ongoing maintenance to keep the lights on: Dependencies need to be updated, infrastructure needs to be maintained, and the site needs to be continuously monitored for bugs and performance issues.

In our experience, this additional effort has its upsides: It forces brand operators to get into a continuous optimization mindset, where they’re constantly identifying and capitalizing on new technology and other opportunities that can improve the shopping experience. Monolithic platforms, on the other hand, encourage a less intentional set-and-forget approach, which is definitely easier to execute, but also worse positioned for long-term scalability.

### 2. Time-to-market (and cost!)

Headless builds are typically associated with slightly higher timelines than monolithic builds. Adopting a headless architecture requires a significant investment in an agency or an in-house development team that will build your storefront, and this process can take anywhere between 2 and 4 months, depending on the complexity of the build.

Conversely, launching a store on a monolithic platform can be a much faster process with more competitive pricing, if you’re willing to settle for a more standardized look and purchase experience. This can be an acceptable compromise for smaller mom-and-pop businesses, but certainly not for a direct-to-consumer (DTC) brand with large long-term aspirations.

### 3. Integration effort

Headless eCommerce platforms are very flexible because you have full freedom to implement your storefront however you want. Unfortunately, this also means that many of the integrations and plugins that you can use out of the box with a monolithic platform will require a bit more work to be integrated in a headless architecture.

If you want to add reviews to your headless eCommerce website, for instance, you’ll need to work with your designers and engineers to figure out what the experience should look like, where to place the reviews, when to ask for them etc., and then implement and test the new functionality.

Ultimately, this extra effort is a good thing: A headless system asks you to be more disciplined and intentional in how you modify your storefront. This will force you to approach all initiatives with a critical eye rather than jumping from trend to trend, but it can be frustrating if you’re used to installing a plugin and forgetting about it.


## The verdict: headless or monolithic?

![Woman holding a credit card and using a phone](https://cdn.sanity.io/images/kqgmf0g2/production/cb3e8d957a2c46acdf1eda32e9cecd9c5173bf13-1200x800.jpg?fit=clip)

The answer is: It depends on the use case. There’s no right or wrong answer.

While a headless commerce architecture has myriad benefits over monolithic architectures, it’s not ideal in all contexts. In certain scenarios, a headless commerce approach is the best way to build your vision and drive superior brand performance, while in others, you’re better off with a monolithic architecture that saves you time and money.

Headless commerce solutions might be right for:

1. **Brands that want to offer a consistent customer experience across channels:** Any brand that wants to deliver consistent customer experiences regardless of channels or devices should consider adopting this architecture.

2. **Brands that feel their current platform is too rigid and restrictive:** If you’ve ever felt your platform is limiting on the backend or frontend, it’s time to switch to a flexible headless setup.

3. **Brands that put personalization front and center:** If personalizing the shopping experience is critical for your brand’s strategy, then you should explore the capabilities that a headless build will unlock for your development team.

4. **Online stores that have slow-loading pages:** If sluggish pages have been a pain point for your eCommerce store, a headless architecture may be able to help by allowing you to leverage a more robust frontend ecosystem.

On the other hand, monolithic builds are a good solution for:

1. **Brands with limited technical know-how:** Headless commerce requires stronger technical capabilities which might not be everyone’s cup of tea. If you want to launch a commerce website without dealing with the underlying technicalities, headless is not for you.

2. **Brands with time-to-market or financial constraints:** If you’re on a tight timeline or a limited budget, a monolithic build will very often prove cheaper and quicker to launch than a headless counterpart.

3. **Brands that want ready-made functionality:** If you want to leverage ready-made features and integrations without thinking too deeply about how to integrate them in your shopping experience, a monolithic platform will give you more peace of mind.


## Need help picking the right platform?

![Entrepreneur using his phone and laptop](https://cdn.sanity.io/images/kqgmf0g2/production/97e367e0de824649a05070d381052e44e0ca20e4-1200x801.jpg?fit=clip)

Headless architectures allow teams to move faster, address changing consumer needs, improve the user experience, and capitalize on omnichannel opportunities, but they’re not ideal for all brands.

Nebulab can help your new digital brand pick the right eCommerce platform for a greenfield build, or help your established brand design the right tech stack for its next growth spurt. We offer full-service consulting throughout all stages of your eCommerce project.

[Reach out](/contact-us) to see how we can help you create a vision for your eCommerce experience.

Headless Commerce: The Good, The Bad, and The Ugly

Andrea Vassallo

In this article, we are going to show how you can create a [NextJs](https://nextjs.org/) project with [Storybook](https://storybook.js.org/) and [TailwindCSS](https://tailwindcss.com/).

Before starting, I want to explain who are the actors and why it should be better adding them to our frontend application.

### NextJS

[NextJS](https://nextjs.org/) doesn’t need a lot of presentation. If you are here, you probably already know what NextJs is and why we should use it to build robust applications.

NextJs is a great [React](https://it.reactjs.org/) frontend framework, and it’s mainly used to build SEO-friendly applications since you can use three different types of rendering/pre-rendering methods:

* SSG (Static-site generation) the HTML is generated at build time and will be reused on each request,

* SSR (Server-side rendering) the HTML is generated on each request using a node server, so the response is SEO-friendly.

* CSR (Client-side rendering) the normale React behavior, the response is simply Javascript run by the client.

### TailwindCSS

Tailwind is one of the most powerful libraries to build your application style using HTML classes. [TailwindCSS](https://tailwindcss.com/) implements a ton of dynamic classes which apply different style rules to your application, and it is fully customizable using the configuration file!

Initially it will take time to understand which are the correct classes you need to use to build your interface, but one of the coolest thing in Tailwind is its super documentation.

By the way, the 2.0 version has recently been released with a lot of new features.

### Storybook

[Storybook](https://storybook.js.org/) is a great library that is mainly used to render our application components outside the NextJs environment. This means that you can check your components UI without making real queries or fetching data. You can also figure out how the application components change based on the passed props.

Storybook is more powerful when used with well-organized components, for example, using [Atomic Design(https://bradfrost.com/blog/post/atomic-web-design/).

**Example**

You will probably create your custom `Button` component in your project that will be rendered differently based on the passed props or the fetched data. With Storybook, you can check all the UI changes applying custom props from the Storybook panel or stubbing all your requests.

### TL;DR

Here you can find the fully configurated [project](https://github.com/nebulab/nextjs-storybook-tailwindcss)

## Let’s start!

For this article, I won’t split the application into components to be more direct. It would be best to do it in a real application to avoid using the `index.js` page directly.

The best practice is writing components splitting them by context using a great file structure:

* React documentation about components: [link](https://it.reactjs.org/docs/components-and-props.html#extracting-components)
* Atomic Design pattern about components structure: [link](https://bradfrost.com/blog/post/atomic-web-design/)

### Create the NextJS app

First of all, run this command to create your NextJs project:

```
npx create-next-app --use-npm nextjs-storybook-tailwindcss
```

and navigate inside the project directory with `cd nextjs-storybook-tailwindcss`.

### Run your application

```
npm run dev
```

### Refactor the default code

The `create-next-app` command creates the project with some unnecessary configuration since we’ll use **TailwindCSS** to build our style.

Replace the content in `pages/index.js` with:

```
const Home = ({ article, showImage }) => {
  if (!article) return "The article wasn't found!"

  const {author, company, image_url, content} = article

  const Image = showImage ? (<img className="w-24 h-24 rounded-full mx-auto md:flex md:self-center"
    src={image_url} alt="A beautiful cat" width="200" height="200" />) : ''

  return (
    <div className="w-96 mx-auto">
      <div className="h-screen flex items-center">
        <figure className="lg:flex bg-gray-200 rounded-xl p-8 lg:p-4">
          {Image}
          <div className="pt-6 lg:p-4 text-center lg:text-left space-y-4">
            <p className="text-lg font-semibold">{content}</p>
            <figcaption className="font-medium">
              <div className="text-blue-600">{author}</div>
              <div className="text-gray-500">{company}</div>
            </figcaption>
          </div>
        </figure>
      </div>
    </div>
  )
}

Home.defaultProps = {
  showImage: true
}

export const getServerSideProps = async () => {
  const response = await fetch('http://localhost:3000/api/article')
  const data = await response.json()

  if (!data) return { props: {}}

  return {
    props: {
      article: data
    }
  }
}

export default Home
```

Add your first API:

```
touch pages/api/article.js
```
```
const Article = (_, res) => {
  res.statusCode = 200
  res.json({
    id: 1,
    author: 'Andrea Vassallo',
    company: 'Nebulab',
    image_url: 'http://placekitten.com/200/200',
    content: 'The cat is a domestic species of small carnivorous mammal.'
  })
}

export default Article
```

Remove the CSS file: `styles/Home.module.css`:

```
rm styles/Home.module.css
```

![Nextjs without style result](https://cdn.sanity.io/images/kqgmf0g2/production/cf125dfe5106852987ebfd778e133fe4566ef324-537x357.png?fit=clip)

![Man pointing thumb down](https://cdn.sanity.io/images/kqgmf0g2/production/f804d6533a925773c96bc9055cd7aae96d76c578-640x480.gif?fit=clip)

The result is an ugly and boring HTML page.

**Let’s go applying our awesome style.**

### Install TailwindCSS

*Why the documentation isn’t enough in this case?*

Because NextJS came up with a bunch of pre-configured services like Babel and [PostCSS](https://postcss.org/) and we have to TailwindCSS with them.*

Reading the [TailwindCSS documentation](https://tailwindcss.com/docs/installation), you’ll see that we need three different libraries to complete the installation:

* tailwindcss

* postcss

* autoprefixer

We don’t need to install postcss and the autoprefixer libraries since they are already installed in NextJs.

Run these commands to install TailwindCSS:

```
npm install --save-dev tailwindcss
```

Unfortunately, we can’t use `npx tailwind init` to create the configuration file since it’ll check if you have installed the `autoprefixer` library.

Let’s create the configuration file adding the `tailwind.config.js` file:

```
touch tailwind.config.js
```

with the default configuration:

```
module.exports = {
  purge: [
    // This is not present inside the default configuration
    // but it's good to build your production application
    // Read more about this here: https://tailwindcss.com/docs/installation#building-your-css
    './pages/**/*.js',
  ],
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}
```

### Configure PostCSS

To configure PostCSS we have to override the [NextJs default one](https://nextjs.org/docs/advanced-features/customizing-postcss-config):

Install the dependencies:

```
npm install --save-dev postcss-flexbugs-fixes postcss-preset-env
```

Create the `postcss.config.js` file:

```
touch postcss.config.js
```

and fill it with the default configuration as well:

```
module.exports = {
  plugins: {
    'postcss-flexbugs-fixes': {},
    'postcss-preset-env': {
      autoprefixer: {
        flexbox: 'no-2009',
      },
      stage: 3,
      features: {
        'custom-properties': false,
      },
    },
  },
}
```

Add the `tailwindcss` plugin to the top of the plugin list:

```
module.exports = {
  plugins: {
    tailwindcss: {},
    ...
  },
}
```

### Include Tailwind in your CSS

Add these three lines of code to the top of this file: `styles/globals.css`:

```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

### We made it

Check your application homepage; the result should be similar to this one:

![Tailwind result](https://cdn.sanity.io/images/kqgmf0g2/production/8610b447fdcea90e798a8e33440326e498f8cbba-485x292.png?fit=clip)

![](https://cdn.sanity.io/images/kqgmf0g2/production/ef653b4c8ced24daaf9d3b865d207d11b7b905bb-700x394.gif?fit=clip)

## State of mind

From here on, it’ll be a breeze building beautiful component with Tailwind, but we need to answer a couple of questions about testing:

1. How is this component rendered when the article data isn’t found?

2. How can we check all the component variants at any moment without changing the code?

[Storybook](https://storybook.js.org/) will help us to accomplish both.

### Install Storybook

The default `npx sb init` command that is used inside the official documentation installs libraries that we don’t need and adds a bunch of files that we don’t use.

For that reason, I usually prefer to use the `from scratch` configuration.

```
npm install --save-dev @storybook/addon-actions @storybook/addon-essentials @storybook/addon-links @storybook/react
```

Add the Storybook commands inside the `package.json` scripts:


```
"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "storybook": "start-storybook -p 6006",
  "storybook:build": "build-storybook"
}
```

Copy this piece of code inside the `.storybook/main.js` file

```
module.exports = {
  "stories": [
    // Paths to the story files
    "../pages/*.stories.mdx",
    "../pages/*.stories.js",
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials"
  ]
}
```

Copy this piece of code inside the `.storybook/preview.js` file

```
// Import the global style enabling tailwind classes
import '../styles/globals.css'

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
}
```

### Add a story

For each page or component that we want to tell using a `story`, we need to create a file called `component-name.stories.js`.

In this case, we want to create the `index.stories.js` inside the `pages` dir:

```
import Article from './index';

const articleMock = {
  id: 3,
  author: 'Dave Canterbury',
  company: 'Bushcraft 101',
  image_url: 'https://via.placeholder.com/200/200',
  content: 'David Michael Canterbury born September 19, 1963 is a survival expert'
}

const Story = (props) => <Article {...props} />

// Here we export a variant of the default template passing props
export const ArticleStory = Story.bind({})
ArticleStory.args = {
  article: articleMock,
};

// Here we export a variant of the default template passing props
export const EmptyArticleStory = Story.bind({})
EmptyArticleStory.args = {
  article: null,
};

// Here we export the default component that
// will be used by Storybook to show it inside the sidebar
export default {
  title: 'Article',
  component: Article,
  argTypes: {
    showImage: { control: 'boolean' },
  },
};
```

### Run the Storybook server

```
npm run storybook
```

![Storybook result with style](https://cdn.sanity.io/images/kqgmf0g2/production/6b98a19deccff277aaa00d736aff13aa969a23ac-846x906.png?fit=clip)

At the time of writing there is a chance you might run into this [bug](https://github.com/storybookjs/storybook/issues/12668). You can fix it with this [solution](https://tailwindcss.com/docs/installation#post-css-7-compatibility-build).

## That's all

Your project is ready to be built using a robust framework and beautiful style with an easy way to check component behavior in isolation!

I hope that you found this article helpful and easy to read.

Do you need the [Typescript](https://www.typescriptlang.org/) version? Let us know with a comment.

### Follow up story - use TailwindCSS and Storybook with SCSS

NextJS side this isn’t a problem, you need just to install the `scss` library using `npm`.

```
npm install sass
```

Rename the `styles/globals.css` to `styles/globals.scss` and fix the `_app.js` and `.storybook/preview.js` style imports.

and replace the TailwindCSS style import from this:

```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

to this:

```
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";
```

**And Storybook?**

![Storybook SCSS error](https://cdn.sanity.io/images/kqgmf0g2/production/59838f648762570d289c5201a0bf7848015ae22e-1042x410.png?fit=clip)

It seems that Storybook doesn’t recognize the SCSS syntax, and for this reason we need to extend the library [Webpack](https://webpack.js.org/) configuration adding the `sass loader`.

The Webpack loader is used starting from the end, and this means that the `sass-loader` should be added at the end of the loader list.

Here you can find the `.storybook/main.js` file with the correct configuration:

```
module.exports = {
  stories: [
    // Paths to the story files
    "../pages/*.stories.mdx",
    "../pages/*.stories.js",
  ],
  addons: ["@storybook/addon-links", "@storybook/addon-essentials"],
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.scss$/,
      use: [
        "style-loader",
        "css-loader",
        "postcss-loader",
        // Add the sass loader to process scss files
        "sass-loader",
      ],
    })

    return config
  },
};
```

Using Tailwind and Storybook with Next.js

Francesco Michelini

Like all web developers, I love to experiment with new tools, libraries and frameworks.

This time, for one of my side projects (my new portfolio), I decided to use [NuxtJS](https://nuxtjs.org/), which is a framework built on top of VueJS that allows to build SPAs and static websites blazingly fast, and [Prismic](https://prismic.io/), which is a Cloud headless CMS.

I've been using WordPress for years, but recently I've started working with VueJS and Nuxt on other projects, and not much time passed before deciding to build my new portfolio with Nuxt, mostly because of VueJS' ease of use.

But having a static website means that whenever I want to update it I have to:

- Open my code editor
- Make all the changes needed
- Commit to my repository
- Upload the updated/new files to the server

Not the ideal situation to be honest; I wanted to have a static website but manage its content without writing code, this is why I decided to add Prismic to the project.

By using Prismic, I can have a static website that fetches its content from an API; sounds perfect!

But there's a downside: whenever I add new content (a blog post or a case study), I still have to add the new content's page to the site's source code, meaning I'm back at the starting point.

The solution is quite simple: during the generation of the site, I tell Nuxt to make calls to the Prismic API and dynamically create those pages.<br>
Doing so, I don't have to write a single line of code anymore, bingo!

But I wanted to push it a bit further because it's true that this mechanism works, but every time a page is visited it makes a call to the Prismic API to fetch the content; this is pretty useless, and on a large scale website it can become costly.

I mean that I wanted to make those API calls only when generating the website, creating a completely static website, and at the same time having a CMS to manage its content.

> "But how do I regenerate the website everytime I update the content?"

The website is hosted on [Netlify](https://www.netlify.com/) and I've configured a webhook that whenever is triggered by Prismic it regenerates the whole website.

It's really easy to configure:

- [Create an incoming webhook on Netlify](https://www.netlify.com/docs/webhooks/#incoming-webhooks)
- [Configure webhooks on Prismic](https://user-guides.prismic.io/webhooks/webhooks)

## TL;DR;

You can find the code in [this GitHub repository](https://github.com/kekkorider/nuxt-prismic-app).

There's also a [demo available](https://determined-panini-7baf61.netlify.com/).

### 01. Creating the NuxtJS app

[Creating a new NuxtJS application](https://nuxtjs.org/guide/installation#using-code-create-nuxt-app-code) is pretty straightforward, all you have to do is open your terminal and launch

```
yarn create nuxt-app <my-project>
```

At this point, `nuxt-create-app` asks a couple of questions like the project's name, description, server, UI framework to use and so on

![create nuxt app command](https://cdn.sanity.io/images/kqgmf0g2/production/af880aca6b4ee5b59f337269f484bb799c506e21-1378x1162.png?fit=clip)

The next step is to `cd` into the project's folder and run

```
yarn run dev
```

and voilà, the new application is running at `http://localhost:3000/`.

![nuxt app created](https://cdn.sanity.io/images/kqgmf0g2/production/708e9deec984925fd5b91f6bb498f74cd4e1e411-1309x777.png?fit=clip)

## 02. Creating the Prismic backend

The website will be quite standard: it will have a homepage, an about page, a list of posts and an X amount of single post pages.

Let's start by [logging in into our Prismic account](https://prismic.io/dashboard) and create a new repository with three content types:

- Homepage (single type)
- About page (single type)
- Blog post (repeatable type)

### Important note

When creating the `Blog Post` content type, make sure you set up a `UID` field, it will be the slug of each post.

Noticed that I haven't set up a "Posts index" custom type? That's because I'll setup Nuxt to create that page when generating the website.

With the content types created, the custom types list will look like this

![prismic custom types list](https://cdn.sanity.io/images/kqgmf0g2/production/0b783ae71d8acfd1e8ef1a80812ba000b3d670b0-1189x634.png?fit=clip)

Now, let's fill in some content in the **Content** section

![prismic content created](https://cdn.sanity.io/images/kqgmf0g2/production/db99fbc5dd003154187e4af8409664c014ddd44c-1230x675.png?fit=clip)

## 03. Set up Nuxt to retrieve content from Prismic

The first thing to do is to add the `prismic-javascript` and `prismic-dom` modules, which are the two libraries that allow to query and parse content from Prismic.

Install `prismic-javascript` and `prismic-dom` by running

```
yarn add prismic-javascript prismic-dom
```

and then create a `prismic-config.js` file at the root of the project with the following content:

```javascript
// prismic.config.js
import Prismic from 'prismic-javascript'
import PrismicDOM from 'prismic-dom'
const config = {
  baseUrl: '<API_ENDPOINT>',
  access_token: '<ACCESS_TOKEN>'
}
export const initApi = req => {
  return Prismic.getApi(config.baseUrl, {
    accessToken: config.access_token,
    req: req
  })
}
export const linkResolver = doc => {
  if (doc.type === 'blog_post') return `/blog/${doc.uid}`
  return `/${doc.uid}`
}
export const generatePageData = (documentType, data) => {
  switch (documentType) {
    case 'homepage':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
    case 'about_page':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
    case 'blog_page':
      return {
        posts: data
      }
    case 'blog_post':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
  }
}
```

This file contains the Prismic's configuration and a couple of functions that are used in every template to initialize the APIs (`initApi`) and generate each page's content (`generatePageData`)

The Prismic `API_ENDPOINT` can be found in `Settings -> API & Security -> API Endpoint`.

An `ACCESS_TOKEN` is required only if the backend is set as `Private` in `Settings -> API & Security -> Repository security`

Now, open the `nuxt.config.js` file and add the following code:

```javascript
// nuxt.config.js
const Prismic = require('prismic-javascript')
import { initApi } from './prismic.config'
module.exports = {
  ...
  generate: {
    routes: function() {
      // Fetch content for the homepage and generate it
      const homepage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'homepage'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: '/',
                payload
              }
            })
          })
      })
      // Fetch content for the about page and generate it
      const aboutPage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'about_page'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: '/',
                payload
              }
            })
          })
      })
      // Fetch all the blog posts to generate the Blog page
      const blogPage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return [{
              route: `/blog`,
              payload: response.results
            }]
          })
      })
      // Fetch again all the blog posts, but this time generating each post's page
      const blogPosts = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: `/blog/${payload.uid}`,
                payload
              }
            })
          })
      })
      // Here I return an array of the results of each promise using the spread operator.
      // It will be passed to each page as the `payload` property of the `context` object,
      // which is used to generate the markup of the page.
      return Promise.all([homepage, aboutPage, blogPage, blogPosts]).then(values => {
        return [...values[0], ...values[1], ...values[2], ...values[3]]
      })
    }
  },
  ...
}
```

What the code above does is pretty simple: it queries all of our custom types (`homepage`, `about_page` and `blog_post`) from Prismic and passes the data to our templates.

## 04. Create templates and components

I'll try to explain all of these templates and components, but you can just copy-paste them in their respective locations.

```html


<template>
  <nav class="nav">
    <nuxt-link to="/">Logo goes here</nuxt-link>
    <ul class="nav-links">
      <li class="nav-link"><nuxt-link to="/">Homepage</nuxt-link></li>
      <li class="nav-link"><nuxt-link to="/about">About</nuxt-link></li>
      <li class="nav-link"><nuxt-link to="/blog">Blog</nuxt-link></li>
    </ul>
  </nav>
</template>

<style scoped>
.nav {
  align-items: center;
  display: flex;
  justify-content: space-between;
  padding: 20px;
}
.nav-links {
  list-style-type: none;
  margin: 0;
  padding: 0;
}
.nav-link {
  display: inline-block;
  margin-left: 20px;
}
</style>
```

☝ The navigation top bar

```html


<template>
  <div>
    <main-nav/>
    <nuxt/>
  </div>
</template>

<script>
import MainNav from '@/components/MainNav.vue'
export default {
  components: {
    MainNav
  }
}
</script>


<style>
html {
  font-family: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI',
    Roboto, 'Helvetica Neue', Arial, sans-serif;
  font-size: 16px;
  word-spacing: 1px;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: antialiased;
  box-sizing: border-box;
}
body {
  background-color: #fafafa;
  margin: 0;
}
a {
  text-decoration: none;
  color: #5CBEFD;
}
*,
*:before,
*:after {
  box-sizing: border-box;
}
</style>
```
☝ The default layout with common styles

```html


<template>
  <section class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </section>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('homepage', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'homepage'))
          .then(response => {
            return generatePageData('homepage', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ Our homepage.

As you can see, I've set up an `asyncData()` method. This method is [part of NuxtJS](https://nuxtjs.org/api/) and is responsible for fetching the data before rendering the page.

Inside of `asyncData()` I check if the `context` object has the `payload` property (if the `yarn generate` script is running).

If so, we directly return the data using the `generatePageData()` function I created in `prismic.config.js`.

But the `payload` is only available when I'm generating the site using `yarn generate`, during development `payload` doesn't exist, so we have to fetch our data from Prismic first and then return the data with `generatePageData()`.

```html


<template>
  <section class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </section>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('about_page', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'about_page'))
          .then(response => {
            return generatePageData('homepage', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ The About page, same as the homepage

```html
// pages/blog/index.vue

<template>
  <div class="container">
    <h1>Blog page</h1>
    <hr>
    <article class="post" v-for="(post, index) in posts" :key="index">
      <header>
        <h1>
          <nuxt-link :to="`/blog/${post.uid}`">{{ "{{" }} "{{ "{{" }}" }} Dom.RichText.asText(post.data.title) }}</nuxt-link>
        </h1>
      </header>
    </article>
  </div>
</template>

<script>
import Prismic from 'prismic-javascript'
import PrismicDOM from 'prismic-dom'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  data() {
    return {
      Dom: PrismicDOM
    }
  },
  asyncData(context) {
    if (context.payload) {
      return generatePageData('blog_page', context.payload)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return generatePageData('blog_page', response.results)
          })
      })
    }
  }
}
</script>
```
☝ The blog page.

Here, the code inside the `asyncData()` method is a bit different from the one of Homepage or the About page; that's because there's an **array of contents**.

The difference here is that we do not pass the `data` property of the `payload` to `generatePageData()`, but directly the `payload`.

Also, we include the `PrismicDOM` library to the component's `data`, so that we can use it to print all our contents into the template by writing

```javascript
Dom.RichText.asText(post.data.title)
```

where needed.

(Yes, I _could_ avoid using the `PrismicDOM` library, but in that case we have to write something like `post.data.title[0].text[0]`)

```html


<template>
  <div class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </div>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('blog_post', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('my.blog_post.uid', context.params.slug))
          .then(response => {
            return generatePageData('blog_post', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ The single post template

First of all, did you notice the file structure? The folder's name starts with an underscore, that means that its name will be auto-generated via our configuration in `nuxt.config.js`.

For our single posts we wrote

```javascript
route: `/blog/${payload.uid}`
```

This means that `_slug` will be replaced with the `UID` of our post, resulting in a tree that will look like this:

```
/root
  /blog
    /post-01
      index.html
    /post-02
      index.html
    /post-03
      index-html
```

## Conclusion

You did it, you've managed to create a NuxtJS website that fetches its content only during the build process (except for development of course).

This allows you to save a lot of bandwidth (and also money) because it only calls the APIs once per content type instead of every page load. Cool uh?

I hope you found this post useful, if you have questions, found a bug or just want say hi, leave a comment.

Creating a Blazing-Fast Nuxt.js Website with Prismic

There's no debate around the fact that good API design is an art. When we stumble into a properly
designed API, we can feel it. Just like good visual UIs, good APIs are not just beautiful, it's
functional and it saves everyone's time. With this mind, it's not a stretch to say that APIs are, in
fact, UIs. They're not just meant for machines either: since there are people programming and using
those machines, creating an API that users are delighted to interact with is a deliberate choice of
its development team, and one we ought to make.

There are many resources about design principles for visual UIs, as well as a lot of good examples
to take inspiration from. When it comes to APIs, on the other hand, there is a lot of documentation
explaining the different protocols, languages and frameworks for their implementation, but nearly
not enough material on the underlying principles and choices that make certain APIs a joy to work
with and others a complete nightmare.

While nothing can beat experience and each team comes up with their own rules for what makes an API
great, we can all benefit by applying some basic principles to the design of our APIs. These are
very abstract and can be implemented in many different ways, but they should always guide our
technical decisions.

## Consistency

Consistency means that similar endpoints should behave in similar ways, including in edge scenarios.
You should always strive to keep vocabulary, URL structure, request/response formats and error
handling consistent across your entire API.

This provides several benefits:

* It makes it much simpler to interact with your API, since users always know what to expect and
  don't have to read the documentation of every endpoint, but can simply go with their gut.
* It allows writing client libraries that don't know the exact schema of the API, just the rules
  you commit to respecting. The Stripe API client is a good example of this: because the structure
  of requests and responses is always the same, it can build objects dynamically and only needs to
  be updated when one of the API rules changes.
* It creates a set of battle-tested guidelines that you can abide by when you are implementing new
  features in the API. No more discussions around whether to use numeric IDs or UUIDs, because
  you'll just go with whatever you already have in place.

Consistency is probably the most impactful trait you can implement in the design of your API, and your users will love you for it.

## Performance

Performance in HTTP APIs is a tricky matter. Because APIs are not directly consumed by end users,
it's easy for performance issues to go unnoticed for a very long time, especially in the context of
server-to-server interactions. Unfortunately, because software is made for people, all types of
performance issues will eventually impact the end user.

I strongly advise against early optimization, for the usual reasons: it will slow down the
development of your MVP and you can't know what parts of your product need to be optimized without
having the right metrics in place first. You should optimize based on data, not instinct.

With that said, it is extremely important that you start collecting the data from day one. Setting
up an APM tool is a matter of seconds nowadays, and it will provide you with a ton of useful
information about how your API is being used in the real world.

## Documentation

No matter how consistent your API is, users will still need a place they can go to in order to get
started or obtain additional details about certain aspects or capabilities of the API.

Furthermore, API documentation should not just be about presenting request and response templates.
It's useful and recommended to add any information your users might find helpful, such as
explanations as to what happens in the background when a certain API call is made or what other
endpoints the user might need to complete the transaction at hand.

It is extremely important that your API documentation is accurate and up to date. The only way to
accomplish this is by creating a workflow to integrate documentation into your development process.
A good way is to check documentation into your VCS and require developers to update it whenever they
change the API.

Having developers write documentation might seem like a waste of time, but the more time you spend
documenting, the less time you'll spend answering questions and investigating bogus bug reports.

Finally, ensure the documentation is not just available, but a joy to consult. Since it is meant to
be consumed by humans, put extra care into the UI and UX of reading the documentation. Instead of
doing this yourself, you can just adopt a service such as [Stoplight](https://stoplight.io) that will store and present the content in a standard format for you.

## Usability

While there is nothing inherently wrong with having a 1:1 mapping between your database tables and
your API resources, you should know that this is not the only way to build an API. In fact, for
complex APIs, it's often not the best way, because it puts all the burden of stringing the right set
of operations together in the right order on the user's shoulders.

If you can simplify a business transaction to only require one API call instead of two, why not do
it? It would be unthinkable for a visual UI to require user input for every single operation that
happens in the background - and yet, that's exactly what we do in many APIs, when we ask our users
to do our work out of laziness.

One example of this is an API that allows users to add a new payment method and mark a payment
method as the default one. If we expect situations where the user wants to add a new method and
immediately mark it as default, we can add a mark_as_default attribute to the payment method
creation endpoint and do everything in one transaction without requiring two API calls. This saves
both development time and bandwidth.

This kind of simplification is not always possible: when you are not able to determine the exact use
cases of your API in advance (e.g. in the case of public APIs), you ought to be as flexible as
reasonably possible (in the example above, this would mean adding the field but also maintaining a
separate endpoint for setting the default payment method).

The rule of thumb is to consider all aspects of your API as means to an end, i.e. to complete a
business flow. How can you best help the user achieve that goal? Once you have that in mind, design
choices become much easier.

## Simplicity

Build your API on top of simple, universally accepted standards and tools. There's no need for
envelopes, schemas, API gateways or any other esoteric solutions unless you have very good reasons
for using them.

The HTTP RFC already provides you with most of the tools you'll need to build a Web service that is
reliable and interoperable, so [go
ahead and read it](https://tools.ietf.org/html/rfc2616#section-10.1.1) (yes, it's long, but I can guarantee it's worth it).

Stick to the basics and do them well. Simplicity means less overhead for humans and machines, as
well as less room for mistake. For instance, here's what it takes to charge a credit card using the
Stripe API:

```console
curl https://api.stripe.com/v1/charges \
  -u your_api_key: \
  -d amount=999 \
  -d currency=usd \
  -d description="Example charge" \
  -d source=tok_visa
```

It's so simple you can do it without looking up the documentation, and it's virtually impossible to
mess it up. This is the kind of simplicity you want to strive for.

(By the way, the Stripe API is an excellent example of thoughtful API design, so take a look at the
[API reference](https://stripe.com/docs/api) if you have some time.)

## Evolution

Traditional Web applications are updated all the time: new features are designed and added, popular
ones are improved and streamlined, unused ones are deprecated and removed. Users are accustomed to
living and operating in an environment that's constantly changing, sometimes quite dramatically.

Most of the time, products do a very good job of nudging users to adopt new features: newsletters,
in-app tours and good design practices ensure that the UX is never disrupted by the latest round
updates.

For APIs, on the other hand, it looks like there are only two possible options: either you never
change your interface for fear of breaking implementations, or you change it without notice,
disrupting the most of your customers' work. This happens because API teams are often disconnected
from their user base, since they don't interact with users directly.

But a third option is entirely possible: with the right infrastructure and tooling in place, you can
have an API that changes in a way that is manageable for its users. You can use metrics to make
informed decisions about the interface you expose to the world: how often is an endpoint used? What
users called a specific API endpoint in the last 6 months? Make sure you can always answer this kind
of questions, because they will allow you to evolve your API without making your users' day a
nightmare.

## Over to You!

Do you have any other principles that you apply when designing APIs? Or have you seen examples of
very well-designed APIs? We'd love to hear from you and discuss, just leave a comment below!

The Nebulab