A Non-Technical Guide to Troubleshooting Headless Storefronts

Have you ever been perusing your website, when suddenly you sat up in alarm, proclaiming 'Something is amiss!

Perhaps data is absent, or incorrectly displayed, but due to the nature of your headless tech stack, you don't know where to turn. Could it be Nacelle? Could it be Contentful? The dreaded and inscrutable spaghetti code?

When something is broken or misrepresented on the front-end, it helps to think through the data’s journey: Source (CMS/PIM) --> Nacelle --> Javascript --> Website

The Source

This is the first place to check. If it is product or collection related, head on over to Shopify/Magento/Commerce Cloud. If a product is incorrect, pull up the product and review the description, price, etc.

If it was content related, head on over to the headless CMS (Contentful, Sanity, Storyblok, etc).

Same deal here, identify the content entry that matches what was incorrect on the website, and comb through it to identify where the disparity may have occurred.

Common issues:

- Product or collection not visible on website (make sure Nacelle app is on each product/collection)

- Content not visible on website (make sure content entry has all required fields filled out, and is published)

Nacelle, The Index

If everything looks correct at the source, we voyage with the data to the Nacelle dashboard and check the index.

With tabs for product, collections, and content, use the search bar in the respective index to locate the data that is giving you trouble.

If it isn't there, perform a reindex. If it still isn't there, log a ticket with Nacelle!

If it is there, click into the data entry and 'view json' to look at the data. Does it match the source data? When was it last indexed? How does it compare to what's on the website?

Our main goal here is to make sure:

- That Nacelle has the data entry, ingested during a manual reindex or by a webhook

- That the data entry is up to date, updated via manual reindex or webhook

The Code

If the data is accurate at the source, and has been indexed successfully, it has one more stop before being displayed on the front-end website. That is the codebase.

Nacelle data is delivered via Nacelle's Storefront API to the javascript codebase. Within the codebase, the data is being manipulated to generate the front-end experience.

If the source data looks good, and the Nacelle data looks good, this last step requires a developer or agency to dig into the codebase. They'll review where the issue is being initialized, looking for logic breaks, or other code issues.

The developer can compare local builds against production builds, and use other standard testing methods to isolate and resolve the issue.

By understanding and reviewing the data flow, correcting issues as they are encountered, the front-end website will work properly.

For additional guidance on headless troubleshooting, reach out to your Nacelle Customer Success Manager to set up an enablement session!