Moving from a Shopify theme to Headless Shopify: What's involved?

Absolutely – existing Shopify stores that are not currently headless can transition to a headless architecture at any time.

In truth, there are only a couple of small tweaks that need to be made from your Shopify backend in order to "activate" things and get it ready for a headless build-out. These are related to apps, namely enabling the Headless app, and/or creating a Custom App and configuring its scopes in order to implement the desired headless implementation.

The headless build can get underway while your existing Shopify store continues to operate as usual.

Is there a migration process involved when going Headless with Shopify (if we're already on Shopify)?

As an agency with rich experience in Headless Shopify, we can attest that there isn't a straightforward answer to this question.

In truth, it depends. 

There is often somewhat of a data migration / transformation / consolidation process involved, but this isn't the case for every build. In theory, the development process will principally aim to decouple the storefront from the Shopify backend; but it's rarely as straightforward as this in practice. 

This is because brands will typically have an extensive list of preexisting frustrations that they wish to solve with the pivot to headless architecture; it's rarely just about decoupling the storefront. Most of the time, businesses aren't opting to go headless merely to "go headless"; but rather as a route to resolving years of compounded operational & user experience frustrations that they've had to accept as a result of platform inflexibility.

In reality, resolving many of these embedded frustrations often involves much more than just decoupling the storefront. And for that reason, there is indeed sometimes a process of data re-architecture and re-housing that takes place as part of the wider implementation.

Example: The simplest form of migration (storefront only)

If you're already using Shopify, going headless doesn't have to involve any data migration.

For straightforward builds that intend to remain heavily invested in the Shopify ecosystem, moving from Shopify to Headless Shopify can be achieved without any impact on the overall structure of your Shopify backend or any of its data.

In this case, any "migration" would pertain to the frontend itself; and its decoupling from Shopify. Traditional Shopify sites use Liquid themes to style and skin the storefront, and even the most straightforward of headless Shopify implementations will effectively require a "migration" of the storefront, away from the Shopify platform and to Javascript-based frontend architecture. Note: You can't literally migrate a Liquid theme to headless, it's rather a migration of architecture.

Example: A highly-involved move to Headless Shopify including migration of content, theme/experience, apps.

Some moves to Headless Shopify are significantly more involved than others. While taking an existing Shopify store Headless does not require a conventional site migration “in and of itself”, large and complex builds can certainly involve a transition which is akin to a migration. 

In some cases, we’ll also recommend migration of certain types or formats of content to other entity types within Shopify, or to an external (but connected) application that makes better sense for the intended use case.

For example, a highly-involved move from Shopify to Headless Shopify may present the following requirements:

• To maintain the existing look, feel, and functionality of the existing store once headless
  • This would require rebuilding of the storefront design, layout, and experience (together referred to as the “frontend“ or “storefront”) — in a like for like manner. While the old/current frontend will exist as a Shopify theme with Liquid templates, the new frontend would exist as a bespoke interface built within a JavaScript framework. 
    
    Styling, supporting media assets, and general hierarchy of the DOM will all be replicated from the Liquid templates into the JS frontend, with the aim of matching the existing store design as closely as possible. 
    
    There isn’t an effective shortcut to this; retaining the same storefront UI requires rebuilding, but this is the perfect opportunity to make efficiencies and gains to maintainability by refactoring any clunky styling techniques that exist within the current theme with more reusable, structured ones in the JS environment. 
    
    This process can be speed up significantly if we utilize a JavaScript-ready UI framework or design library, such as Tailwind. 
• To rearchitect the content management approach by introducing a headless CMS into the headless stack, including migration of existing editorial or marketing content currently housed in Shopify to the external headless CMS.  
  • The introduction of a Headless CMS into a decoupled Shopify build serves as a mechanism to better manage, display, and integrate content into the storefront. 
    
    Popular headless CMSes such as Sanity, Strapi and Contentful provide editorial tooling that far exceeds that of Shopify’s core content management capabilities, providing a more specialised way in which to create content. 
    
    If we choose to implement a headless CMS for certain types of content, such as blog posts, landing pages, or for marketing-led microsites, it’s very possible that some existing content in the Shopify store will need migrating out and into the headless CMS. 
    
    One common architecture issue in Shopify is the overuse of ill-fitting metafields once content volume begins to grow. With content of a sizeable volume, metafields are often not the most intuitive way of storing this. 
    
    Migrating this data out to a CMS that is more suited to complex content architecture can do wonders for editorial teams. This process does involve a migration in the traditional sense, whereby candidate content in the shopify store will be moved over to the CMS via a process of field mapping, transformation, and programmatic data entry into the CMS. 
    
    At Cocoon, we don’t use exporters, connectors, or prebuilt tools to do this—but instead write a custom data migration pipeline from scratch, specific to each store we’re working on. We do this because no two content architectures are the same, and how each store uses fields and enters content tends to differ, fairly broadly. 
    
    Additionally, each store will have different requirements in terms of what gets migrated, which data is transformed, and where it gets mapped to.
• For a store with hundreds or many thousands of variants and option combinations, to refine the backend approach to which products are managed, such as moving to an external or custom PIM as the single source of truth, and syncing products into Shopify in a radically different format and structure to Shopify’s native option and variant structure.
   
• To move customer accounts off the Shopify platform and instead to a best-in-class customer account platform with a view to implement SSO authentication into the subsequent headless Shopify storefront.
  • Shopify provides its own native authentication management, for customers to login to your store. Headless builds are not restricted to Shopify’s native customer authentication platform, however, and can implement account access using any third party authentication provider of their choosing.
    
    The choice of authentication provider is highly specific to the store, what it aims to achieve, and importantly whether Shopify’s native authentication poses any current challenges for the store and its ideals. Good use cases for integration with a third party platform are SSO, a stronger level of control, implementation of a specific auth flow, etc. If a store has existing customers, we’ll need to map the customer data, or at least some of it, to the external auth provider of choice through field mapping and a migration script or pipeline. 
    
    This will ensure the user’s account exists in the new provider so that they’re able to authenticate via the new headless storefront. If the existing Shopify store is using legacy customer accounts (with a password), the password cannot be migrated or ported over. 
    
    If the new provider is also to use a password, customers will need to reset their password when logging in via the headless frontend for the first time. 
    
    If moving from legacy customer accounts to an external provider with passwordless or SSO auth, this doesn’t pose an issue as users wouldn’t need a password on the headless storefront anyway, as they’ll simply gain access through the new auth flow by confirming their identity via other means.
    
    If your store is on the new customer accounts, moving to another SSO or passwordless provider again doesn’t present much friction for end users, because they’ll be able to login without having to worry about a password reset. In the event of moving from Shopify’s passwordless login to a password-only or password-supporting external auth provider, of course users would have to set a password on the new storefront upon first login (coupled with email verification).
    
    Moving the storefront authentication away from Shopify doesn’t equal a disjointed administration experience. 
    
    Our builds continue to register each user as a Customer in Shopify, just that their method of authentication (the provider) changes. In this way, you’re still able to see the individual customer who placed an order in Shopify, view their account/profile in Shopify, and connect any apps that integrate with Customer Accounts (such as remarketing apps, etc) in the same way you normally would. This allows us to create a connected ecosystem for you that provides the added benefits of a best-fit authentication provider and login flow.
• To reimplement either custom or external third party solutions to replace select Shopify Apps that may not be candidates for a move to headless. 
  • While there are plenty of Shopify apps that do work with headless, there are also those that don’t. Where this poses a problem, needed functionalities will either have to be supplied by an alternative app that supports headless or custom storefront setups, or better-built from scratch directly into the headless frontend.  Any data housed within the existing app will be migrated out to either a custom data store or transformed and imported into a supporting app that allows for bulk data import or migration. 

Although this sounds involved, many of our larger headless Shopify projects involve similar specifications (often More), making this example a fairly typical representation of a more widespread restructuring along with the headless build-out.

We're the experts in Headless Shopify.

Your search for answers ends here. Discover our services.

Explore Headless Shopify Services

While the actual switch to headless alone might not involve a migration, the reality is that often, brands choose headless because their setup and requirements are naturally more complicated, and they’re now coming up against limitations. In practice, therefore,  it’s entirely likely that a large move to headless for a complex Shopify store with rich architecture will indeed involve some level of “migration”, when it comes to certain elements. 

How long does it take to move from a Shopify theme to Shopify headless?

For a moderately-sized, frequently trafficked production store of typical complexity (involving apps, variable products, a custom theme, blog posts, comments, reviews, and user accounts), the process to going headless could take a few months at best. 

However, in reality—the actual amount of time can vary significantly, and could definitely extend beyond six months for large and complex projects.

Here are some factors that can influence the build time:

1. The requirements of the build itself.
   
   Headless Shopify builds rarely comprise of simply building out a JavaScript frontend and hooking it up to Shopify’s existing APIs. Most of our builds have some pretty advanced nuances and business-specific complexities that make each implementation fairly unique. Specific requirements in terms of system design, integration, and custom functionality can add significant time to the build, especially when you factor testing and any associated bug-fix into account.
    
2. Size & experience of your development team/agency partner.
   
   Because these builds can be so intensive, manpower is of course one factor that contributes to overall development time. The larger and more experienced (in headless Shopify builds) your development team is, the faster you can anticipate a conclusion. Size doesn’t indicate better resulting quality, mind you. Greater experience – in headless technologies specifically – will go a long way in hastening the development process, so it’s crucial to select a dedicated agency partner with headless expertise.
   
   One crucial part of selecting an appropriate partner is not only their familiarity with Shopify, but more importantly–their JavaScript prowess. Headless build-outs on Shopify primarily involve JavaScript code, not Shopify configuration. It's therefore essential that you identify a development partner who has the required all-round skill set and internal tool suite to deliver the outcome you're after. Developers more familiar in Liquid templating are not necessarily going to possess the deep JavaScript know-how that would be required to build out & support a functional, high-stakes headless storefront.
    
3. Whether interface and experience design forms part of the build.
   
   Interface and Experience Design forms a crucial part to development of any e-commerce store, but depending on the project goals, it may or may not be part of the build scope. Often, our clients will use this opportunity to commission a complete redesign of the storefront, whether this is provided by our team or an external design agency, so that everything gets a refresh all at once. 
   
   However, we encounter just as many cases where clients want to retain the current frontend design, but conduct a radical overhaul of their tech implementation by taking their Shopify store headless. We refer to this as a “lift and shift” of the design element, though in real terms it’s quite a bit more involved than the term suggests.
   
   It’s crucial to remember that the design phase (what we refer to as Interface Design) is not equal to the frontend development phase. The design phase, which usually involves planning and conceiving of wireframes, prototypes, high fidelity mockups, and any revisions, can take weeks to months for a large store, and it usually makes sense to complete the majority of the design phase prior to beginning on frontend development, to reduce the number of revisions shared across teams. 
   
   A note on retaining the existing store design:
   
   For clients who wish to retain their preexisting storefront design and layout, bear in mind that this doesn’t necessarily make the frontend development process any quicker or easier. In our experience, it’s actually sometimes more time consuming to retain the same storefront design, as there’s often a necessity to ensure it has been ported over across platforms in a pixel perfect fashion. 
   
   With likely no design files to work from, porting the existing design in a pixel perfect fashion from Liquid to a Headless frontend takes a meticulous level of detail and is still very time-intensive. As a given, for larger and more complex stores, the intensity of this process is only amplified. 
   
   Porting the existing Shopify theme to a headless stack can be done in a variety of ways, some less time intensive than others, but in many cases the styling library will probably also change as headless builds use different styling techniques for performance and maintainability reasons, such as Tailwind or CSS in JS. 
   
   The absolute quickest option is to port the HTML elements, inclusive of all their current classnames, into the headless build, along with the accompanying CSS files. While this potentially reduces styling time, it’s not going to be the most performance conscious approach in the majority of cases, for a headless build. 
   
   As a result, we’ll typically “rebuild” the design itself utilizing a more appropriate, high performance styling library within the headless build, with a completely revised DOM structure, and then match the new architecture’s styling to that of the existing Shopify theme/frontend. 
   
   This method allows us to ensure that the new frontend implementation is as performant, maintainable, and logically structured as possible, as far as styling and presentation goes. With this approach, we can reduce total DOM size, reduce the size of the bundled style sheets, and ensure that you squeeze as much performance as possible out of what will appear to be an identical frontend design. 
   
   Talk about bang for your buck! 😎
    
4. Whether Headless CMS development will form part of the build
   
   For content rich sites, we’ll often couple Shopify with a fit-for-purpose headless CMS, so that your editorial and marketing team is better able to create rich content experiences and has access to all the appropriate tools. 
   
   Architecture and integration of a headless CMS involves additional development time, on both the backend and frontend. Builds that are content-heavy and use multiple data sources such as a headless CMS can be expected to take a little longer than projects that rely solely on Shopify, in general. 
   
   The headless CMS will require entity architecture development and content modeling, in addition to development of any custom API queries in order to extract data. If the build involves migration of content from Shopify (or some external platform such as HubSpot CMS Hub) to the headless CMS, then this will also take additional time to complete. 
   
   Beyond the architecture and any content migration, we’ll then need to actually source the data housed in the headless CMS from the frontend, and map this out wherever used across the site. If a third-party, composable search platform is also used as part of the build, the data from the headless CMS will need to make its way into the site’s search index through API connection, which further adds to build time and potential complexity.
    
5. How composable the headless build aims to be (i.e. how modular the stack is and how many third-party platforms & tools will be integrated into the build)
   
   Shopify is built fairly composable by nature, but obviously shifting to headless setup opens plenty of additional doors in terms of tech stack composablility. Depending on how composable your headless build will be, there’ll be a level of development and configuration time involved in connecting all of the stack’s components. 
    

Other stages of a headless Shopify build:

Informal chat? Works for us. 🤘

Contact Cocoon for a no-cost, no-obligation consultation.

Let's talk Shopify

• The frontend development phase
  
  The frontend development phase involves actually building the frontend itself, including implementation of the design, user experience implementation, and the development of any micro-interactions. 
  
  The frontend development process is one of the most involved, and time intensive phases of any large headless Shopify build. This stage can be made more efficient through the use of design libraries, UI frameworks, and SDKs, which provide us with a foundational toolset of ready-made components that can be styled and modified specifically for your store, ensuring that they feel natural and part of the baked-in experience.
  
  Leveraging existing frontend libraries where sensible will allow the headless Shopify storefront to come together quicker and with relatively less friction, while improving future maintainability. 
  
  At Cocoon, we have a toolbox of trusted UI libraries and frameworks, which we selectively draw upon based on the project’s individual frontend needs. We can consult with you on the most logical options for your headless Shopify store, and use these to speed up the development process.
  
  Best practices such as implementation of optimum component reusability can also reduce time lost to code duplication. In the context of headless storefronts, component reusability refers to the best practice of “breaking up” the code base into many small components, which can be imported and reused throughout the frontend , saving time and improving maintainability. 
  
  It also helps us to ensure consistency and that common elements, sections etc look identical everywhere.
   
• Shopify API Integration
  
  The storefront’s going to source data from Shopify via API, and will therefore require the implementation of GraphQL queries and mutations to Shopify’s Storefront API. This is done either via SDK or manually querying the Shopify store via GraphQL, depending on developer preference, the chosen frameworks,  project objectives, and any potential SDK limitations. 
  
  Beyond data sourcing, GraphQL mutations allow the storefront to communicate with Shopify where information needs to be sent from the frontend. These queries and mutations need to be built out within the storefront or its middleware layer, to actually integrate Shopify into the frontend.
   
• App integration via API or scripts
  
  When moving from a traditional Shopify setup to a headless Shopify setup, any existing apps installed in the store will need to be carefully inventoried to determine how compatible they’ll be in a headless environment.  Many popular apps are headless-compatible, and those that aren’t officially can sometimes be reverse engineered to work on a headless storefront. However, there are many frontend apps that won’t work in a headless setup, and those will need to be replaced. Where possible, any problematic existing apps can be switched out for alternatives—or if this isn’t desirable, the provided functionality can be built directly into the headless Shopify storefront in the form of a custom solution that delivers like for like functionality. 
   
• Custom functionalities
  
  Many large headless store builds are fairly complex by nature, which is one of the primary reasons brands come to Cocoon to seek expert consultancy and development services. A foundational component to many of our headless Shopify builds is the development of custom functionalities that are unique to the clients business model or product type. 
  
  These functionalities are therefore built from the ground up, directly into the headless storefront,  as part of the project. This allows for deeply nuanced functionality to be created, while remaining connected and compatible with Shopify through API connections. 
   

Is there any downtime while deploying Headless, when we have an existing Shopify build?

Not really, no – nothing out of the ordinary for a site move in general. Some DNS changes will be required, which might result in a short period of downtime while things propagate. In most cases, propagation can be accelerated by lowering the domain's TTL value ahead-of-time, and in our experience often completes within minutes rather than hours. 

When going headless, an official "go-live" period will need to be coordinated so as things are deployed during a period of lower-traffic (off peak hours) to ensure ample opportunity for testing after initial (re-)launch.