Skip to main content

❓ Troubleshooting Guide

This guide provides solutions to common issues encountered when integrating, building, and styling Nodeblocks frontend components.

🎨 Broken, Plain, or "Bad" Styles​

Symptom​

Components render on screen but look completely unstyled. Buttons appear as plain HTML buttons, margins are misaligned, colors are wrong, or default Material-UI elements render instead of the official Basal-branded interface.

Root Cause​

Nodeblocks frontend components are styled on top of a unified, customized Material-UI (MUI) design system. If you render blocks without registering the design system at your application's root, they will fallback to unstyled primitives.

Solution​

Wrap your React application's root (typically main.tsx, index.tsx, or App.tsx) with the <ThemeProvider> and defaultTheme provided by @nodeblocks/frontend-theme (sourced from @nodeblocks-frontend-blocks/packages/theme/src).

Implementation Example​

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import {ThemeProvider, defaultTheme} from '@nodeblocks/frontend-theme';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider theme={defaultTheme}>
      <App />
    </ThemeProvider>
  </React.StrictMode>,
);

🌐 Server-Side Rendering (SSR) & Hydration Failures​

Symptom​

When using SSR-based frameworks (like Next.js, Remix, or Docusaurus), builds fail with errors like: ReferenceError: window is not defined Or you experience hydration mismatch warnings in the browser console.

Root Cause​

Some sub-dependencies and rich interactive blocks access browser-only globals (such as window, document, or navigator) during instantiation, which are unavailable in a Node.js server context.

Solution​

In Next.js, use next/dynamic with ssr: false to force client-side rendering:

import dynamic from 'next/dynamic';

const ListUsers = dynamic(() => import('@nodeblocks/frontend-list-users-block').then(mod => mod.ListUsers), {
  ssr: false,
});

export default function MyPage() {
  return <ListUsers data={[]} listUsersTitle="Members" labels={{}} />;
}

📦 Missing Peer Dependency Errors​

Symptom​

Installing a Nodeblocks package throws warnings/errors during npm install or yields compilation failures such as: Module not found: Can't resolve '@mui/material' or @emotion/react

Root Cause​

To optimize bundle sizes and avoid multiple versions of the same library in your application, Nodeblocks leaves core UI engines (like Material-UI and Emotion) as peer dependencies. You must supply these peer packages yourself.

Solution​

Make sure you have installed the required Material-UI and Emotion engine peer dependencies:

# npm
npm install @mui/material @mui/icons-material @emotion/react @emotion/styled

# yarn
yarn add @mui/material @mui/icons-material @emotion/react @emotion/styled

# pnpm
pnpm add @mui/material @mui/icons-material @emotion/react @emotion/styled

🛑 Action / Click Event Handlers Not Firing​

Symptom​

Clicking tabs, page changes, searching, or deleting chip filters does not change the table data or update the UI state.

Root Cause​

Nodeblocks blocks are built as presentational (stateless) components to allow maximum layout control. They do not maintain internal lists, search keyword states, active tab states, or page counts.

Solution​

You must capture events inside callback props (such as onTabChange, onPageChange, onSearchFieldChange, onSearchSubmit) and update your local react state, which is then passed back down as props.

See the code examples in each block's page (e.g. List Users → Quick Start) to see how to hook up these state bindings.