In our work with e-commerce brands, we frequently encounter a common challenge: how do you build trust in systems that operate invisibly? While custom algorithms and automation solutions may be working flawlessly behind the scenes, both business teams and customer service representatives often struggle to confidently explain these processes to stakeholders and customers.

This scenario plays out repeatedly across e-commerce operations. While custom solutions deliver tremendous value, their invisible nature creates four critical challenges:

* Reduced trust in automated systems
* Limited opportunities for cross-team collaboration
* Increased support resolution times
* More difficult iterative improvements

The good news? We've developed several approaches to solve these visibility challenges, each suited to different business needs and constraints.

Let's explore each approach, starting with the quickest to implement and moving toward more comprehensive solutions. We'll share real implementation experiences and help you understand which solution might work best for your specific situation.

## 1. Tags

The simplest place to start is with Shopify's built-in tagging system. These lightweight markers can provide immediate visibility into system states and trigger automated processes. The beauty of tags lies in their simplicity – they're provided out of the box on Shopify and integrate seamlessly with existing workflows.

At Tannico, one of Italy's leading wine retailers, we use tags to control their product synchronization with their enterprise resource planning system. When products need to be synced, the operations team can simply add a specific tag, and our middleware picks up these tagged products for processing. This gives the team direct control over the sync process without needing to understand the underlying technical complexities.

## 2. Metafields

As your needs grow more sophisticated, metafields offer structured data storage capabilities that go beyond simple flags.

Again looking at our work with Tannico, we use metafields to store and control parameters for their third-party pricing engine. This allows the team to fine-tune pricing rules and see their effects directly within Shopify, making complex pricing management feel like a native part of their workflow.

While metafields require more planning and development effort than tags, they provide much richer data visibility without adding significant complexity to operations. They're particularly valuable when you need to store detailed configuration data or track complex states that can't be captured with simple tags.

## 3. Admin UI Extensions

When simple flags and data storage aren't enough, Admin UI Extensions offer a more sophisticated approach. These extensions allow you to create custom interfaces directly within the Shopify Admin, making complex operations more intuitive and accessible to your team.

