Sign Up
  1. Znode
  2. Solution home
  3. Developer Documentation - V10
  4. Storefront Development - V10

Webstore Troubleshooting Guide

TABLE OF CONTENTS

Introduction

This article is a step-by-step guide to help developers and customers debug and troubleshoot issues and resolve common issues in the Webstore and Page Builder environments. Ideal for teams working with Next.js, React, it outlines into two main sections one is for troubleshooting the issues and its history and another is for developers to debug the issue in a web store or Pagebuilder.


Troubleshooting & Debugging(App Development)


Client Issues History

Issue DescriptionHydration Mismatch
Troubleshooting or RCA Details
  •  Mismatch between server-rendered content and client-rendered content
  • Non-deterministic Rendering
  • Browser-only APIs (window, localStorage, etc.)
Type of IssueEnvironment
SolutionAvoid a mismatch between server-rendered content and client-rendered content


Issue Description Component Not Rendering in webstore
Troubleshooting or RCA DetailsThe component was not registered in your shared components
Type of Issueconfiguration
Solution
  • Confirm the component is registered correctly in your shared-components or parent component, where you are importing the component
  • Ensure required props are passed and default values are set where necessary
  • Ensure the component is loading from the alias configured in the tsconfig.js file and export


Issue Description Component Not Appearing in Page Builder UI
Troubleshooting or RCA DetailsThe widget is missing from the visual editor component list
Type of Issueconfiguration
Solution
  • Confirm the widget is registered in the correct config file
  • If using a theme, make sure it's included in root-config.ts via extendConfig.
  • The component folder is created in the correct path
  • packages/page-builder/src/configs/base-config/widgets/ui/-widgets/Grid



Issue Description Visual Editor Crashes After Widget Integration
Troubleshooting or RCA DetailsMissings config
Type of Issueconfiguration
Solution
  • Wrap render logic in error boundaries or use defensive coding for undefined/null props.
  • Log received props and config values using console.log or debugger.
  • Use try-catch for custom render logic, especially when looping through dynamic data.


Issue Description Theme-Level Widget Overrides Not Taking Effect
Troubleshooting or RCA Detailsoverride is missing in the root-config.ts
Type of Issueconfiguration
Solution
  • Confirm the override is defined in the root-config.ts
  • Avoid name conflicts with base widgets unless intentionally overriding.
  • Restart the dev server after config changes.


Issue DescriptionEdits in Page Builder are not visible in Webstore preview
Troubleshooting or RCA DetailsThe keys were missing in the  .env file
Type of Issueconfiguration
Solution
  • In both .env files webstore and pagebuilder: 
IS_DEBUGGING=true


  • In Webstore .env:
ENABLE_CACHE=true

  • Restart both apps to apply changes


Issue DescriptionThe publish button will not display in the page builder, so we can't save changes and export to the webstore
Troubleshooting or RCA Details Settings were missing
Type of IssueConfiguration
SolutionOpen the following file in the Page Builder codebase:
packages/page-builder/src/constants/visual-editor.ts

Update settings in the visual editor constants file in :
ENABLE_CACHE=true

This enables the “Publish” button and allows saving JSON layout files.


Issue DescriptionUnable to Commit Changes in Webstore or Page Builder
Troubleshooting or RCA Details Spell check or linting 
Type of IssueConfiguration
SolutionPre-Commit Hook Overview
Our repo is configured with a husky pre-commit hook that performs the following steps:
Spell Check (using cspell)
Linting (npm run lint)
Build Check (npm run build)
Commit Message Validation (via commitlint)


If any of these steps fail, your commit will be aborted to maintain code quality and consistency.



Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.

Storefront Development - V10