[Our work with Cometeer](https://nebulab.com/case-studies/cometeer) serves as a perfect example of this approach. Their algorithm was making sophisticated decisions about which coffees to include in each box, considering factors like customer preferences, previous orders, and inventory availability. However, without visibility into this process, it was difficult for teams to understand and trust these selections.

![](https://cdn.sanity.io/images/kqgmf0g2/production/a6b7f0a08d0748f778e20893e2dbb0a5373d226f-1386x1050.png?fit=clip)

We transformed this "black box" system into a transparent one through a comprehensive Admin UI extension that visualizes the entire decision-making process. The results were remarkable: customer service representatives could now explain algorithm selection decisions, the time required for algorithm adjustments dropped as developers could now see exactly how their changes affected the selection process and, perhaps most importantly, non-technical team members began contributing valuable suggestions for improvements.

While this approach requires more initial investment in development time and resources than tags or metafields, it offers the most flexibility for complex interactions and rich data presentation.

## 4. Third-Party Platforms

As systems grow more complex, teams often need more sophisticated ways to interact with custom logic. While the previous solutions work well within Shopify's Admin interface, sometimes the best approach is to meet your teams where they already work by integrating with their daily platforms.

Many customer service and operations platforms like Zendesk and [Kustomer](https://developer.kustomer.com/kustomer-apps-platform/docs/widgets) provide robust API integration capabilities. This means you can surface key data from your custom Shopify solutions directly within these platforms and, more importantly, enable actions to be taken from there.

![](https://cdn.sanity.io/images/kqgmf0g2/production/15f920216eff929c332ecf67a9c340c42f28cd27-956x1168.png?fit=clip)

At [MeUndies](https://nebulab.com/case-studies/meundies), we integrated their custom subscription logic directly with their customer service platform. This meant that when handling customer inquiries, support teams could see relevant subscription data (like upcoming shipment dates and product preferences) and perform actions like skipping deliveries or updating preferences—all without leaving their familiar support interface. The integration eliminated constant switching between tools and made customer interactions more efficient.

The complexity of this approach varies based on the platform you're integrating with. Data exposure typically involves formatting and forwarding information through authenticated API requests. Enabling actions requires more setup as you'll need to create secure endpoints in your middleware to handle authenticated requests from the third-party platform. While this requires careful planning and ongoing maintenance, it can significantly streamline workflows for teams that spend most of their day in these platforms.

## 5. Custom Frontends

While the previous approaches cover most use cases we encounter, there are times when you need complete control over the user experience. In these situations, creating a custom frontend offers the ultimate in flexibility. Shopify provides robust support for embedding custom applications directly into the Admin Panel through their embedded app framework, with dedicated libraries for both Remix and Rails to handle the complexities of setup and authentication.

This approach gives you complete control over the user interface and functionality, allowing you to create exactly the experience your team needs. While we haven't found this level of customization necessary for most clients at Nebulab – the other solutions typically provide sufficient flexibility – it's worth considering for unique use cases that require specialized interfaces or workflows.

![](https://cdn.sanity.io/images/kqgmf0g2/production/53bfe0a056a980d2d3bc89539ca562d0f4993be7-2880x1620.png?fit=clip)

Development platforms like [Retool](https://retool.com), [Replit](https://replit.com) and [Gadget](https://nebulab.com/blog/building-shopify-apps-with-gadget) can significantly accelerate this process. Retool's drag-and-drop interface builder and pre-built components can reduce frontend development time by 50-70%, while Replit's collaborative development environment streamlines the iteration process. These platforms handle much of the foundational setup work, letting your team focus on building the unique features your business needs.

The trade-off here is still higher development effort and maintenance complexity compared to other solutions we've discussed, even with these acceleration tools. However, for organizations with highly specific needs or unique operational requirements, the investment can pay off through perfectly tailored workflows and improved team efficiency.

## Choosing Your Path

The best visibility solution for your organization depends on your specific needs and constraints. Here's a quick decision guide:

* **Tags**: Best for simple status tracking and quick wins with minimal investment
* **Metafields**: Ideal for structured data storage and analysis platform integration
* **Admin UI Extensions**: Perfect for complex interactions and rich visualizations
* **Third-Party Integration**: Choose when teams primarily work in other platforms
* **Custom Frontends**: Best for highly specialized needs requiring complete control

**Our experience has taught us that successful implementations start small and scale up based on actual usage patterns.** Begin by identifying which processes are currently invisible and causing pain points for your teams. Then start with simple solutions that address these immediate needs, gather feedback from users, and iterate based on real-world usage. Document everything thoroughly and train your teams effectively – visibility tools are only valuable if people know how to use them.

**You'll know your implementation is successful when you see**:

* Customer service resolution times decreasing
* Internal teams expressing greater confidence in automated systems
* Cross-team collaboration increasing
* System maintenance time and error rates improving

**These metrics consistently improve with better visibility into custom solutions.**

Ready to explore how these visibility solutions might work for your specific needs? [Contact our team](https://nebulab.com/contact-us) for a consultation. We'd love to help you bring your custom solutions into the light.

Into the Light: Bringing Visibility to Your Shopify Customizations

The Shopify ecosystem features a plethora of services and frameworks designed to help developers launch their own apps, whether they’re custom apps only meant to be installed on a specific store or public apps that will be listed on the Shopify app store.

Among these tools is [Gadget](https://gadget.dev/), claiming to be “the fastest way to build and run web apps.”

Gadget wants to be your one-stop shop for all of your full stack app development needs by providing a platform to handle all of the infrastructure needed to build and deploy an app.

At its core, it offers a managed PostgreSQL database and auto-generates an API package, complete with TypeScript support and React client integration. Developers can write server-side JavaScript code that runs on a serverless Node.js platform powered by Fastify, while the frontend development is simplified with a pre-configured React scaffold powered by Vite.

![](https://cdn.sanity.io/images/kqgmf0g2/production/ccc1ec82bad8e5a6f57c4d51528ddd41b1a9278a-2856x2172.png?fit=clip)

Gadget apps are always live from the moment they are created, and development environments can be promoted to production with a couple of clicks. On top of this, it offers an Integrated Development Environment (IDE) to manage both code and data in a unified location.

While Gadget is now a tool for building any sort of Web app, it was originally born to accelerate the development of Shopify apps. The Shopify integration provided by Gadget streamlines a lot of boilerplate work by offering:

- Data models for all your Shopify objects that you can augment with new attributes, stored on Shopify as custom metafields.
- Webhook subscriptions for object creation, update and deletion.
- So-called **actions** which allow you to run custom logic to keep Gadget in sync with your Shopify instance.

Gadget also publishes a TypeScript API that you can use to manage your custom data models. As an added bonus, this package is then made available through a registry, so it can be integrated in your Shopify storefront or any other JavaScript application.

Today, we’re going to take Gadget for a spin by using it to build a simple custom app that records the history of price changes for our Shopify products.

## Building Our Sample Gadget App

When creating a new app, we suggest starting with an  **Empty React embedded app**. Gadget also offers some pre-built app templates, but these don’t always work out of the box unfotunately, making for a subpar development experience.

Our Gadget app will need to read **productVariant** objects, as that’s where Shopify stores the variant price, so we need to select the **Product variant** scope when creating the app:

![](https://cdn.sanity.io/images/kqgmf0g2/production/50696d4cc9fd8601284264d42b53520aeae783ed-2910x2160.png?fit=clip)

At this point, can install the app in our Shopify store. To do this, we need to:

1. Create a Shopify app from the Shopify Partner Portal.
2. Copy the Shopify app’s Client ID (the app identifier) and Client Secret and plug them into Gadget’s configuration panel for our Gadget app.
3. Copy the URLs generated by Gadget and paste them in our Shopify app’s configuration panel. 
4. Go back to the Shopify app overview and select a store where we want to install the app.
5. Grant our app the required permissions in the dialog that pops up.

If all went well, we should now be able to see the default Gadget app UI in our Shopify store’s admin panel.

### Syncing Data Between Gadget and Shopify

To experience a bit of Gadget’s magic, we can check the **Installs** tab in the Gadget sidebar and start a **Sync** for the store we just installed our app in. This will sync our Gadget database with our Shopify store.

![](https://cdn.sanity.io/images/kqgmf0g2/production/4d65fe5ba7b9900c0d9944b25cff6d13aa58793f-2480x518.png?fit=clip)

To explore our data, we can head over to the **shopifyProduct** model and check out its data view. 

The **data** view is one of the highlights of Gadget: without Gadget, we’d have to make GraphQL API calls to be able to see the data. Being able to quickly see our Shopify data in a tabular form feels like magic.

![](https://cdn.sanity.io/images/kqgmf0g2/production/c00c913b45be8117514f0aa5fe3574c989eb79ab-3034x2244.png?fit=clip)

Furthermore, Gadget automatically creates webhook subscriptions for every accessible Shopify model, and by default, reacts to every change in the Shopify stores by ingesting changes: object creations, updates deletions are synced in near-real-time with Gadget’s database. If we attempt to edit a product, we should be able to see the changes shortly thereafter in the corresponding data view.

### Extending Our Gadget App with Custom Functionality

The simple app we're building just needs to record the history of prices set for our products. To do that, we need to store this data *somewhere*.

One way to do this would be to add a metafield to our variants. However, reading and writing the metafield would still requires going through the good old Shopify GraphQL queries and mutations, which requires a lot of boilerplate code. This is an annoying limitation of Gadget’s operating model.

Instead, let’s create a new **priceChange** model via the sidebar. Given we don't need to run calculations or any fancy analyses, we can structure the price field as a string, just as it is presented in the **productVariant** model.

We also want to correctly model the relationship between the **productVariant** model and the **priceChange** model: each **productVariant** should have multiple **priceChange** records. Setting this up via the Gadget UI is a breeze and very intuitive:

![](https://cdn.sanity.io/images/kqgmf0g2/production/1a30f13a82c332cfb7d06c17b3a903ad6af445cd-3034x1710.png?fit=clip)

Finally, we need to actually create a **priceChange** record on every price change. In order to do that, we can edit the **update** action for the **shopifyProductVariant** model, which governs what happens when variants are updated:

```jsx
// api/models/shopifyProductVariant/actions/update.js

export async function onSuccess({ params, record, logger, api, connections }) {
  const newPrice = params.shopifyProductVariant.price;

  if (newPrice != api.shopifyProductVariant.findOne(record.id).price) {
    api.priceChange.create({ newPrice, shopifyProductVariant: { _link: params.shopifyProductVariant.id } });
  }
};

```

With all of this in place, we can then test it by editing a product price on our store and then heading to the **priceChange** data view to verify the new addition:

![](https://cdn.sanity.io/images/kqgmf0g2/production/3fc38fe79407ae829db1952d8485118b7cb1cf73-2470x612.png?fit=clip)

### Taking It Further

Consuming the API built on the Gadget backend from any JavaScript or TypeScript application is as easy as installing an NPM package hosted directly in the Gadget registry, or including a minified script in your already existing web application. The API is kept in sync and documented automatically for you by the Gadget platform, which makes it a breeze to work with.

This would allow us, for instance, to read the record of price changes in our Shopify theme in order to show them to the customer (something that may be useful for compliance with the European Omnibus directive).

## Is Gadget Right For Your Shopify Customizations?

The answer is “it depends.”

If your team is already familiar with Gadget’s underlying technologies and ecosystem, picking up Gadget and feeling the magic of the robust webhook management and data synchronization  is a huge productivity boost, greatly reducing time-to-market for the applications you’ll be building.

However, if your Shopify application needs to deploy a checkout extension, a Shopify Function, or some other feature that’s not directly integrated in the app codebase, you can’t just use the Gadget UI. Instead, you’ll need to clone the code locally via the `ggt` command line tool, and then rely on the Shopify CLI to complete these tasks. While this adds some friction, it also allows you to use your preferred tools to work on the codebase, and `ggt` will still keep your data models in bi-directional sync between Gadget and your codebase.

Developers evaluating Gadget should also be mindful of platform lock-in: the platform takes over pretty much your entire custom app infrastructure, forcing you to play by their technical and commercial rules. If you ever need to migrate off of Gadget, the price to pay may be significant.

In conclusion, for teams prioritizing rapid Shopify app development over platform independence, Gadget offers a compelling and solid foundation to build upon. If, on the other hand, you value owning your infrastructure and want full control over your development environment, you’re probably better off developing your app from scratch.

A Primer to Building Custom Shopify Apps with Gadget

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?

So, you’ve reached the hard conclusion that [you need to build some middleware](https://nebulab.com/blog/ecommerce-middleware) for your Shopify store—perhaps you need to integrate with an exotic third-party system that doesn't offer a native app, or you have a complex subscription flow that cannot be accommodated by an off-the-shelf solution.

But once you've mapped out all the business requirements, you're still left with a million decisions to make: where should you host your middleware? What's the best architecture, a monolith or microservices? Should your code run on a fixed cadence or respond to Shopify's webhooks?

In this article, we're publishing some broad technical considerations we've collected over the years while working on middleware implementations for our clients. We suggest treating these as general guidelines: your mileage may vary depending on your requirements, team composition, and growth stage.

Let's dive in!

## Reactive vs. Scheduled Middleware

The first crucial architectural decision you'll make is whether your middleware should be reactive or scheduled.

Reactive middleware responds immediately to events triggered by external actions, such as customer purchases or inventory updates. It's the preferred choice when dealing with time-sensitive business logic, such as sending email notifications or updating order information.

In reactive middleware, incorporating a queue mechanism is imperative to facilitate the asynchronous processing of incoming event payloads. By decoupling the reception of webhooks from the actual processing logic, queues create a buffer that allows your middleware to absorb workload spikes seamlessly. They also mitigate the risk of data loss during processing disruptions, ensuring that all incoming events are reliably processed.

Queues are de facto mandatory when building middleware for Shopify, as your store will deactivate your webhook subscription [in case of multiple failures/timeouts.](https://shopify.dev/docs/apps/webhooks/best-practices#respond-quickly)

Additionally, you should design reactive middleware to be idempotent and resilient against race conditions, e.g., when handling duplicate or out-of-order event notifications. This allows brands to mitigate the risk of data corruption.

Scheduled middleware, on the other hand, operates on a predefined cadence, executing tasks at regular intervals. It's the preferred choice when dealing with bulk data operations, such as subscription processing or (in some cases) integrations with third-party systems.

Because scheduled middleware might process a substantial amount of data during each execution, optimizing performance and resource utilization is essential. This can be achieved by grouping data into manageable chunks and processing it in batches, minimizing resource contention and maximizing throughput. When integrating with third-party systems, it's also essential to be mindful of rate limits, maximum payload sizes, and the opportunity to leverage batch APIs whenever available.

By understanding the distinct functionalities of reactive and scheduled middleware, businesses can leverage these tools strategically to orchestrate complex workflows and optimize their Shopify operations for efficiency and scalability.

## Monoliths vs. Service-Oriented Architectures

Especially in larger projects, it's tempting to implement your middleware logic as a constellation of microservices, making up what's typically called a Service-Oriented Architecture, or SOA for short. Technically, these services may run as traditional long-lived web applications, but we often see them deployed in serverless environments such as AWS Lambda or Cloudflare Workers.

The theory is that this design increases technical freedom and reduces maintenance overhead: for instance, the subscription processing engine may be implemented using a technology different from the WMS integration. Plus, if they're deployed as serverless functions, there's no need to worry about scaling the services to match transaction volume because the infrastructure provider will handle that responsibility for us.

In our experience, however, most SOA setups suffer from premature optimization. The additional freedom and scalability come at the expense of a more complicated development and infrastructure setup, with multiple codebases to maintain and constraints on the deployment process. Code reuse is also more complicated, and rather than going through the hassle of building and maintaining an internal SDK, engineering teams often end up duplicating the shared code. In other words, the additional effort and complexity often outweigh the gains.

Because of this, when faced with complex middleware architectures, we always consider whether there's a chance to simplify things by moving to a [Majestic Monolith](https://signalvnoise.com/svn3/the-majestic-monolith/) deployed as a traditional, long-lived Web application. While they're not as fancy as a serverless SOA, monoliths have several advantages:

* Engineers only need to work in one codebase to make orthogonal changes, which makes it easier to work atomically.
* Code sharing across API endpoints and scheduled jobs is trivial since everything's in the same application.
* We only need to write and maintain a single deployment pipeline, which makes deployments simpler and more robust.
* We eliminate the need to deal with network failures, data model inconsistencies, and data synchronization issues.
* It's still easier and cheaper to find and onboard new engineers on a monolith vs. a SOA.

This is not to say that microservices and serverless architectures are always bad. There are situations where they can help with scalability, e.g., for trivial middleware that only needs to respond to a specific webhook (in which case a serverless infrastructure is acceptable) or when a particular piece of business logic can be optimized by rewriting it in a more suitable technology. However, these pros always need to balance against the additional complexity introduced into the system.


## Keep Your Options Open

As we mentioned at the beginning of this article, your mileage may and will vary, especially as time passes and your middleware starts taking on more responsibilities. Our suggestion is to regularly re-evaluate your design and architectural choices to ensure that your current setup is still the ideal fit for your needs.

Furthermore, remember that the best middleware is no middleware. Whenever you see an opportunity to simplify your architecture by removing custom logic in favor of a third-party solution, you should seriously evaluate it. E-commerce brands are not tech startups, and every dollar you save in development costs is a dollar you'll be able to invest in other areas of the business.

If you are struggling with fine-tuning your custom integrations or business logic, [don’t hesitate to reach out](https://nebulab.com/contact-us): we can help you navigate and streamline the complexity, finding the ideal setup for your brand.

Designing and Scaling High-Throughput Shopify Middleware

In the complex world of e-commerce technology, Shopify stands out as a beacon for businesses eager to establish or expand their online presence. Its user-friendly interface, coupled with a vast ecosystem of apps and integrations, has made it the go-to platform for merchants. Still, the convenience offered in the off-the-shelf package is not enough for everyone.

While Shopify's app store provides many easy-to-install solutions that promise quick wins, the reality is that the more complex your business needs, the less likely you'll find an app that fits the requirements. And, as businesses grow and operations become more complex, the limitations of a simple Shopify build become more and more apparent until they bring businesses to a crossroads: either simplify operations to fit into Shopify’s boundaries, or heavily customize Shopify to play by their rules.

The former path might be acceptable and sometimes even advisable for smaller stores. Building complex Shopify customizations requires significant resources and can be a source of [technical debt](https://nebulab.com/blog/shopify-technical-debt); as such, these projects should always be justified by a clear and compelling ROI.

But for brands in the upper midmarket/enterprise segment, building more complex automations and customizations on top of Shopify often makes perfect sense: these companies have complex internal workflows, custom tooling, and nuanced policies, and their e-commerce platform must learn to adapt and play nice with the existing ecosystem.

Luckily, Shopify’s ecosystem comes with rich tooling designed to create custom apps and integrations. In this post, we'll delve into some of these tools. More specifically, we’ll cover Shopify Flow, Zapier, e-commerce iPaaS Solutions, Gadget, and Greenfield Apps, exploring their pros and cons, ideal use cases, and some examples of the customizations they enable.


## Shopify Flow

[Shopify Flow](https://help.shopify.com/manual/shopify-flow) is a tool built into Shopify that allows creating automations without leaving the platform. It's a basic yet powerful way to respond to events generated within your online store (e.g., a new order being placed) with a set of actions (e.g., sending an email to your staff).

**Pros:**

* **Seamless Integration:** It’s designed specifically for Shopify, ensuring a smooth integration with your store. It’s Included in Shopify for free; no need to pay for extra software.
* **User Friendliness:** Shopify Flow comes with a visual workflow builder that requires no coding, making it accessible to non-technical users.
* **Third-Party App Support:** Shopify apps can extend Shopify Flow by adding their own triggers and actions, which expand the possibilities of the tool. This functionality is only available to Shopify Plus merchants.

**Cons:**

* **Complexity Limitations:** While powerful, Shopify Flow does not always cater to highly intricate integration needs that require custom coding.
* **Partial Support for External API Calls:** You can create an action that performs an API request to an external service (if you’re on the Shopify, Advanced, or Plus plan), but you cannot use the data you receive in any way. Shopify has committed to solving this in 2024.
* **Partial Support for External Emails:** At the moment, it's not possible to send emails using Shopify Flow, except for emails to staff members or as part of email marketing automations. You cannot send transactional emails to your customers or anyone else.

**Ideal Use Case:** Shopify Flow is your go-to for automating operational tasks within Shopify's ecosystem, particularly if you're a Shopify Plus user and can use all of the functionality it offers. It's ideal for businesses looking to streamline processes like tagging high-value customers for exclusive offers or automating restock notifications.

**Example Customization:** Automating the tagging of VIP customers based on their spending history and automatically enrolling them in an exclusive loyalty program.

## Zapier

[Zapier](https://zapier.com/) can be a good alternative to Shopify Flow, if you find its limitations unbearable. Via the Zapier app for Shopify, you can connect Zapier to your Shopify store and pick from an extensive list of triggers and actions to build your automation.

**Pros:**

* **Wide Range of Integrations:** Zapier can connect Shopify with over 3,000 web services, facilitating many different kinds of automations.
* **No Coding Required:** Zapier’s interface is similar to Shopify Flow, but offers even more power by allowing you to build more complex, more robust automations.
* **Rapid Deployment:** You can quickly set up new integrations and automations without the time and cost associated with custom software development.

**Cons:**

* **Pricing:** Zapier’s costs can quickly escalate as you increase your usage of the platform and build more complex workflows.
* **Dependent on Third-Party Connectors:** Even though it boasts more integrations than Shopify Flow, Zapier still relies on the availability and limitations of third-party connectors.

**Ideal Use Case:** Zapier is best suited for businesses that find Shopify Flow too limiting, but still need to build automations or integrate Shopify with other platforms quickly and without custom development.

**Example Customization:** Automatically adding new Shopify orders to a Google Sheets spreadsheet for advanced reporting and analysis.


## E-Commerce iPaaS

Integration Platform as a Service (iPaaS) solutions connect your online store with a variety of other systems, such as ERP, POS, and warehouse management systems (WMS), facilitating the automation of business processes across platforms. There are plenty of iPaaS solutions that integrate with Shopify–our favorite are [Patchworks](https://www.wearepatchworks.com/), [VL OMNI](https://vlomni.com/), [High Cohesion](https://highcohesion.com/), and [Pipe17](https://pipe17.com/).

**Pros:**

* **Connector Ecosystem**: Unlike Zapier, which is a generic automation platform, e-commerce iPaaS platforms specialize in connecting e-commerce platforms like Shopify with CRM, ERP, POS, and WMS systems.
* **Data Integrity:** E-commerce iPaaS platforms were designed to ensure data consistency across platforms, reducing synchronization errors and improving operational efficiency.
* **Bespoke Support:** with most iPaaS platforms, you can typically engage their customer support or professional services team to build connectors that are not already available.

**Cons:**

* **Integration Complexity:** Setting up more sophisticated connectors and automations may require technical expertise to configure and manage.
* **Cost:** The investment required to use an iPaaS reflects its enterprise-level capabilities, making it more suitable for larger businesses with complex needs. Most platforms will charge you per connection or event (e.g., a new product being created).

**Ideal Use Case:** E-commerce iPaaS solutions are ideal for medium-to-large businesses that require robust, real-time integrations between Shopify and other enterprise systems.

**Example Customization:** Integrating Shopify with an ERP system to automate order management, inventory management, and financial reporting, streamlining operations and reducing manual errors.

## Gadget

[Gadget](https://gadget.dev/) is a powerful full-stack serverless platform that allows building and hosting custom Shopify Apps, skipping all the repetitive tasks and accelerating the development cycle of your custom app. Through Gadget, you can accomplish all the automations and integrations that are not possible with off-the-shelf apps and integrators.

**Pros:**

* **Rapid Development:** Gadget offers a rapid development environment for Shopify apps, reducing time to market and human error.
* **Scalability:** Gadget is built to handle high volumes of data and traffic, making it suitable for growing businesses.
* **Developer-Friendly:** Gadget provides advanced tools and resources tailored for developers who need to create sophisticated apps, like Shopify API version management and pre-built React frontends that are compatible with Shopify’s security policies.

**Cons:**

* **Learning Curve:** Developing with Gadget requires a significant amount of technical knowledge, making it hard to access for non-developers.
* **Cost:** Custom apps may involve higher initial development costs compared to simpler integration approaches.
* **Single Environment:** As of today, multi-environment applications (staging+production, for example) are not supported. However, Gadget claims the feature will be released soon.

**Ideal Use Case**: Gadget is a powerful choice for tech-savvy teams looking to build a private Shopify app for their brand as quickly as possible.

**Example Customization:** Creating a custom loyalty program that’s not supported by any off-the-shelf loyalty apps for Shopify.


## Greenfield Apps

When none of the tools above is capable of fulfilling our complex business requirements, we are left with one extra solution, probably the most flexible one: building a custom Shopify app completely from scratch. We call these “Greenfield Apps.”

Greenfield Apps can extend the functionality of your Shopify store in whatever way you want, as long as your desired workflow is supported by Shopify’s APIs.

**Pros:**

* **Malleability:** Greenfield apps can be designed to meet your exact business requirements, offering unparalleled flexibility.
* **Direct Integration:** You can use greenfield apps to interact with all of Shopify's APIs, enriching your online store with custom business logic, Storefront and Admin UI components, and complex automation and integration workflows.
* **Technical Scalability:** Greenfield apps can grow with your business, accommodating new features and processes as needed, without financial or technological lock-ins.

**Cons:**

* **Development Cost**: Custom development is typically more expensive and time-consuming than pre-existing solutions.
* **Maintenance Effort:** Greenfield apps require ongoing maintenance and updates to ensure compatibility with Shopify's evolving ecosystem. \

**Ideal Use Case:** When your business requires unique functionality that cannot be addressed with existing apps or tools, greenfield Shopify apps provide a solution tailored specifically to your needs.

**Example Customization:** A bespoke app that provides a UI for a marketplace’s vendors to update product prices and availability, and instantly propagates those updates across multiple warehouses within your Shopify storefront.

## Complexity Is Not Always a Bad Thing

While Shopify's app ecosystem offers a solid foundation for run-of-the-mill retailers, expanding beyond these boundaries unlocks new levels of operational efficiency, customization, and customer satisfaction.

When considering your options for customizing your e-commerce store, remember that the right choice depends on your needs, budget, and technical capabilities. Make sure that you’re factoring in all of these elements before committing to a specific solution.

Building custom features and integrations may seem daunting, and might require resources and expertise that you don’t have in-house. But at the end of the day, this growing complexity is often a testament to your brand’s growth and the need to evolve your customer experience.

If you need help launching a custom feature or integration for your Shopify store, [feel free to reach out!](https://nebulab.com/contact-us) Our engineering team would love to help you figure out the right solution.


Building Custom Shopify Automations, From Beginner to Pro

Have you ever struggled with a simple addition to your Shopify store turning into a nightmarish project, full of intricacies and edge cases? Or maybe you’ve experienced the impatience of looking at your product page take forever to load, longing for the good old days when it showed up instantaneously? Or perhaps you’ve run into weird UI bugs caused by two of your apps not playing nice with each other?

When you launch a new Shopify store, everything’s fantastic: the theme is beautiful, the pages load fast, and the apps you’ve picked are a joy to work with. It feels like you’ve got everything figured out, and no one and nothing will ever change that.

But after a while, some friction shows up. Implementing new features takes longer. Bugs pop up. Site speed decreases, as does your conversion rate.

Your team (or your agency) now spends more time hunting down the things that are not working than implementing new functionality that could move the needle. But even though everyone’s dissatisfied with the state of things and your business is suffering, no one can pinpoint the root cause or figure out a definitive solution.

Starting from scratch looks like the only option, so that’s what you do. You change agencies, rewrite your theme, and call it a day. Unfortunately, the rewrite only helps temporarily: give them enough time, and things will revert to their original state, and the cycle will start all over again.

Sounds scary, doesn’t it? And yet it’s a story that we’ve heard from many Shopify merchants, disenchanted with their agency, internal team, or the Shopify ecosystem as a whole.

The good news is that it doesn’t have to be like this. There’s a way to keep your ecommerce store from degrading over time; all it requires is a more thoughtful approach to store development. In this blog post, we’ll outline what that approach looks like, and how you can adopt it.

But before we do that, we need to introduce the concept of technical debt.

## What Is Technical Debt?

Technical debt, often called just “tech debt,” refers to the compromises made in a system for short-term gains, which may lead to more complex maintenance and updates in the long run. It is the practice of taking shortcuts: installing unvetted apps for the sake of shipping a feature, implementing untested JavaScript “hacks” in your theme, breaking best practices for theme maintenance, or failing to keep up with the latest Shopify API updates.

These solutions help you move faster and will not kill your store in the short term, which makes them so appealing in the first place. But in the long term, the consequences will show up in the form of bugs, lower site speed, a slowdown in development velocity, and, in extreme scenarios, a decrease in conversion rate.

Unfortunately, Shopify’s marketing can be misleading when it comes to technical debt: the promise is that, by using Shopify, merchants will never need to worry about technology, and by extension, they will never need to worry about technical debt.

That is only partially true: while Shopify handles a lot of responsibilities for merchants, a merchant’s theme and app stack is still for the merchant to maintain, and it can accumulate technical debt just like any other software. Your theme can either be a beautifully architected piece of technology, highly performant and easy to evolve, or a hot mess of obscure hacks and patches no one understands anymore. You, the merchant, are ultimately responsible for deciding where you want this pendulum to swing.

But in practice, what are the sources of technical debt in Shopify that cause stores to lean one way or the other? Here’s a non-exhaustive list, but keep in mind that there are additional factors that are often unique to each store:

* **Multiple stores:** even after the advent of Markets and B2B in Shopify, many merchants keep using multi-store setups when they are not needed. Because each store is independent and stores can diverge from each other, this setup can be a significant source of technical debt, increasing the cost and complexity of making changes.
* **Too many apps:** Shopify’s blessing–its app ecosystem–is often its curse. When we audit Shopify stores, we are often shocked by how many apps the average store has installed. Often, not even the merchant can explain what all the apps do. This is the #1 source of bugs, compatibility issues, and a steep increase in license fees.
* **Too much JavaScript:** some custom themes present a large amount of JavaScript code, often using external libraries such as React, Angular, or jQuery. This complexity, which is sometimes uncalled for, makes it harder for developers to find their way around a theme, slows down your website, and introduces bugs.
* **Large Liquid files**: similar to the point above, Liquid files that are hundreds of lines of code quickly become hard for developers to understand and change, to the point where they might be deemed completely unmaintainable.
* **Outdated code:** if your store is not leveraging metaobjects or not using the full potential of Online Store 2.0, you might end up with weird hacks and workarounds to implement functionality that is now natively available in Shopify. Apps can compound this problem because they are sometimes slow to adopt new Shopify APIs and capabilities, reducing the flexibility and optionality of their user base.

There are additional factors that are not technical debt _per se_ but often lead to technical debt over time: examples of these would be the lack of a defined QA process for theme changes, which increases the likelihood of bugs, or the lack of theme documentation, which makes it harder for unfamiliar developers to find their way around the project.

## A Three-Step Approach to Managing Shopify Technical Debt

Managing technical debt in a Shopify store can be tricky for inexperienced merchants and developers. However, a structured approach can go a long way in effectively controlling it. Here’s the three-step process we typically adopt when we work with a merchant.

### 1. Measure the Business Impact

Before tackling technical debt, it's essential to understand the extent of the problem.

In traditional software projects, there are tools that attempt to measure the health of your code. These tools typically ingest your entire codebase and produce a “quality” score that tells you the overall state of the software and what areas you should improve.

The bad news is that most of these tools don’t work with Shopify themes because they’re structured differently than most other software. The good news is that, in our experience, such tools are ineffective: technical debt only matters insofar as it _actually_ impacts your business. Code quality, as measured by a machine, is rarely a good proxy for business impact.

Instead, you want to measure the effects of technical debt on your store’s real-world performance. There’s no one-size-fits-all metric here, but here are some that we’ve used:

* **Defect rate,** which measures the number of features your team has shipped that introduced one or more bugs in the customer experience.
* **Cycle time,** which measures the time it takes for your team to implement a change after that change has been prioritized.
* **Site speed,** which should be pretty self-explanatory.

Both defect rate and cycle time can be measured with a good project management tool, while site speed is typically measured with tools such as PageSpeed Insights.

With all these metrics, what matters most is not their absolute value but their directional trend over time: if they’re getting better and not worse, you’re moving in the right direction and can double down on your current approach.

### 2. Establish a Solid Foundation

Once you have a good grasp of the extent of the problem, the next step is to ensure there are no obvious sources of technical debt in your Shopify setup.

These are the aspects we typically focus on:

* **Leverage native Shopify features**: by using native functionality as much as possible, you are reducing the need for ongoing maintenance. Whenever you diverge from the built-in functionality, you should always consider the balance between innovation and the additional complexity you’re introducing into your store.
* **Minimize third-party apps**: in addition to increasing your license fees, each app you install into your store introduces more complexity, potentially slows the website, and can lead to bugs in the customer experience. Vet all the apps you install and ensure they are needed.
* **Adopt a version control system (VCS):** a VCS makes it much easier to document the changes developers are making to your theme, and to roll back to a previous version of the theme in case a bug pops up. From a technical standpoint, there’s no reason not to have a VCS in place for your Shopify theme.
* **Set up a test store:** a staging environment (sometimes called a “test store”) allows you and your ecommerce development team to test your changes safely before rolling them out to your customers. The caveat is that you will likely need to install all your apps in the staging environment, increasing your license fees.

While this is just the beginning, it will give your team an initial foundation they can build upon.

### 3. Prevent and Reduce Debt Over Time

With the basics in place, you can now adopt team-wide policies to help your team minimize the technical debt you introduce over time.

These are some of the policies that we adopt:

* **Call technical debt by its name:** if you only do one thing outlined in this article, it should be this. The #1 reason technical debt keeps growing is that developers do not have the technical understanding or psychological safety to talk about it. Ensure everyone is familiar with technical debt and comfortable calling out when a corner has been cut. A recurring team retrospective can be very helpful here.
* **Perform technical code reviews:** encourage developers to review each other’s code whenever a change is introduced. This means that developers will need to schedule time for code reviews, and your development velocity will slow down a bit, but the quality of the end product will benefit tremendously.
* **Establish a structured QA process**: ideally, QA should be done on every new change by your development team, who should be familiar enough with your store to understand whether a feature meets all the acceptance criteria. If that’s not possible, you can also designate the person in charge of website development.
* **Set time aside for tackling technical debt:** in the past, Shopify shared their internal strategy for dealing with technical debt, the [25 Percent Rule](https://shopify.engineering/technical-debt-25-percent-rule). It might not work for everyone, but having a clear understanding of how much time is acceptable to dedicate to refactoring technical debt will create a safe space for developers to work on it.

Some of these policies might be overkill for small stores, while others must be adapted to your needs. Ultimately, it all boils down to how much technical debt impacts your store and how many resources you can dedicate to fighting it.

## Technical Debt Is a Tool: Learn to Use It!

With this entire article focusing on eliminating and preventing technical debt in your Shopify store, you might be tempted to think that technical debt is something to be avoided at all costs. The reality is a bit more nuanced.

Like financial debt, technical debt is a tool: cutting corners helps you move faster at critical times of your business, such as before a big launch or public holiday.

And _just like_ financial debt, technical debt must also be paid off at some point. If you ignore it, its adverse effects will compound over time, severely impacting team morale and dragging down business performance.

Leveraging technical debt thoughtfully and intentionally is critical to a merchant’s success in the Shopify ecosystem. Doing it well requires a collaborative effort, with clear team agreements and robust processes tailored to your growth stage and team composition.

If you’re struggling with managing technical debt in your Shopify store, [reach out!](https://nebulab.com/contact-us) As a Shopify partner, have worked with some of the largest brands in the ecosystem and can help find the best solution for your store.


How To Manage Technical Debt in Your Shopify Store

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 an eCommerce brand, replatforms are always exciting projects that hold a lot of promise: a replatform can come with increased flexibility, lower maintenance costs, and a better customer experience that can significantly impact your top-line growth.

However, replatforms are also incredibly stressful and can quickly become a nightmare when they’re not planned or executed appropriately: because they’re large and irreversible projects, it’s easy to miss something important and only realize it too late. Suddenly, what was supposed to be a growth driver for your business turns against you, leaving your board, team, and customers unhappy.

In this article, we will share some strategies we follow when guiding our clients through a replaform, from picking your new eCommerce platform all the way through implementation and launch. Hopefully, we can help make your next replatform a bit less scary!


## 1. Start With the Why

This one should be obvious, but you’d be surprised how many store owners cannot clearly articulate why they are executing a replatform.

A replatform project is a big undertaking from many perspectives:

* **It takes time**: replatforms will take up a lot of your team’s time and energy. In our experience, most re-platforms take anywhere between 2-5 months, depending on the complexity of your online store. Enterprise replatforms can take years!
* **It’s expensive:** replatforms are expensive projects, no matter whether you use your internal team or work with an agency. Trying to cram a replatform into a tight budget is a recipe for disaster, so make sure you can allocate the right resources.
* **It’s risky:** re-platforms are inherently risky. While most software projects can be approached incrementally, re-platforms require a big-bang transition, dramatically increasing the likelihood of something going wrong.
* **It impacts morale:** for some of your team members, the replatform will come with a steep learning curve, considerable disruptions to their existing workflows, and even fears about their career opportunities (“Will this new skillset make me less relevant?”).

With all that is at stake, you want a crystal-clear understanding of why you need to replatform: you owe it to your team, your customers, and yourself. Some of the most common scenarios in which it makes sense to do a replatform are:

* **To increase flexibility.** If your platform is consistently preventing you from executing your digital roadmap, then it’s time to look for more advanced vendor–that is, provided that your roadmap is the result of an [intentional, data-informed product management workflow.](https://nebulab.com/blog/ecommerce-product-management)
* **To support growth.** If your existing platform is having growth pains, then you might want to switch to a more scalable solution that will support your brand’s long-term plans.
* **To reduce maintenance costs.** Some platforms are more expensive than others to keep up and running. Sometimes, this is an acceptable cost to pay for certain benefits (such as additional features), and sometimes it’s a non-justifiable expense.
* **To access a larger ecosystem.** If you can’t find any partners or system integrators willing to work with your current setup, and this is preventing you from reaching your business objectives, then it might be time for a change.

There are also many _bad_ reasons to do a replatform, such as your team only having experience with a specific stack (they can learn a new technology), fear of missing out because everyone else is using a different solution (they are not you), or an investor pushing you hard to make the switch (it’s unlikely they fully understand your business needs).

We suggest writing a [Request for Comments](https://nebulab.com/blog/driving-organizational-change-with-rfcs) about the replatform. This will help you analyze your motivations and assumptions, evaluate potential alternatives, and ensure that a replatform is the right move for your eCommerce store.

RFCs have the added benefit of helping you build commitment and create alignment on the project internally–and believe us, it’s something you will need badly if you move forward.


## 2. Think Brand First, Not Vendor First

So, you wrote an RFC, you discussed it with your team, and you’re all aligned on your motivations. The next question is, how do you compare the capabilities offered by different vendors?

Nowadays, there are tens of eCommerce platforms to choose from. As in most crowded software categories, they all offer a base layer of foundational functionality and a certain number of differentiators that make them stand apart. Some of these differentiators will be useful for your specific needs, while others are just marketing stunts that will lure you in but ultimately prove irrelevant.

When approaching a replatform, we typically categorize business requirements in one of three buckets–Big Rocks, Pebbles, and Sand:

* **Big Rocks:** these are major pieces of functionality. They are highly specific to your brand promise and business model. For membership-based brands, for instance, the #1 Big Rock is their membership billing engine.
* **Pebbles:** these requirements are still important but not unique to your brand. An example would be your average ERP or 3PL integration. For most brands, there’s not a lot of innovation involved in these foundational eCommerce features.
* **Sand:** these are minor requirements that can be taken more or less for granted. Most cosmetic improvements, such as the image carousel on your PDP, fall into this category.

![](https://cdn.sanity.io/images/kqgmf0g2/production/ee19cec17172531bd1e236882c503471ca249262-3200x2104.jpg?fit=clip)

Once you have this mapping, you can understand how the platforms you’re evaluating will solve your requirements, prioritizing each requirement depending on how it’s been categorized. Feel free to ask the vendors you’re considering for help during this phase: after all, they know their own solutions inside out. However, you should always double-check their claims, as they are bound to be biased.

Whatever you do, make sure you base your comparison on your actual requirements–not on the narrative each vendor tries to push, nor on the hype around their product. It is ultimately irrelevant how many features or apps an eCommerce solution offers if you only use a tiny fraction of them. **Technology is just a tool: your platform should fit your brand, not vice versa.**

A platform-agnostic agency is the best partner for this kind of project: they have the expertise to advise you, but they are not married to one specific solution, which gives them the freedom to offer you what they genuinely believe to be the best path forward.


## 3. Account for All the Expenses

Platform and transaction fees are a _significant_ part of any eCommerce brand’s P&L statement. When replatforming, you should clearly understand the costs you’ll incur under the new tech stack if you don’t want any unpleasant surprises.

Unfortunately, many brands jump the gun here and only account for the most apparent and immediate costs, such as their platform’s transaction fees in the first year. As a result, they neglect other variables that are not as visible but equally important, only to get burned by their new vendor once it’s too late to go back.

When approaching a re-platform, we typically categorize the costs as follows:

* **License fees:** this is how much you’ll pay your vendors for access to their services. Most brands only include the cost of their eCommerce platform here, but you should also account for any third-party apps and services you will need.
* **Transaction fees:** these are the fees you pay on your payments, and they typically have fixed and variable components. Some platforms have integrated payment gateways with lower transaction fees, while others will require you to work with a third party.
* **Maintenance fees:** we would all love to use an eCommerce platform that requires zero maintenance, but that is rarely the case. While you can’t calculate precisely how much design and development effort you’ll need with your new platform, you should make an educated guess and understand how that compares with your current setup.
* **Replatform fees:** how much will it cost to execute the replatform? Assuming that your goal is reducing engineering spend, how long will it take you to recoup that initial investment under the new platform?

When evaluating these costs, you also want to understand how they will change as your brand grows: what would they look like at 2X your current scale? Does pricing grow linearly, more than linearly, or less than linearly? Will there be room for negotiation, or are you locked into this commercial structure forever? Does the new vendor have any minimum commitments?

Every platform is unique, but do your best to make an apples-to-apples comparison that clearly outlines the total cost of ownership and any pros/cons associated with each option.

## 4. Approach the Work Incrementally

Switching over to the new platform will require a Big Bang Release, where you switch your brand to your new tech stack almost overnight. This approach is typically frowned upon in software development: the more changes you’re introducing simultaneously, the more you increase the chance that something will go wrong.

The bad news is that Big Bang Releases are somewhat unavoidable with most replatforms. The good news is that there are several approaches to minimize the amount of uncertainty associated with them. In general, if you can do something _before_ you finalize your transition to the new platform, you should.

Here are a few techniques we typically adopt:

* Work closely with your in-house team or external partner to demo and test their work as often as possible. You don’t want the team to work in isolation for three months and then do your testing in one go: you’re bound to miss something or discover significant problems once it’s too late to do anything about them. Better yet, have your entire team do QA: you’ll be surprised how much more stuff you can find as a group!
* If you need to make any changes to integrations or external systems to make them compatible with your replatform, see if you can apply them beforehand in a way compatible with both the old stack and the new one. This typically applies to ERPs, WMSs, and 3PLs, but you can generalize it to other vendors.
* Test your data migrations ahead of time and continue to execute them continuously in the days leading up to the launch. That way, on launch day, you will only need to migrate a small portion of your data rather than all of it.
* Create checklists for what you will do before, during, and after the replatform. Launch day is incredibly stressful, so it’s essential your team doesn’t have to think too much about what they’re going to do.

These are just some ideas, and your mileage may vary depending on your setup and the complexity of your architecture. The rule of thumb is that you want to work in small increments and do the bulk of the work upfront, so you only need to pull the trigger on launch day.

You can also check out [this article](https://nebulab.com/blog/ecommerce-agency-productivity) we published about how to optimize your agency’s or digital team’s productivity. All of those strategies also apply to replatform projects!

## 5. Resist the Urge to Redesign

If there is one thing you take away from this article, let it be this: do NOT do a rebrand or redesign at the same time you’re doing a replatform. After over a decade of working with eCommerce brands of all sizes, we have witnessed so many failed attempts at this that we strongly discourage this practice.

There are several reasons why a redesign might be bundled together with a replaform. In our experience, it’s usually a combination of the following factors:

1. Most brand executives are visual people. During a replatform, they get understandably excited and come up with a million potential improvements to the customer experience, which often turn into a full-blown redesign.
2. The byproduct of #1 is that, in larger companies, the person sponsoring the replatform often feels the need to justify the investment to their boss through a tangible artifact, such as a rebrand/redesign. This gives them a clear “thing” to point to when someone asks them where all that money went.
3. Unfortunately, some eCommerce agencies do redesigns along with replatforms to increase the scope of the engagement, and so that the final result can be more easily turned into a compelling case study.

As we already mentioned, this is almost always a bad idea. Replatforms are complicated and risky, so you want to keep their scope as small and controlled as possible. Redesigning your website while uprooting its tech stack dramatically increases the risk of something going wrong during or after the launch. It also makes it much harder to isolate and measure the business impact of specific changes to the customer experience.

We suggest keeping the new website as similar as possible to what you had before. After you launch the replatform, you’ll have plenty of time to fully leverage the capabilities of your new tech stack, so there’s no reason to rush it.

## 6. Prioritize the Scary Stuff

Remember that Big Rocks, Pebble, Sand categorization we talked about earlier? That’s not just a way to map your business requirements, but it’s also an excellent mental model to keep in mind when prioritizing the different features involved in your replatform:

1. Big Rocks are the most critical problems to solve and carry the highest risk and uncertainty, so you want to get them out of the way as early as possible.
2. Pebbles are essential but less risky–you want to get them done and tested early, but not before you’re done with the Big Rocks.
3. Sand is irrelevant: while some of these features are important to your business, they’re also quick and easy to implement and can be left for last.

Unfortunately, we often see things being approached in the opposite order. Because it’s easier and faster to make progress on Sand than on Big Rocks, they focus on the lowest-hanging fruit while neglecting the big, scary problems screaming at them.

One brand we spoke with in the past, which was heavily subscription-based, reached the last week of their replatform without having done any work on their subscription engine yet. When they finally focused on it, they realized the provider they had picked wouldn’t be able to accommodate their needs, and they had to cancel the launch and go back to the drawing board.

To keep your team focused, it can be helpful to appoint a Product Owner/Project Lead. This person, who ideally has project management experience and understands your brand inside out, will be responsible for keeping track of the project’s progress and ensuring the team is prioritizing the work correctly.

One last word of warning here: remember that perfect is the enemy of good. Just like with the redesign, you’ll have plenty of time to improve your online store after the launch, so don’t get bogged down in pursuing tiny optimizations at the expense of bigger achievements.

## Launch and Celebrate!

If you follow the tips above, launch day should be much less stressful than it could have been. Just follow your checklists on launch day, sit back, and celebrate!

Besides that, now is the time you can fully unleash the true power of your new eCommerce stack. As always, make sure to move intentionally and be data-informed–[establishing a lightweight Product Management practice](https://nebulab.com/blog/ecommerce-product-management) can do wonders in ensuring you’re not getting ahead of yourself, but working on features that will actually move the needle.

We hope we managed to shed some light on what is typically a long and confusing process for any brands that go through it!

If you need additional help with your replatform, [don’t hesitate to reach out!](https://nebulab.com/contact-us) Our team works with a variety of eCommerce platforms. They would be more than happy to advise you on the best choice for your brand and guide you through the entire implementation and launch process.

How To Nail Your eCommerce Replatform

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

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

Your stakeholders are complaining that the app is slow. You work tirelessly to shave millisecond over millisecond off your server’s response time. Yet, at the end of the month, the stakeholders still complain about the suboptimal performance, to only later discover that they are using the application on a smartphone connection, inside a building with hundreds of other people using a smartphone, and while taking the elevator to move from one meeting room to the other.

This is just a story, but maybe you have experienced (or are experiencing) something similar in the real world and are looking for a more scientific approach to performance tuning. Perhaps you are here looking for an easy solution to improve your performance by just tweaking a single parameter in your configuration.

Unfortunately, most of the time, that’s simply not possible. All the overnight success stories you read about are the result of long experimentation, and they conveniently forget to mention all the failed attempts. Performance tuning is complex: it heavily depends on your application’s context, architecture, and [tech stack](https://nebulab.com/blog/ecommerce-tech-stack). To succeed, you must get your hands dirty and enter into a continuous measure/tune/verify cycle.

In this article, we will showcase a process for experimenting with the ideal performance setup for a [Solidus](https://solidus.io/)-based eCommerce application, as well as some interesting conclusions we’ve reached.

## Starting with Puma threads

When configuring a Puma-based Rails application, you can tune a lot of values to optimize its performance. Still, we can simplify our process by focusing on four major levers:

* The number of Puma workers

* The number of Puma threads

* The amount of CPU in your environment

* The amount of RAM in your environment

For now, let’s assume the amount of CPU and RAM and the number of Puma workers are constant, which is the most straightforward configuration you can have. We’ll talk about Puma workers and horizontal vs. vertical scaling in a separate article.

That means we should just focus on the number of threads, which allows us to keep things simple and straightforward. In general, when tuning performance, we recommend tweaking one parameter at a time: touching multiple levers simultaneously will lead to inconclusive results, and you might end up making things worse.

## Works on my machine!

For this experiment, we have run all tests locally. This allows us to have full control over environment in which the load tests are running. It also gives the Rails server plenty of CPU and RAM, preventing those from becoming a bottleneck in our testing.

Another advantage of running the tests locally is the almost complete lack of DB latency. In the real world, DB latency might impact the ideal number of threads, since each DB request will block its originating thread for a little longer. However, you can fine-tune this parameter in production. In this case, we’re more interested in getting a ballpark number that we can start with.

## The setup

In this experiment, we will optimize a Solidus-based eCommerce application, running PostgreSQL and Redis for data storage and caching/background jobs.

We’re using [k6.io](http://k6.io/) for load-testing because the open-source version is free, easy to set up and use, and it’s scriptable.

As a first step, let’s bootstrap a simple Solidus store. We won’t go through the setup because the process is already covered in the [official Solidus documentation](https://guides.solidus.io/getting-started/installing-solidus#in-a-new-app). You can find all the code in the [GitHub repo for this post](https://github.com/nebulab/repo-for-globpost-are-you-leaving-free-performance-on-the-table-).

We wrote a k6 script that simulates a complete visit to the website and performs a guest checkout. Note that this approach has some limitations: for example, we’re not testing the authentication system. However, it’s a good approximation of what a typical user journey would look like on my store.

As recommended by k6, we’re not testing asset delivery: in production, assets will most likely be served by a CDN, so testing them in a local environment would just muddy my data. Right now, we’re only interested in optimizing the application server.

We’ve decided to load-test the system with 50 concurrent users, each completing a single journey in my application. We’ve run the script against our Solidus application ten times, progressively increasing the number of Puma threads from 1 to 10.

## The results

Here are some graphs showing our results:

![Requests per second](https://cdn.sanity.io/images/kqgmf0g2/production/01b5ecdc96e1fa7859b614281aee8419c0ecfa39-600x371.svg?fit=clip)

![Request duration](https://cdn.sanity.io/images/kqgmf0g2/production/82090ce65420951346613c6f146c18b5e94ffa49-600x371.svg?fit=clip)

![Elapsed time](https://cdn.sanity.io/images/kqgmf0g2/production/88a998380731794a35b121d895e51122c54b74a0-600x371.svg?fit=clip)

Like most eCommerce applications, our Solidus store is a DB-heavy codebase, and it blocks each thread for a relatively long time. This is noticeable in our benchmark because the application is heavily underperforming with fewer than 4 threads.

It’s also interesting to note how the default Puma value of 5 threads is a good starting point for our application: anything beyond 5 threads is only giving us marginal gains. It also looks like performance is actually *decreasing* above 8 threads, which is probably due to the excessive thread context switching.

## Conclusions

k6 is a powerful tool with many applications: for instance, it could be used to enforce service-level objectives through automated performance tests.

When it comes to performance tuning, it’s always a good idea to put all decisions under the microscope. It was interesting to confirm that the default value of Puma workers is indeed a sane default. For a Solidus store, I would probably recommend bumping that number to 8 as a starting point to squeeze out each bit of performance.

However, the number of Puma threads is just the beginning. For instance, in a real-world performance tuning project, we should also:

* Calculate the amount of RAM I need to accommodate my ideal number of threads.

* Experiment with the number of Puma workers with 1 CPU.

* Experiment with the advantages of having a dedicated CPU versus a shared one.

* Compare different PaaS solutions to evaluate the pricing of our ideal setup.

* Experiment with horizontal and vertical scaling for our needs, creating to a well-defined scaling strategy.

As we’ve mentioned in the introduction to this article, there is no silver bullet for performance tuning: each project needs to account for the context, technical and business factors at play. However, by adopting a rigorous, scientific approach, you can tame the usual chaos of performance tuning, reaching your desired results with much less effort.

Over the next few weeks, we’ll continue to expand on this topic. *Stay tuned*!



Are You Leaving Free Rails Performance on the Table?

eCommerce operators often tell us that picking the right tech stack for your eCommerce brand feels like walking on a tightrope. There are so many tools and technologies to choose from, and making the wrong decision can severely impair your online store’s ability to scale with your business.

In this guide, we’ll look at what a tech stack is, why building it is a critical phase in your brand’s life, and how you can create a tech stack that will support your goals and your brand’s evolving requirements.

## What is a tech stack?

In layperson’s terms, a technology stack (“tech stack” for short) is a collection of programming languages, software libraries, frameworks, databases, and online services integrated to deliver a particular user experience.

While some of these technologies are very generic and apply to all kinds of scenarios, others are specific to the eCommerce industry. Here are the basic building blocks of most modern tech stacks:

* **Programming languages:** Developers use specific programming languages (e.g., Ruby, JavaScript, PHP, Java, Python) to code the server-side and frontend logic behind your application. Different languages have different properties and capabilities when it comes to popularity, scalability, and developer experience.

* **Libraries and frameworks:** These are software packages that make it easier for software developers to implement standard functionality. For instance, most backend programming languages provide Web frameworks that speed up the implementation of Web applications, such as Django for Python or Ruby on Rails for Ruby.

* **Infrastructure:** Infrastructure consists of the Web server, database, and other components that run your application’s backend and frontend code and host its data. Depending on your use case and requirements, many different types of infrastructure providers and possible configurations exist: e.g., you may use a relational database like MySQL, or a NoSQL database like MongoDB.

* **SaaS providers:** This is a catch-all term to indicate all the third-party software you pay a recurring fee to access. It can be a small piece of your stack, such as an analytics service or automation platform, or a major component, such as the eCommerce platform your brand runs on.

As you may imagine, picking the right mix of frontend and backend technologies, libraries, infrastructure, and SaaS providers requires a lot of experience: First of all, not all components integrate well with each other; secondly, each set of technologies has its pros and cons, which are very context-dependent.

While recommended practices exist, any agency or Web development team pushing the same software stack onto all of their customers is doing them a huge disservice. **Using the wrong tech stack can slow down your development process, prevent you from efficiently capitalizing on business opportunities, and hold back your startup from scaling.**

In the following paragraphs, we’ll explore the most critical parts of an eCommerce brand’s tech stack and how to make informed decisions when discussing them with your agency or in-house developers.

## What are the components of an eCommerce tech stack?

![Image of an hand that holds a rainbow-coloured MasterCard with two fingers](https://cdn.sanity.io/images/kqgmf0g2/production/4c046c881c959d397caaedf2278e3a95741ec830-1920x1080.jpg?fit=clip)

The average eCommerce brand may integrate many tools and technologies to deliver and optimize their customer experience. Let’s look at some of the most common eCommerce technology you might make as an operator or developer.

### eCommerce platform

Your eCommerce platform (sometimes called “shopping cart”) is the core of your business. Picking the right eCommerce platform is a critical decision when launching or re-launching your online store and one that you should evaluate from many angles.

There are many players in this space, and they come in different shapes and forms: established solutions such as [Shopify](https://shopify.com/) and [BigCommerce](https://bigcommerce.com/) promise reliability and large ecosystems. In contrast, newer solutions such as [Swell](https://swell.is/) and [Commerce Layer](https://commercelayer.io/) offer flexibility and a more modern approach. Then you have disruptors such as [Solidus](https://solidus.io/) (which is open-source) and [Chord Commerce](https://chord.co/) (which is data-driven), which push for a completely different take on building and operating your brand.

You can learn a bit more about the state of the eCommerce platforms market in our article on [headless vs. monolithic eCommerce](/blog/headless-commerce).

### Payment processing

Payment processing is a big part of running an eCommerce business. All eCommerce brands integrate with one or more vendors in the space, called PSPs (Payment Service Providers).

Note that “payment method” and “payment service provider” (or “payment gateway”) are sometimes used interchangeably. Still, they have two different meanings: while a payment method represents a medium the customer uses to pay for goods and services (e.g., credit card, Apple Pay, Google Pay), a payment service provider is a company that builds software to enable specific payment methods. For example, credit cards are one of the most common payment methods in eCommerce. To accept credit card payments, you must partner with a PSP that provides that service, such as [Stripe](https://stripe.com/).

You can either decide which payment methods you want to support and then pick the right combination of PSPs, or pick a PSP you want to use and then choose which payment methods you wish to enable among the ones they support.

There’s no right or wrong answer: whether to go one way or the other depends on your market (e.g., US vs. EMEA), business model (e.g., B2C/B2B), customer demographics (e.g., Gen X vs. Gen Z, household income) and industry (e.g., THC products are highly regulated and only supported by specific PSPs).

### Logistics

The supply chain experience can make or break a brand’s shopping experience. Especially for DTC, the bar is high, with consumers constantly comparing you with their latest experience and not settling for delivery delays or order mix-ups.

“Logistics,” in the context of an eCommerce operation, encompasses at least three different components, which may or may not be provided by the same vendor:

* **Inventory management:** an inventory management system allows you to track the inventory in your warehouse(s). Modern WMSs integrate with your eCommerce platform for real-time stock counts.

* **Shipping management:** a shipping management system allows you to generate shipping labels and track your packages’ journey from the warehouse to the customer.

* **Returns management:** a returns management system allows you to define your return policies, enables customers to handle returns autonomously, and tracks returns on their way to the warehouse.

You can either build/buy these tools and handle your logistics in-house or partner with a 3PL (third-party fulfillment) vendor to store your inventory and handle all logistics- and fulfillment-related responsibilities on your behalf. Which way to go depends on your company stage, product category, market, and many other factors.

### Content management

Depending on your needs, choice of eCommerce platform, and frontend technologies, you may or may not need to pick a content management system (CMS). A CMS allows you to manage the marketing content that appears on your eCommerce website.

Headless CMSs are all the rage nowadays: they allow developers to specify which content types are supported and how they should be presented on screen while still allowing marketers to publish whatever content they want, whenever and wherever they want. This gives your team much power while maintaining a consistent presentation of your content across your storefront, mobile app, and other sales channels.

With that said, headless CMSs are also restrictive: if a particular content module is not supported, your team won’t be able to publish it until a developer implements it. Whether to go with a headless (e.g., [Contentful](https://www.contentful.com/)) or monolithic CMS (e.g., [Webflow](https://webflow.com/)) depends on your scale, technical capabilities, and editorial needs.

For more details, read our article on [eCommerce content management](/blog/ecommerce-content-management).

### Marketing

Reaching your customers at the right touchpoints, and offering relevant, personalized information and offers, is an unbeatable advantage of online shopping. Brands can leverage first-party data to create “aha!” moments and magical experiences, but only if they are supported by the right tools.

You will find many marketing tools serving different channels and purposes: some tools are specifically built for email/SMS marketing, while others will be more targeted at social media marketing. Some tools are specifically designed for eCommerce companies; some are generic but do a good enough job of accommodating the needs of an online brand.

Our suggestion? Start simple. Going too aggressively after too many channels might cause you to disperse your efforts. Instead, be very intentional about which channels you’re pursuing, your segmentation strategy, and how to ensure that all the information you have about your customers is being put to full use. Once you have an established strategy, you can start to iterate and experiment.

### Customer support

Expectations around customer support (“CS”) have never been so high, and the bar is set even higher for digitally-native brands, which have pioneered a new era of customer support. Customers expect you to be responsive, solve their problems, and go above and beyond to provide a memorable experience.

Different CS software solutions support different channels (e.g., email, SMS, phone, social media), and covering as much ground as possible is critical in implementing a successful customer support strategy. If you have an Instagram account, customers expect their complaints to be answered there, not just by email.

Also, when those customers do reach out, you want to have the correct data at your disposal, so make sure your customer support platform integrates well with the rest of your stack: for example, when a customer reaches out, can you quickly identify them and see what they’ve purchased, and maybe initiate a return from within the CS tool itself? The more manual work you eliminate from the process, the easier it will be for your team to offer stellar support.

### Business intelligence

Data is an eCommerce store’s superpower. When a customer buys from you, you instantly get access to a ton of precious information about them and their behavior. You can either aggregate these bits of information to generate valuable insights for your business strategy, drill down to the customer level, or use the data to offer hyper-personalized experiences (ideally, you do both).

Building the right business intelligence (BI) infrastructure is a topic of its own, and entire books have been written about it. Many ready-made solutions allow eCommerce brands to track user behavior and generate fundamental reports and insights about their business. Highly sophisticated solutions enable brands to model their tracking, ETL, and data mining processes.

When it comes to business intelligence, we strongly encourage brands to be intentional about what they’re doing: it’s easy to implement a million different tracking pixels, tools, and reports and still be unable to generate any actionable insights. Start from the questions you want to answer, understand what data will help you answer them, and pick the right tool(s) for the job.

## 8 tips for building your tech stack

![Picture of a green crossroads into the wood](https://cdn.sanity.io/images/kqgmf0g2/production/ef51951e452f8432f6a43df46b9a9c9c598058dd-1920x1285.jpg?fit=clip)

The good news for eCommerce companies is that there are an incredible amount of solutions for launching and operating a brand. The bad news is that, with so many established players and new ones popping up daily, making a choice can feel overwhelming, and the consequences can be disastrous.

Here are eight tips that you should use to build your brand’s tech stack or when evaluating a change in your existing stack:

* **Ease of integration:** some solutions will be easier to integrate, thanks to public APIs and built-in connectors. When building your tech stack, pay attention to how the different parts of your stack will communicate. An integrated tech stack means less manual work and a better customer experience.

* **Build vs. buy:** buying an existing solution is not always the right choice. If you don’t find any vendors that fit your business needs, consider building an in-house solution that will scale with your brand over time. However, be mindful that this comes with caveats (e.g., higher upfront costs)!

* **Hot vs. boring:** should you jump on the latest hot trend or pick a boring solution that has stood the test of time? Unfortunately, there’s no correct answer: sometimes, some experimentation can give you a competitive advantage. But if you overdo it, you can expose your business to unnecessary risk.

* **Pricing:** it may seem obvious that you want to evaluate pricing when building your tech stack. However, we encourage you to look beyond the Pricing page, considering the expected lifespan of the solution, the total cost of ownership, and even the opportunity cost.

* **Decision reversibility:** some tech stack decisions are more challenging than others to reverse. Switching your customer support tool is rarely too complicated, but migrating to a new eCommerce platform is a big deal. Keep this in mind when making a choice.

* **Compliance:** in specific markets and business verticals, you will need to worry about compliance and regulatory issues. Sales tax, the CCPA (in the US), and the GDPR (in the EU) are the usual suspects, but the needs will evolve with your business, so you will need to stay on top of things.

* **Scalability:** while everyone loves to talk about scalability in the performance sense (e.g., how well a solution handles high traffic volumes), that is rarely a problem in most scenarios. Instead, understand how well the solution will support your evolving requirements and how likely you will need to move away from it as your brand grows.

* **Customer support:** we’ve discussed the importance of offering excellent customer support as a brand–you should hold your vendors to the same standard. Look at SLAs, support channels, and even G2 reviews. Ideally, talk to someone who’s already a customer and get their feedback!

## Do you need help building your tech stack?

Hopefully, we’ve convinced you that building your eCommerce brand’s tech stack is no easy feat. It’s a complicated, multi-layered process critical for ensuring your brand’s long-term success.

If you’re launching your brand or need to overhaul your existing brand’s tech stack, we can help. Our eCommerce engineers have worked with tens of brands over the years and can help you make the right decisions, enabling you to move quickly and laying the foundations for aggressive growth.

[Reach out](/contact-us) to tell us more about your project!

How to Build Your eCommerce Tech Stack

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

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

Everyone keeps telling us to be gentle when reviewing Pull Requests, and that’s the right thing to do, but are we nice with who reviews ours?

A Pull Request is a way to communicate with other individuals who are responsible for the project’s maintenance, so we should do a good job improving our Pull Requests code and documentation to make their work straightforward. It’s also in our best interest to do that since the easier the review is the faster we’ll get our code merged.

## Who reads our Pull Requests?

Creating a reasonable Pull Request is a matter of walking in the shoes of people that will open it later, who fall into the following categories:

* **Code Owners**: who are in charge of reviewing and merging the code.

* **Developers implementing new features**: who are changing previously merged code and need to understand why that code is there.

* **Developers fixing bugs**: who encounter a bug and need to go deep in the git history to understand where the regression has been introduced and why.

We should be respectful of each of them while creating a Pull Request since facilitating their work both in the present and in the future is what makes software development honest and practical. “Time is running out” kind of excuses here are not valid, every moment that we don’t spend improving Pull Requests that we leave in our project is a lot of time wasted for who will interact with them later.

> A Pull Request is created one time but evaluated multiple times.

Do the math!

![](https://cdn.sanity.io/images/kqgmf0g2/production/61e451b8aa097487f4e8e20ab17f3ac713117f8c-560x240.gif?fit=clip)

## What reviewers dream to see

Let’s take a look together at what makes a Pull Request easy to review.

### Well organized code

Code is the soul of the Pull Request, but it won’t be my focus here. You can find a lot of resources about this on the Internet. I’ll only mention some general rules to apply code side:

* Make it small, try to break it into multiple Pull Requests.

* Write well-separated and well-documented commits, the why is the most important thing.

* Add tests, they’ll help reviewers understanding the context of the Pull Request.

* Take a look at the contribution guidelines usually at CONTRIBUTING.md; it may have important information.

### Meaningful title

It needs to clearly and exactly describe what has changed. For example:

![The preview of a wrong-formatter Pull-request title](https://cdn.sanity.io/images/kqgmf0g2/production/2c23d7ca307eba19629a23417b8c92525c59f42f-1340x200.png?fit=clip)
🔴 Bad: This one is too generic and doesn’t provide any value.

![The preview of a well-formatter Pull-request title](https://cdn.sanity.io/images/kqgmf0g2/production/e51f25dbd3166b9566efd0606c4f264866d63a64-1340x200.png?fit=clip)
✅ Good: This one is specific and explain what changed.

If you can only come up with a generic title, that’s probably a first signal that we could split the Pull Request into multiple ones.

A rule that I apply to determine if a title is good is to ask myself this:

> Could this title fit a CHANGELOG entry?

This soft-rule comes from my experience maintaining [Solidus](https://solidus.io/), the open-source project I mostly work on. On Solidus, before each release, we run a script that auto-generates entries for the CHANGELOG.md file using Pull Request’s titles. When they are self-explanatory, there’s much less manual work to do for maintainers.

### A description that really helps

Here’s the core of the Pull Request documentation. It’s quite common to assume that the Pull Request title and commits are enough for people to understand the context, but that’s not always true. For example, let’s consider this Pull Request title:

![](https://cdn.sanity.io/images/kqgmf0g2/production/2a55753537b7c1d02daf6a0746efd6d2e744bd47-1340x200.png?fit=clip)

I’m sure that when reading the Pull Request title today, with all the team focused on this specific change, everyone will immediately get what’s going on and **it could be tempting to leave the Pull Request’s description empty**. But what happens if you have to come back to this Pull Request in 1 year? Will you immediately remember how this switch has been done, and why?

Luckily, the “how” could still be read by commits description, even if it would be more time and energy-consuming to scan all the commits to get the sense of what’s happening. The real problem is that it’s tough to see the “why” of the change.

Let’s see what makes a good Pull Request description:

* It contains a **quick recap of the changes introduced**. It doesn’t have to be a lot of text, just something to quickly understand what changed without opening every single associated commit.

* It describes **why things changed**, try not to take for granted that the reader has a clear picture of the state of the system when the change happened. If the Pull Request comes from a change request done via an issues tracker, it could be handy to link that issue here.

* It describes the **steps to reproduce the changes introduced** with the Pull Request. It could be calling a method from a console, or make some interactions in a UI. It will drastically help reviewers to touch with hands the code they are seeing. It allows them to figure out any doubts that could arise in autonomy, without the need to ask for clarification and extra back and forth with the author.

* It includes **screenshots**: if the change has an impact on how the website looks or on any other visual part of the system, it’s a good idea to attach some screenshots. It will be super easy for those who look at the Pull Request to identify what changed and how.

With GitHub, you can guide the Pull Request author into providing all these things by using **Pull Request templates**. It’s a feature that allows to specify a template that will populate the Pull Request description for any new Pull Request. It’s just a matter of adding a markdown file into `.github/PULL_REQUEST_TEMPLATE.md`. Here’s a collection of [ready-to-grab Pull Request templates](https://github.com/stevemao/github-issue-templates) and the [GitHub documentation page for Pull Request Templates](https://help.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository).

There’s also another hidden, not well-documented GitHub feature, that allows having multiple templates for Pull Requests. You can get them by just reflecting this filesystem structure:

```
.github/
  - PULL_REQUEST_TEMPLATE.md .       # The Default Template
  - PULL_REQUEST_TEMPLATE/extra.md   # Additional templates
```

When you create the Pull Request, you can use the infrastructure template by adding the `&template=extra.md` in the URL’s query params.

### The right reviewers

The policy about asking specific persons to review our code could change depending on the project. For this reason, GitHub offers a [Code Owners](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) functionality that allows us to specify rules that automatically trigger review-requests from the right people. Here’s an example of a CODEOWNERS file:

```
*                   @project/backend-team
/app/javascript/    @project/frontend-team
/docs/              @project/documentation-team
```

This will ask for a review to the `project/backend-team` for all changes in the project excluding those that are located in `app/javascript` and docs, which will ask for a review to their respective teams.

I suggest integrating the usage of this feature with a clear team policy on how much time and how often developers are expected to review others’ code.

## Preview App linked to each Pull Request

Reviewers’ work is way smoother when they can test what a Pull Request changes before merging, and it’s a good practice to have a preview environment, very similar to staging, generated for each Pull Request open.

If you are deploying on Heroku, you can just use their [Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), whose setup is quite simple. It’s also possible to build something very similar by yourself: GitHub offers a Deployments API to create a Deployment section in the Pull Request page. By calling something like:

```
curl -X POST -H "Content-Type: application/json" \
-H "Accept: application/vnd.github.ant-man-preview+json" \
"https://api.github.com/repos/nebulab/project/deployments/42/statuses?access_token=XXX" \
-d '{ "state": "success", "environment_url": "https://your-custom-url/", "environment": "preview"'
```

You’ll see the deployment link in your Pull Request.

![The deployment button in GitHub](https://cdn.sanity.io/images/kqgmf0g2/production/bfe079861626b276e4e2cf4a47eb55f201bf93e7-1564x784.png?fit=clip)

At Nebulab, we use CircleCI and we’ve created a [CircleCI Orb](https://github.com/nebulab/circleci-orbs-feature-branch-preview) that allows us to have this functionality ready in minutes in all our projects by adding the following lines to the `.circleci/config.yml`:

```
version: 2.1

orbs:
  feature-branch: nebulab/feature-branch-preview

workflows:
  cool-workflow:
    jobs:
    - do-cool-things
    - run-specs
    - feature-branch/preview:
        domain: <domain-for-preview-apps>
        github_repo: <your-github-repository>
        github_token: <your-gh-auth-token>
        letsencrypt_email: <email-for-ssl-cert>
        server: <docker-server-to-run-containers>
        user: <docker-server-user>
```

### I bet you now want to be nice too!

After reading this post, you should! Being nice with reviewers gives you better and contextualized quality checks for your code, which should help you **grow as a developer**. It decreases **time-to-merge** for your code and will increases the **velocity to implement new features** that depend on existing ones. **Debugging is also faster** since you don’t have to read all the code to understand how and why a specific thing has been done. Helping reviewers means helping your team and your future self!

What Every Teammate Wants to See in Your Next Pull Request

During my career, I’ve had the honor of observing and being part of tens of engineering teams as a consultant, IC and manager.

Obviously, not all of these teams were equally effective at reaching their goals: some worked like perfect machines, others fell apart at every little problem, and most of them were somewhere in between these two extremes.

One would be tempted to explain these performance differences through a mere gap in technical skills — simply put, some people are more skilled than others and get more done, faster. The theory here is that the more highly-skilled engineers you hire, the better your team will perform.

This is certainly true, at least to an extent. However, if you talk to a seasoned manager, you’ll find that they’ve dealt with these two types of engineers at least once during their career:

* A junior engineer who absolutely crushed it not just from a technical perspective, but also in terms of the impact they had on the organization.

* A very senior and skilled engineer who never managed to accomplish anything meaningful, and ultimately moved on or had to be let go.

**Technical skill cannot always justify gaps in the performance of individuals or the teams they comprise**. There must be a more important underlying factor, one that justifies such dramatic differences in the impact people have on an organization, beyond their direct knowledge of the technologies and tools they work with. When present, this factor leads people to overcome their technical limitations in order to be effective at their job. When absent, it discourages them from pursuing meaningful results, no matter their skill.

Lately, I’ve come to realize the root factor may be **ownership**.

## An Intrinsic Trait with Extrinsic Results

Ownership is an intrinsic trait with extrinsic results: it’s born *inside* you, but most of the good things it leads to happen *outside* of you, in your interactions with others.

**Intrinsically, ownership is a sense of belonging and pride in one’s efforts that ultimately leads to the pursuit of excellence.** People who have ownership genuinely care about everything they do because they have the ability to see the value in it, even when it’s not obvious. Because of this love, they are willing to do the right thing.

**Extrinsically, ownership is the collection of traits that give managers peace of mind**: people who have ownership are dependable and consistent; they don’t wait for someone to assign work to them, but autonomously pick the thing that will have the most impact; they are in touch with the company’s mission; they work to the best of their abilities; they remove blockers from their way; they are not afraid to roll up their sleeves and fix something that’s broken, even when it’s not supposed to be their concern; they constantly re-evaluate and improve their way of working.

Most importantly, **ownership is contagious**, and it spreads very quickly: while technical skills take years or even decades to truly master, it only takes a few weeks of working in a team that consistently exhibits ownership for a new person to get up to speed on what’s expected of them. This is probably because we all have a natural sense of ownership and can recognize it and appreciate it in others when we see it.

## Ownership and Organization Design

In most mature organizations, there are at least three layers an individual is interacting with at any given time:

1. **The craft (the “how”).** When I am working, I am connected to the craft I am practicing to produce my work. An example is the relationship between an engineer and the code they write.

2. **The team (the “what”).** The code I write doesn’t exist in isolation (most likely), but is part of a larger endeavor my team is collectively working on. Together, we work on something bigger than ourselves.

3. **The company (the “why”).** Ideally, we don’t write code simply out of love for the code, but because we want to solve a problem we care about. Our company connects us all through its mission.

The three layers are also directly connected, and almost equivalent, to the three factors Daniel Pink identified in [Drive](https://www.amazon.com/Drive-Surprising-Truth-About-Motivates-ebook/dp/B004P1JDJO/ref=tmm_kin_swatch_0?_encoding=UTF8&qid=1587991379&sr=8-1):

* Ownership towards **the craft** corresponds to **Mastery**.

* Ownership towards **the team** corresponds to **Autonomy**.

* Ownership towards **the company** corresponds to **Purpose**.

In some organizations, ownership is experienced at all three layers: people love their craft, trust their team, and believe in their company. This perfect alignment creates the ideal environment for individuals to do their best work, and such an organization is bound to have an impact.

In other cases, there is a disconnection between these three layers. It’s important to note that, while the layers are connected to each other, the different levels of ownership people feel towards them may be completely independent of one another. Here are some examples:

* An organization whose members are deeply connected to the company’s mission, but completely uninterested in their craft.

* An organization that hires superstar employees by offering extremely generous compensation packages. In this case, employees will own their craft, but most likely not feel connected to the company.

* A dysfunctional organization that happens to have one or two very good teams in it. Their members are bound to feel a strong sense of ownership towards their team, but a very weak one towards their company (in extreme cases, people may favor their team while antagonizing their company).

Another important aspect is that the ways to foster ownership in these three layers are completely different. While ownership should be practiced first and foremost by the CEO, ultimately **it’s up to the individuals who comprise the organization to find the best ways to implement ownership in their work.**

Because the ways to foster ownership towards the company is largely independent of the type of company, and has been written about extensively already, and fostering ownership towards the craft is not something managers should be concerned with, let’s instead focus on how to foster ownership towards one’s team, especially in the context of an engineering organization.

## Ownership and Cycle Time in Engineering Teams

In a team setting, the biggest obstacle to team members’ ownership comes in the form of bottlenecks. Bottlenecks are steps of the work process that require team members to wait for someone before they are able to move forward with their work. **By removing responsibility from the person who is producing the work, they discourage that person from “owning” the work all the way to its completion.**

In the average engineering team, bottlenecks come in many different shapes:

* Software engineers need to wait for a PM to define the next sprint and assign work to them before they can start working.

* Software engineers need to wait for a QA engineer to test their work before their work is approved for deployment.

* Software engineers need to wait for a release manager to follow a very long and complicated checklist before their work gets deployed.

Every single bottleneck reduces the ownership individual team members feel towards their team: QA engineers find bugs in the features they test, but these bugs are never fixed and the work lingers in a limbo forever; engineers sit on their hands all day because they don’t know what they’re supposed to work on next. This results in a very tangible increase in cycle time.

Unfortunately, **engineering teams often don’t know a better way to do things**. In fact, many of them will argue that the bottlenecks are necessary: we need the engineers to have their priorities clear before they work, because the priorities change too quickly. We need to do manual QA on our system, because our system is too complex to rely on automated tests alone. We need to handle deployments with care, because the cost of a mistake is too high.

I would agree with all of these objections: there are products where the priorities would change dramatically from one day to the next, there are enterprise systems that are too complex for automated tests to catch all the permutations of interactions and edge cases that would cause a bug, and there are applications where the cost of a bad deployment can be computed by multiplying the minutes of downtime by a factor of one thousand or more.

And yet, I would never ever advise such teams to strip their engineers of their responsibility and ownership to protect the business — not because I think the sacrifice isn’t worth it, but because there is a better way. One that empowers teams and makes them more productive, resulting in more value for the organization and a better use of the engineering budget.

## A Practical Framework for Fostering Ownership

There are three activities paramount to building ownership in your team:

* **Communicate:** by communicating constantly with your team, you create alignment on the business priorities and expectations. Frequent and consistent communication gives your team the information they need to make decisions autonomously.

* **Streamline:** by streamlining processes, you empower everyone to follow them and make sure their work gets done. Note that streamlining doesn’t necessarily mean automating: while automating a process is the ultimate way to streamline it, proper documentation can also do wonders.

* **Trust:** ultimately, you need to trust your team to do the right thing. Most teams lack ownership because their managers don’t think their members can do the best interest of the organization without micromanagement. In the long-term, this lack of trust is a recipe for failure.

These three activities will take different shapes depending on the size and conformation of your team, but your end goal should always be to establish a framework for ownership and collaboration within the team. Everyone on your team should know not only what ownership means, but also how to exhibit it in their day-to-day work.

For example, here are some of the practices I have adopted over the years to foster ownership in the engineering teams I led:

* **Enforce direct communication:** when you’re a team lead, people have a tendency to go to you when they have a question, effectively turning you into a bottleneck and reducing their contact surface with the business. The next time someone approaches you with a question you can’t answer, encourage them to seek the answer by themselves. This may seem like you’re forfeiting responsibility, but what you’re actually doing is removing a bottleneck in the communication process.

* **Take “done” to the extreme:** most engineering teams don’t even have a definition of “done”, yet alone an extreme one. It should be clear that a feature is only finished once it’s been successfully deployed to production and used without problems by your users. Until then, the developer’s first priority should be to keep the feature moving through the development pipeline so that it gets done  — *actually* done.

* Turn **bottlenecks into leverage:** bottlenecks often come in the forms of individuals or teams who are responsible for keeping another team’s work moving forward. I’ve already made a couple of examples when I spoke about QA engineers and release managers. This kind of repetitive work alienates people and doesn’t add any value to your team — in fact, it slows them down. Instead, find ways to turn bottlenecks into leverage: the job of a QA engineer, for instance, should be to document QA processes and build tooling to automate them as much as possible. QA on individual features should be done by the engineer in charge of that feature.

* **Make ownership visual:** having a highly visual representation of the state of work can be extremely helpful in creating ownership. Most development teams work with Kanban boards, which are great for this sort of exercise: make sure your Kanban board actually has columns for every single step of your development process (e.g. don’t conflate code reviews with QA) and make it clear that it’s an engineer’s responsibility to keep things moving through that board at all costs. Also, make sure people give priority to things on the right (i.e. closer to get done) over things on the left. Having strict rules in place helps fight our tendency to start something new when we feel blocked on in-progress tasks.

* **Delegate decision-making:** nothing empowers people such as… their manager empowering them. Delegate decision-making as much as possible, even and especially when it feels a little uncomfortable. This doesn’t mean you should leave people to themselves: always be there for your engineers to talk a problem through, but give them the last word if possible. When someone has autonomy, they will honor that autonomy by exhibiting ownership.

As I said, your mileage may vary, but a good starting point is to try these practices in your team, keeping what works and adjusting what doesn’t. People will start taking ownership in ways that surprise you, identifying bottlenecks and creating original solutions to keep the process moving.

## Ownership Is a Gateway to Velocity

You have probably heard the term “velocity” before. A lot of articles talk about velocity and the difference between velocity and speed: while speed is just about how quickly you’re moving, velocity is also about *where you’re going*.

Many teams move crazy fast, but they often lack a clear direction. As a result, they do work that is not truly meaningful for the business, or they have to redo their work over and over again because of defects, incomplete implementations or missed requirements.

Once you and your team start exhibiting ownership, you will realize how connected ownership and velocity truly are: teams that own their work are teams that move both quickly and in the right direction. This connection exists for two reasons:

* **Ownership is first and foremost about doing the right thing.** Low-ownership environments discourage engineers from thinking about the business value behind their work, but high-ownership teams carefully consider each initiative and its impact from all possible angles. People will start doing things that really move the needle.

* **No one wants to own a half-done task.** Teams that don’t own their work often do the quickest thing that will allow them to cross an item off their list, whereas teams that exhibit high levels of ownership know that the work doesn’t stop when it’s in production: quick and dirty solutions mean more maintenance work down the line and less time for high-impact initiatives.

As you can see, creating a high-ownership environment is not just the best thing you can do for your team members, but it’s also the best thing you can do for your business: it will increase the volume, quality and business impact of the work produced by your engineering team.

For a lot of managers, it can feel scary to give away control so radically, once you have seen the results, you’ll never want to go back.

The Transformative Nature of Ownership in Engineering Orgs

One of the most important decisions you will make when launching your digital brand is which eCommerce platform you build your store with. Typically, there are three categories to choose from:

* **SaaS platforms** are online software solutions that handle all the complexity of building and running a store. In exchange for a recurring license fee, these tools provide a storefront your customers can access as well as a backend to to manage your store. They are by far the quickest and easiest solution to get started. Popular examples in this category are [Shopify](https://www.shopify.com/) and [BigCommerce](https://www.bigcommerce.com/).

* **Open-source platforms** are ready-made software packages that provide similar functionality to what you could get with a SaaS platform. Because they are open-source, these platforms can be customized, although many of them are not built for that. Furthermore, you have to host them in your own infrastructure. Popular examples are [WooCommerce](http://woocommerce.com/) and [Prestashop](https://www.prestashop.com/).

* **Open-source frameworks** are software solutions that provide the basic functionality you need to build your store. They vary in functionality and underlying technology, but most of them are built to create extremely custom experiences and provide a very high degree of flexibility, at the cost of a steeper learning curve and a larger upfront investment. Popular examples are [Solidus](https://solidus.io/) and [Saleor](https://saleor.io/).
The main difference between SaaS platforms and open-source platforms is the pricing model: SaaS platforms require paying a recurring license fees, while most open-source platforms are free. In terms of functionality, however, they are pretty similar, so we will instead focus on the differences between SaaS platforms and open-source frameworks.

## Cost of ownership

SaaS platforms have two main pricing models: you either pay a fixed fee every month/year, or a percentage of your store’s sales volume. This results in a pricing model that scales with your store, but **it also means you are paying money just to keep your store online instead of investing in its continuous evolution.**

Most open-source frameworks, on the other hand, are entirely free to use, but you need to hire a development team that will build, launch and maintain your store. While this model requires a larger upfront investment, **it’s also a better fit for those entrepreneurs who are serious about investing in the technology that powers their business.**

If you can afford a larger upfront investment and you expect your brand to scale seriously, going with an open-source framework will reduce your total cost of ownership while creating more opportunities than you could get with an off-the-shelf solution.

## Customization possibilities

SaaS platforms offer a great starting experience with no customization work needed. This is really helpful for people who are just getting their feet wet in the eCommerce industry: **if you don’t know how to create a good UX and just want to start selling, a SaaS solution will help you.** This kind of simplicity doesn’t come for free, though: **SaaS platforms are not always easy to customize, and in certain cases you are stuck with the default experience they provide.**

Going with an open-source framework means you’ll have to figure out more stuff by yourself, but **it also affords you the flexibility to customize each and every aspect of your store however you see fit,** allowing you to truly innovate the buying experience rather than being one more droplet in a sea of digital brands.

The most prominent online brands became memorable not just because of their products, but because of the experience they created around all brand interactions. **If eCommerce is an important channel for you, you need to start seeing yourself as an experience company,** and treat technology as a first-class citizen.

## Data ownership

**SaaS platforms, unfortunately, act by their very nature as middlemen between you and your customers.** Because you are not hosting your infrastructure when you adopt a SaaS solution, you lose direct access to a lot of potentially useful information. These platforms try to make up for the lack of data ownership by providing out-of-the-box reporting tools, but they often fall short of brand expectations.

**With an open-source framework, you will always have complete access to all the data generated by your store.** This data can be used in any way you see fit: you can either customize your platform to generate advanced reports internally, or connect an external business intelligence tool that will help you take full advantage of all the information at your disposal.

Being a digital brands allows you to use data to your advantage: by accessing information that is not always available to traditional brick-and-mortar retailers, you can make smarter decisions, which reduces your costs and helps you stay competitive. The paradox here is that **data ownership is even more important for smaller brands, which don’t have access to economies of scale and can afford fewer mistakes.**

## Time to market

Because most SaaS solutions provide all the tools you need to start an online business out of the box, it will always be quicker to get your brand started with a SaaS platform than with an open-source framework, at least for a basic store. **If you’re in a hurry to get started and cannot afford to wait, you should definitely look into SaaS.**

With that said, one aspect to keep in consideration is the velocity of your team when evolving your store in response to market conditions. **In the hands of a skilled engineering team, an eCommerce framework will be not only quicker to adapt, but because it’s built to be customized, it will also allow you to make optimizations that stand the test of time.** SaaS platforms, on the other hand, often require ugly hacks that cost you more time in ongoing maintenance than for their initial development.

For most brands, time to market for the initial launch is not a relevant factor. On the other hand, time to market in capitalizing new opportunities and evolving your eCommerce experience can make or break a digital brand.

## So… which one is it?

As you have seen, there are different factors to take into consideration when choosing the best eCommerce platform for your needs. Most of them boil down to two key aspects: experience and vision.

**If you are only getting started in eCommerce, or think of your brand mainly as a product company, you should probably consider SaaS options.** They will make selling online a no-brainer, at the cost of technical limitations and a higher total cost of ownership.

**If you are an eCommerce veteran, or consider customer experience to be paramount in building your brand, you should instead going with an open-source framework**, making a larger upfront investment in order to have a flexible platform that will allow you to deliver a completely custom experience.

What Can Open Source Do for eCommerce?

These days code is a collaborative matter. Good developers are expected
to both write great code and help others write code. Code reviews play a crucial part in this: they're the main tool a team has to ship great code and have fun while doing so.

## 😤 Reviews are hard

First of all, let me say it loud and clear: doing code reviews is **damn hard**.
If somebody says giving a pull request review is easy it's probably because they never actually went over a pull request. Pull request reviews are hard because:

* you need to be polite and forgiving;
* it happens remotely 99% of the times;
* you need to think like someone else;
* everyone has their own coding style and it should be respected;
* code written in 10 hours is often reviewed in under 10 minutes;
* praise and criticism happens publicly;
* you are going to write stupid things and completely fail;
* ...

It also depends on the PR of course: certain PRs are pretty straightforward.
You can relax with simple PRs, just approve them and merge them ASAP, your
code deserves it.

I think you get the picture: pull request reviews are more about people and less
about code and computers. In a productive development team reviews should happen
often and be stress-free; they should help the team improve over time, spread
knowledge and increase overall badassery.

## 📕 My Checklist

When I need to go over a pull request I do it several times and use each time a
different point of view. I do this because checking everything at once is simply
unbearable... I lose track of what I'm looking for and I need to start all over
again. So each time I need to look at a PR I look for:

1. syntactic correctness
2. feature completeness
3. meaningful use of git

### ✅ Syntactic Correctness

This is the first check: it's easy and fast (depending on the amount of code)
and doesn't require a fresh brain and, usually, can even happen late during the
day because it's just a matter of checking:

- do tests pass? Is the build green?
- does static code analysis report problems (i.e. [RuboCop][rubocop] and
friends)?
- overall look of the code, are there any code smells?
- are the description and the commit messages written in proper English?
- does the PR respect all of the project conventions (i.e. branch naming,
labels, ...)?

Generally, if something is clearly wrong I either assume the PR is not ready to
be reviewed or straight away ask for a fix on those simple things before digging
into the PR.

The key take-away here is **automation**: you'll save a ton of time by using
tools like [overcommit][overcommit] or [Hound][hound], take the time to
configure them properly so they can do the work you would do manually.

Another thing I do regularly is using [pull request templates][pr-templates] to
add a checklist of what a project needs. Depending on the project and team, stating
clearly the review process within the PR itself can be a huge time-saver,
especially for simple requirements. There are a [ton of examples][pr-template-examples]
you can choose from.

![](https://cdn.sanity.io/images/kqgmf0g2/production/a30b68397c4da12a3e1274e08ff86159eff9e1fa-200x144.webp?fit=clip)

### ✅ Feature Completeness

This step is the hardest. First of all, I read once or twice the issue the PR is
trying to solve (it should be linked in the PR description), then I go over the
code changes, class by class, file by file and dig down the code as in depth as
I can.

The idea here is to try to understand if the person that wrote the code:

- had a good understanding of the issue (asked the right questions, had the
required skills, ...)
- wrote code that actually solved the issue
- didn't miss any edge-cases
- used the right design patterns (and didn't over-engineer the code)

All of the above can be *extremely hard* because you're generally looking at
the result of several hours of work in a short amount of time (sometimes you even
need that code in production and it won't help).

The key takeaway here is **open-mindedness**: never assume anything. Always be
neutral when reviewing code, you should look at code as something that can
advance a project, not like a form of art.

If you've been asked for a review there's a good chance you're the more senior
developer (at least in that competence area). It can be tempting to request
changes just because the code "looks ugly" or maybe because that doesn't look
like something you would write... That's not the way you should do it: look for
real problems, effective solutions and give developers the freedom to write the
code in their style within the project guidelines.

![](https://cdn.sanity.io/images/kqgmf0g2/production/eacaebf6b0ca46c088f79d4baeef17bc69419e5a-499x341.gif?fit=clip)

### ✅ Meaningful Use of Git

So, the code looks solid, now onto the commits. Why are commits so important?
I think of the git history as a ball of yarn that needs to be untangled: would you
prefer the thread to be neatly rolled around... or would you prefer it to be randomly
put together just for the sake of building a ball form?

This makes sense to me because we've always used [Trunk Based Development][trunk] so
our projects' `master` history is a single line of commits with each commit connecting
(hopefully) to the following one, in a single stream of changes. As the features grow and
evolve, the git history linearly represents what happened and why.

With commits following one another it's helpful to try to tell a story with [good git
messages][git-messages] and overall common sense. I ask for changes on a PR when:

- meaningless history added (code is added and removed within the same PR)
- lots of changes and few commits (history is not explained properly)
- lots of commits and few changes (meaningless history probably added)
- commits explaining what the code does instead of saying why it does it
- merge commits (rebasing is a tidier way of making changes on PRs)
- commits not explaining what's happening (the infamous "fix the fix")

A lot of my time goes into reviewing git messages and it can sometimes feel like a
chore (in particular for smaller projects) nonetheless understanding clearly
what and why a particular piece of code is there is crucial for long term success
of a team of developers. On long term projects developers often forget what happened
a year ago, not to speak of new developers picking up the project later down the road.

![](https://cdn.sanity.io/images/kqgmf0g2/production/528c59f74aa0bd3b3a7ab8c1f93c258813f22db0-392x208.gif?fit=clip)

##  💅 Tips and Tricks

And that's pretty much it! I'll end this post with a final list of random things
that I find helpful:

* automate everything that can be automated
* giving reviews will help you write reviewer-friendly code, encourage everyone to review code
* speak to your team so that they know you don't hate them
* practice [Radical Candor][radical-candor]
* add gifs and funny pictures once in while to a review, a good laugh will set the right mood
* you're not on Twitter, don't troll around
* always explain why, never say "change this" without actually providing some examples
* if everything else fails, schedule a pairing session
* schedule your "review time" (I generally do 80% code/20% reviews)

A Guide to Effective Pull Request Reviews

## Motivation

At the very beginning, HTML was among the first and few technologies enabling
creation of web documents. Not long, JavaScript was introduced, sprinkled here
and there, drop-down menus and simple animations started to appear. Eventually,
the web advanced from simple static websites to highly-interactive asynchronous
web pages.

The web has evolved and so did [Ruby on Rails](https://rubyonrails.org/). The
framework now provides improved JavaScript tooling, including integrations for
both [yarn](https://yarnpkg.com/en/) package manager and [webpack](https://webpack.js.org/) module bundler -
de facto choice in the JavaScript community. Out of the box support for these tools
facilitates creation of rich client applications. We can now easier than ever build
Rails-backed applications with modern tools like [Vue](https://vuejs.org/), [React](https://reactjs.org/) and [Angular](https://angular.io/).

However, as we develop our applications with modern JavaScript libraries, a new
concern emerges. Feature specs that once brought confidence are now becoming
increasingly brittle. Specs that once steadily navigated through almost static web
pages now stumble and fall in an asynchronous world of JavaScript.

Hence, similarly to how webpack and yarn were previously introduced to *build*
modern applications, we further introduce [Cypress](https://www.cypress.io/) to *test* them. Particularly,
in this post, we look at Cypress as an alternative tool for writing and executing
feature specs. We explore the key points that make it stand out among other web
automation tools. Finally, we demonstrate how to integrate Cypress into a Ruby on Rails
development cycle by setting up tests in both local and CI environments.

## Cypress

Cypress is a JavaScript end-to-end testing framework. It is an all-in-one solution
that enables one to both write and execute tests that run in the browser. In a
Rails project, Cypress takes place of both Capybara and the underlying web driver.

## Cypress vs Selenium

Without doubt, Capybara is the most popular and widely adopted solution for integration
testing in Rails. It provides a robust interface to communicate with the browser
through a web driver. Although Capybara is agnostic of the installed driver,
[Selenium WebDriver](https://github.com/teamcapybara/capybara#selenium) is the prevailing choice among Rails developers.
As Selenium is the most widespread solution also beyond Rails, it is therefore important
to understand the difference between Cypress and the combination of Capybara/Selenium.

The key difference between Cypress and Selenium lies in their ways of communication
with the browser, i.e. browser automation. With Selenium, all communications are
done through an external to the browser driver (the WebDriver). To simulate user
actions, Selenium queries the browser by sending remote calls through the network and
then extracting the desired information from the responses. Cypress, on the other
hand, doesn't involve any network communication. It lives directly in the browser
and runs the tests in the same run-loop as the client application. That is, Cypress
tests are right there - in the browser, sharing the same context with your application.

As an outside process, Selenium is not able to react to events in the same run-loop.
Events are thus processed asynchronously, can be overlooked and network delays may
be introduced. This may lead to test flakiness and longer execution times.

In contrast, by sharing the same JavaScript event-loop with your application, Cypress
is synchronously notified of all events as they occur leading to more reliable test
execution. Removing the network layer allows Cypress to execute tests as fast as
the browser is capable of rendering.

The browser-integrated architecture of Cypress accounts for it's quick and reliable
test execution. Sounds promising. But let's see it for ourselves. Next move: install
Cypress in a Rails project. You can find the source code for the demo project [here](https://github.com/nebulab/cypress-store).

## Cypress on Rails: hands-on experience

### Application setup

We want to quickly bootstrap a Rails application with some logic, data, and views
already in place so that we can focus on the testing part. A fresh installation
of [Solidus](https://github.com/solidusio/solidus) will do the job. Solidus is a
highly customizable ecommerce platform.  By adding Solidus gem to our project we
get a default store implementation right out of the box. Bellow is an outline of
all required application setup steps:

1. Create a new Rails project, use [Postgresql](https://www.postgresql.org/) for the database and skip the test files:

```bash
$ rails new cypress-store -d postgresql -T
```

2. Add Solidus to the project by installing two new gems and running their
included generators:

```ruby
# Gemfile

gem 'solidus'
gem 'solidus_auth_devise'
```
```bash
bundle exec rails g spree:install
bundle exec rails g solidus:auth:install
bundle exec rake railties:install:migrations
```

3. Run the rails server and navigate to the index page, you should be greeted with
the default store landing page:

```bash
bundle exec rails s
```

At this step, we have a full-fledged online store. One might want to tweak some
styles before sending it to production, but for our testing purposes, it's just
what we need. We are now ready to setup Cypress.

### Cypress setup

Similarly to how [react-rails](https://github.com/reactjs/react-rails) gem is used
to integrate React components with Rails views, we will use [cypress-on-rails](https://github.com/shakacode/cypress-on-rails)
gem to integrate Cypress with Rails tests. The new gem is a light wrapper around
Cypress that augments its functionality allowing us to prepare application state
using factories or custom Ruby code. Following the gem's getting started [guide](https://github.com/shakacode/cypress-on-rails#getting-started),
add the cypress-on-rails gem to the Gemfile and run the generator:

```ruby
# Gemfile

group :test, :development do
  gem 'cypress-on-rails', '~> 1.0'
end
```
```bash
bin/rails g cypress_on_rails:install
```

This will both add the cypress npm package and setup the Ruby integration. To ensure
that Cypress is ready to run tests against our application, run the application
server in a test environment on port 5002 and in a separate window run Cypress:

```bash
# start rails
bundle exec rails server -e test -p 5002

# in separate window start cypress
yarn cypress open --project ./spec
```

You might also need to precompile assets before running Cypress. The command `cypress open`
will launch a test runner window with some sample tests scaffolded for us by Cypress.
We will move on to substitute the sample tests with our own. Now, notice how simple
it is to add Cypress to a Rails project, a single gem and no external dependencies
like servers or drivers required.

However, let's throw in a few more gems to help us with arranging the application
state. We want to empty the database before each spec and then create the data
required by each test scenario.

As usually, we delegate the database cleaning job to the [database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) gem.
Add the gem to the project and then key in the bellow scripts:

```ruby
# spec/cypress/cypress_helper.rb

require 'database_cleaner'
```
```ruby
# spec/cypress/app_commands/clean.rb

DatabaseCleaner.strategy = :truncation
DatabaseCleaner.clean
```
```js
# spec/cypress/support/index.js

import './commands'
import './on-rails'

beforeEach(() => {
  cy.app('clean');
});
```

The above scripts configure the gem and then run it (`cy.app('clean')`) before
each integration test. Now lets prepare the test data with FactoryBot. Add the
`factory_bot_rails` gem to the project together with the following code:

```ruby
# spec/cypress/cypress_helper.rb

require 'database_cleaner'
require "factory_bot"
require "spree/testing_support/factories"
require "carmen"

Dir[Rails.root.join("spec", "support", "factories", "**", "*.rb")].each { |f| require f }

FactoryBot.find_definitions
```

We now have access to both the FactoryBot library and all the factories provided
by Solidus (e.g. users, orders and products).

### Add Cypress tests

Some online stores require their customers to sign in prior to the checkout. Solidus
comes with user session management functionality built-in and for us it's a great
test subject to begin with.

Our first test will verify that only registered (persisted) users can sign in. Users
that cannot be found in our database will be presented with the corresponding sign
in failure message.

Following the Arrange-Act-Assert (AAA) testing pattern, we first arrange the application
state for our planned scenario. We will execute our tests against an application
with one existing user. We will use a user factory imported from Solidus. Key in
the following:

```ruby
# spec/cypress/app_commands/scenarios/sign_in.rb
FactoryBot.create(:user, email: 'user@example.com', password: 'test123')
```

With the state arranged, we move on to describe user actions and assert the desired
outcome. Note that Cypress leverages other well-known libraries to write and organize
tests. Specifically, Mocha provides TDD-like syntax to structure the tests
(think decribe() - beforeEach() - it()). Likewise, Cypress wraps and extends Chai
for writing assertions (think should). Moreover, with cypress-on-rails gem we are
able to run our factory defined above by calling cy.scenario('sign_in'). Type in
the following:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
	  cy.scenario('sign_in');
  });
});
```

Great, with above we declared that we want our `sign_in` state preparation script
to run before any of the following tests. Now, let's describe a scenario in which
an existing user attempts to login:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    cy.get('#link-to-login').click();
    cy.url().should('include', '/login');
    cy.get('[name="spree_user[email]"]').type('user@example.com');
    cy.get('[name="spree_user[password]"]').type('test123');
    cy.get('input.button')
      .contains('Login')
      .click();
    cy.get('.flash.success')
      .contains('Logged in')
      .should('be.visible');
  });
});
```

The test code is self-explanatory. The user visits the index page and clicks on
the login button, which redirects him to the login page. On the login page, the
user enters his valid credentials and clicks "Login" button. As the credentials
are valid, we expect a login success message to be displayed. Now let's verify
that a user with invalid credentials cannot sign in:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    ...
  });
  it('does not sign in user with invalid credentials', () => {
    cy.get('#link-to-login').click();
    cy.url().should('include', '/login');
    cy.get('[name="spree_user[email]"]').type('wrong_email@example.com');
    cy.get('[name="spree_user[password]"]').type('test123');
    cy.get('input.button')
      .contains('Login')
      .click();
    cy.get('.flash.error')
      .contains('Invalid email or password.')
      .should('be.visible');
  });
});
```

It's not ideal, the duplicate code is screaming at us. We will return to it, but
for now, we focus on executing the tests. Thus, we run the server and the test
runner as we did previously. Running the tests we should see the Cypress test
runner in action:

![](https://cdn.sanity.io/images/kqgmf0g2/production/68cd6c0e45890f82c41b5e8dca129820634d99dc-2104x1252.gif?fit=clip)

Great! Our tests are successfully executed: Cypress test runner opens a new browser
window and mimics the user actions as described in our test scenario.

Notice how the browser window is divided into two parts with the command log on
the left and our application on the right. The command log displays all the executed
commands together with application data such as network requests, page loads, etc.
Notably, with each performed action Cypress takes a new DOM snapshot. This series
of snapshots enables us to navigate the command log and see the state of our application
back in time. Furthermore, remember that we are in the browser. Open the DevTools,
inspect the DOM or click on any command from the log and see it's full description.
One can  also put a `debugger` in the application's code or within a test
scenario (`cy.debug()`) and inspect the state with the browser console. Are you
working with a [Redux](https://redux.js.org/) store? Plug into that too. Overall,
the interactive test runner enables us to better understand our application and
quickly reason about our tests, which makes testing a more enjoyable experience.

Finally, let's refactor our user sign in spec to remove duplicate code. One possible
solution is to use Cypress custom commands, which allow one to group together common
user patterns. We extract the repeating user sign in logic into a custom command:

```js
// spec/cypress/support/commands.js
Cypress.Commands.add('login', (email, password) => {
  cy.get('#link-to-login').click()
  cy.url().should('include', '/login')
  cy.get('[name="spree_user[email]"]')
    .type(email)
  cy.get('[name="spree_user[password]"]')
    .type(password)
  cy.get('input.button')
    .contains('Login')
    .click()
})
```

Cypress will load the new command for us so we can start using it right away:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    cy.login('user@example.com', 'test123');
    cy.get('.flash.success')
      .contains('Logged in')
      .should('be.visible');
  });
  it('does not sign in user with invalid credentials', () => {
    cy.login('wrong_email@example.com', 'test123');
    cy.get('.flash.error')
      .contains('Invalid email or password.')
      .should('be.visible');
  });
});
```
## Add Cypress to CI

Nearly any software product involves an engineering team continuously integrating
small code changes into a shared repository. Without special measures, such frequent
updates by different team members can lead to accumulation of bugs. We want to prevent
that. We will catch the bugs early by running our Cypress integration tests on each
commit to our shared remote repository.

In addition to Cypress we will also run RSpec to demonstrate a real scenario with
various test suites running in parallel. Furthermore, we will also run in parallel
the individual tests within each test suit to decrease the overall build time.
Specifically, we will run Cypress test files in different containers, in parallel.
We will highlight the interesting configuration parts, but please find the full
configuration in the [project repository](https://github.com/nebulab/cypress-store/blob/master/.circleci/config.yml).

First, we declare that our `build_rspec_cypress` workflow consists of two jobs
that we wish to run in parallel:

```yaml
# .circleci/config.yml
workflows:
  version: 2
  build_rspec_cypress:
    jobs:
      - rspec
      - cypress
```

The cypress job will run the required general steps like database preparation and
asset compilation after which it will run the Rails server in the background:

```yaml
# .circleci/config.yml
- run:
	  name: Run rails server in background
	  command: bundle exec rails server -e test -p 5002
	  background: true
```

Yes, just like we did on our local machine. However, we will need to wait for
the server to start before executing integration tests against it:

```yaml
- run:
	  name: Wait for server
	  command: |
	    until $(curl --retry 10 --output /dev/null --silent --head --fail http://127.0.0.1:5002/admin); do
	        printf '.'
	        sleep 5
      done
```

Finally, the server is up and we can run our Cypress tests:

```yaml
- run:
    name: Executes Cypress end-to-end tests
    command: |
      export TEST_FILES="$(circleci tests glob "spec/cypress/**/*.spec.js" | circleci tests split --split-by=timings)"
      export TEST_FILES="$(ruby -rshellwords -e'print ENV["TEST_FILES"].shellsplit.join(",")')"
      echo yarn run cypress run --project ./spec --spec $TEST_FILES
      yarn run cypress run --project ./spec --spec $TEST_FILES
- store_artifacts:
    path: spec/cypress/videos
- store_artifacts:
    path: spec/cypress/screenshots
```

The test files will be split to run in parallel in multiple containers. Change `parallelism: 2`
in the configuration file to the desired number of containers, but make sure it is
lower than the number of test files. Finally, configure CPU and RAM according to
your needs with the `resource_class` entry.

## Summary

In this article, we covered a lot of ground. We started with a discussion of the
new Cypress browser-integrated architecture. From there we initiliazed a new Rails
application to see Cypress in action. We defined our test scenarios with JavaScript
and prepared application state with Ruby. Finally, we setup parallel execution of
Cypress tests as part of our continuous integration process.

Using Cypress for Ruby on Rails Acceptance Testing

Test-driven development (TDD) is one of the most useful skills you'll learn as a software developer since it allows you to add new features, refactor old code, as well as catch bugs you may have missed when coding with ease. With tests, you can rest assured you'll know first whether your changes broke something somewhere.

Nevertheless, it is virtually impossible to consider every use case or to avoid making mistakes, that's why things wreak havoc from time to time. Is there a way to reduce this margin error even more? You can bet on that!

Enter mutation testing. As the name implies, it's a testing method where you add mutants (also known as variations) to your code to make it fail. Some examples would be: changing `true` for `false`, calling an incorrect method, deleting parts of your code, you name it. The success is then measured by the amount of tests that fail.

If a test fails, it means that your code is covering (or handling correctly) that case and there's nothing to worry about. If it passes, that means there's something you're either a) not covering b) not testing correctly, and you must fix that.

## What are my options?

At Nebulab, we're very big fans of [Ruby on Rails][railsservice] and JavaScript. We went looking for mutation testing libraries for these languages and found the following:

* [Mutant][mutant] by [@mbj][mbj], which works for Ruby
* [Stryker][stryker], which works for JavaScript, but has two work-in-progress implementations for Scala and .NET

## How do I get started?

For the sake of brevity, we will only use _mutant_ for this post. Its GitHub repo contains a README you should read in depth, as it contains a guide with nomenclature associated to mutation testing, which you should get familiar with before going any further.

Once that is done and dusted, you need to integrate `mutant` to your project. We're going to add it to [Solidus][solidus], as it's always better to use a real-life example when explaining new concepts, which is as simple as adding the following line to Solidus' `Gemfile`:

`gem 'mutant-rspec', '~> 0.8.24', require: false`

Then, run `bundle` to install the newly-added dependency.

If you're running the above command for the first time, you shouldn't have any problems. Otherwise, you might need to run `bundle update` to get things up and running.

Worth noting that there's also an integration with [`minitest`][minitest].

And that's it! You don't have to do anything else, `mutant` is now available for you to use on your project. But how do you use it?

## Killing mutants

Unlike other testing libraries, you don't run `mutant` against a specific test file or scenario, but rather against example group descriptions, like this:

`bundle exec mutant --include lib --require spree --use rspec "Spree::Api::CouponCodesController#load_order"`

That particular action for that controller has two mutants that will make the specs pass; that means there's something we're not testing/covering and we need to kill the mutants (make them fail)

In this case, we're not testing how our endpoints must respond when:

* an order is not found
* passing an argument other than an order number

How can we fix this?

Under `Spree::Api::CouponCodesController#load_order`, we can replace `params[:order_id]` with the `order_id` method found under `Spree::Api::BaseController`, which returns all the possible attributes passed as an argument when searching for an order. While this is not directly related to the killing of a mutant, it allows us to fix possible bugs in advance.

Now, to properly kill the mutants, under `api/app/controllers/spree/api/coupon_codes_controller.rb`, we'd need to add the following tests:

```ruby
describe '#load_order' do
  context 'when trying to load a non-existing order' do
    it 'returns an error' do
      post spree.api_order_coupon_codes_path('not_found'), params: { coupon_code: 'not_found' }
      expect(response.status).to eq(404)
      expect(json_response).to eq({
        "error" => I18n.t('spree.api.resource_not_found')
      })
    end
  end
  context 'when passing an argument other than an order number' do
    it 'returns an error' do
      post spree.api_order_coupon_codes_path(self), params: { coupon_code: 'not_found' }
      expect(response.status).to eq(404)
      expect(json_response).to eq({
        "error" => I18n.t('spree.api.resource_not_found')
      })
    end
  end
end
```

And that's it! You just killed two mutants that were dwelling within your codebase, expecting to crash your application when you least expect it 🎉

There are two caveats when implementing mutation testing that you need to take into consideration:

* Mutation testing is slow, as it requires a lot of computational power. Unless the project you work on can afford to apply it to the whole spec suite, it's better to use it only where absolutely required (i.e.: methods / modules / classes you want as bug-free as possible) or if the project is small enough.

* Equivalent mutants, which are mutants that modify your code in a way that makes it behave as you'd expect it. While this might help you write better, non-redudant code, it also makes a lot of (white) noise, which might be very annoying on bigger codebases.

I also noticed that the output is not consistent for failing specs, at least on this scenario. I'm not sure whether it is the expected behavior, a bug on the parser, or `mutant` requires modifications to properly work with Rails engines, but it was very annoying to receive a different output everytime I ran specs for the aforementioned controller.

## Closing notes

I think mutation testing adds a lot of value to your projects and it's really worth the effort, as it allows you to reduce redundancy within your codebase, remove dead code, forces you to leave no stone unturned and, as `mutant`'s README says: coverage becomes a meaningful metric.

I plan to propose a proof of concept of this testing method for Solidus in the near future. If you wish to keep track of this idea, you can do so [here][fork].

What do you think about this testing method? Have you implemented it before on one of your projects? How well did you fare? Let us know in the comments below!

[mutant]: https://github.com/mbj/mutant
[mbj]: https://github.com/mbj
[stryker]: https://github.com/stryker-mutator/stryker
[solidus]: https://solidus.io/
[minitest]: https://github.com/mbj/mutant/blob/master/docs/mutant-minitest.md
[fork]: https://github.com/aitbw/solidus/tree/aitbw/poc_mutation-testing
[railsservice]: https://nebulab.com/ruby-on-rails-development/

An Introduction to Mutation Testing

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

100% code coverage, right? Yes, I know, you don't merge code in master that is
not fully tested and all that stuff. Yet I'm almost sure there's one thing
that you may be pushing to production without any tests on it: your data
migrations.

For example you could have this code:

```ruby
class RemoveEmailFromUsers < ActiveRecord::Migration[5.1]
  def up
    # Before dropping the email column from users table let's
    # create a new record with that email on the emails has many association.
    users.find_each do |user|
      user.emails.find_or_create_by(value: user.email)
    end
    remove_column :users, :email
  end
  def down
    add_column :users, :email, :string
  end
end
```

How do you test the code into the `up` method that creates a new record on a
newly added association between `User` and `Email` before removing the `email`
column from the `User` table?

It's a pretty common scenario and you could think that this logic should live
into a separate object that you can test in isolation. I agree, but you still
can't really test it since if you call that object with the last version of
your database schema (after this migration run), you'll have an exception
since `User` has no more the `email` column. 🤷‍

This example is easily fixable by just stubbing the email message on any
instance of User:

```ruby
allow_any_instance_of(User).to receive(:email).and_return(["test@email.com](mailto:%22test@email.com)")
```

This would probably fix it, but if you have a complex migration to run, you
may want to perform some more high level tests of how the system works when
the migration happens.

The good news is that you can do that. The mechanism is quite simple:

- Rollback to the migration that precedes the one you under test
- Add data to your database
- Set expectations
- Re-migrate the migration under test up

Let's make an example, we have these migrations:

```
db/
  migrate/
    20181110082123_do_cool_things_with_database.rb
    20181204143322_create_emails.rb
    20190106184413_remove_email_from_users.rb
```

If we want to test that the new association's record between User and Email
is correctly created by this migration we have to:

- Rollback database to `20181204143322_create_emails.rb`
- Create some users with the `email` field filled
- Set the expectation that for each user a new `Email` record has been created and associated with that same user
- Re-Run `20190106184413_remove_email_from_users.rb` migration.

This is how our code will look like:

```ruby
require 'rails_helper'
require Rails.root.join('db/migrate/20190106184413_remove_email_from_users.rb')
RSpec.describe RemoveEmailFromUsers do
  let(:migrations_paths) { ActiveRecord::Migrator.migrations_paths }
  let(:migrations) { ActiveRecord::MigrationContext.new(migrations_paths).migrations }
  let(:previous_version) { 20181204143322 }
  let(:current_version) { 20190106184413 }
  subject { ActiveRecord::Migrator.new(:up, migrations, current_version).migrate }
  around do |example|
    # Silence migrations output in specs report.
    ActiveRecord::Migration.suppress_messages do
      # Migrate back to the previous version
      ActiveRecord::Migrator.new(:down, migrations, ActiveRecord::SchemaMigration, previous_version).migrate
			
      # If other tests using User table ran before this one, Rails has
      # stored information about table's columns and we need to reset those
      # since the migration changed the database structure.
      User.reset_column_information
      example.run
      
      # Re-update column information after the migration has been executed
      # again in the example. This will make user attributes cache
      # ready for other tests.
      User.reset_column_information
    end
  end
  context 'when there are users with email' do
    let(:user_with_email) { create(:user, email: 'test@email.com') }
    it 'creates an Email associated with the same user' do
      expect { subject }
        .to change { Email.all.size }
        .from(0)
        .to(1)
      expect(Email.first.user).to eq user_with_email
      expect(Email.first.value).to eq 'test@email.com'
    end
  end
end
```

**Gotchas**

There is a case when running migrations within an example execution makes
Ruby on Rails generate a particular exception:

```
ActiveRecord::StatementInvalid:
  Mysql2::Error: SAVEPOINT active_record_1 does not exist: ROLLBACK TO SAVEPOINT active_record_1
```

This only happens with MySql in combination with cleaning up specs with a
transaction strategy. The latter can be both set with the RSpec configuration
`config.use_transactional_fixture` to `true`, which is the default (you should
find that in your `spec/rails_helper.rb`) or via DatabaseCleaner `transaction`
strategy. The reason behind this error is basically that we are asking to RSpec
to rollback the MySql database to the previous state with a transaction
rollback, but it can't handle rollbacks of schema changes as well.

There is also a quick way to fix this: we just need to use `truncation` for
all those specs by adding:

```
# Without DatabaseCleaner
before(:all) { self.use_transactional_tests = false }
after(:all)  { self.use_transactional_tests = true }
```

or:

```
# With DatabaseCleaner
before(:all) { DatabaseCleaner.strategy = :truncation }
after(:all)  { DatabaseCleaner.strategy = :transaction }
```

**Is testing migrations really needed?**

I don't know! These kind of specs looks fragile and poorly maintainable, even
if they can be removed once the migration has been pushed since they do not
provide any regression value. I still think they are worth it for some very
**critical data migrations** or in **OSS projects**, where it's important to
keep backwards compatibility in mind; that migration could run in the future,
when code is changed and no one can ensure it's still valid. Also, I think
they can help writing code with confidence and help thinking about all
possible scenarios.

It's worth mentioning that this post comes from a real need I had while
working on [Solidus,
the open source eCommerce platform based on Ruby on Rails](https://solidus.io) that we use.
I created [a PR that removes a field from the database](https://github.com/solidusio/solidus/pull/3028) and I provided three ways to
handle the data migration for Solidus users.
Having the ability to test the migration really helped me being sure all
approaches works without the need to test them by running the migration on
specifically crafted databases. Also, I didn't know when this migration will
be executed since it will run when users upgrade Solidus to the version that
contains PR's commits. At that point, without migration tests, we couldn't
be sure that the migration is still working.

Testing Database Migrations in Ruby on Rails

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