❓ Troubleshooting & FAQ

Common issues, solutions, and frequently asked questions 🔧

This guide covers the most common issues developers encounter when working with Nodeblocks frontend components and their solutions.

📋 Table of Contents

🚨 Installation Issues
🔐 Authentication & Registry
🔧 Configuration Problems
🎨 Theme Issues
🖌️ Styling & UI Issues
❓ Frequently Asked Questions

🚨 Installation Issues

Package Not Found Error

Problem:

npm ERR! 404 Not Found - GET https://registry.npmjs.org/@nodeblocks%2ffrontend-navbar-block

Solutions:

Check your .npmrc configuration:

# Verify .npmrc exists and has correct content
cat .npmrc

Ensure token is set:

echo $NODEBLOCKS_DEV_TOKEN

Verify registry configuration:

@nodeblocks:registry=https://registry.npmjs.org
@basaldev:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${NODEBLOCKS_DEV_TOKEN}

Authentication Failed (401 Error)

Problem:

npm ERR! 401 Unauthorized - GET https://registry.npmjs.org/@nodeblocks/...

Solutions:

Check token validity:
- Contact Nodeblocks team for a new token
- Ensure token hasn't expired
Verify environment variable:

# Linux/macOS
export NODEBLOCKS_DEV_TOKEN=your_actual_token_here

# Windows
set NODEBLOCKS_DEV_TOKEN=your_actual_token_here

Clear npm cache:

npm cache clean --force

🔐 Authentication & Registry

Cannot Access Private Packages

Problem: Getting 404 or access denied errors for @nodeblocks packages.

Checklist:

✅ .npmrc file exists in project root
✅ Registry configuration is correct
✅ NODEBLOCKS_DEV_TOKEN environment variable is set
✅ Token is valid and not expired
✅ You have access permissions

Quick Fix:

# Check current npm configuration
npm config list

# Verify nodeblocks registry setting
npm config get @nodeblocks:registry

Token Environment Variable Not Working

Problem: Token set but still getting authentication errors.

Solutions:

For current session:

# Linux/macOS
export NODEBLOCKS_DEV_TOKEN=your_token

# Windows Command Prompt
set NODEBLOCKS_DEV_TOKEN=your_token

# Windows PowerShell
$env:NODEBLOCKS_DEV_TOKEN="your_token"

For permanent setup:

# Linux/macOS - Add to ~/.bashrc or ~/.zshrc
echo 'export NODEBLOCKS_DEV_TOKEN=your_token' >> ~/.bashrc

# Windows - Use System Environment Variables

Verify token is loaded:

npm install --verbose

🔧 Configuration Problems

Environment Variables Not Working

Problem: Service endpoints not being loaded from environment variables.

Framework-Specific Solutions:

Vite:

# Must start with VITE_
VITE_USER_SERVICE_URL=https://api.example.com

// Access in component
const userServiceUrl = import.meta.env.VITE_USER_SERVICE_URL;

Create React App:

# Must start with REACT_APP_
REACT_APP_USER_SERVICE_URL=https://api.example.com

// Access in component
const userServiceUrl = process.env.REACT_APP_USER_SERVICE_URL;

🎨 Theme Issues

Components Not Styled Correctly (Missing ThemeProvider)

Problem: Components render with incorrect or missing styles, wrong colors, or broken layouts.

Cause: The ThemeProvider is not wrapping your application.

Solution: Wrap your entire application with ThemeProvider:

// ❌ Wrong - No ThemeProvider
function App() {
  return (
    <div>
      <Navbar ... />
      <SignIn ... />
    </div>
  );
}

// ✅ Correct - ThemeProvider wraps everything
import { ThemeProvider } from '@nodeblocks/frontend-theme';

function App() {
  return (
    <ThemeProvider>
      <div>
        <Navbar ... />
        <SignIn ... />
      </div>
    </ThemeProvider>
  );
}

CSS Variables Not Working

Problem: CSS variables like var(--mui-palette-primary-main) return undefined or don't work.

Cause: ThemeProvider is missing or cssVariables is disabled.

Solution:

Ensure ThemeProvider wraps your app
If using a custom theme, enable CSS variables:

import { createTheme } from '@mui/material/styles';
import { defaultTheme, ThemeProvider } from '@nodeblocks/frontend-theme';

const customTheme = createTheme(defaultTheme, {
  cssVariables: true,  // Must be enabled for CSS variables
  palette: {
    primary: { main: '#your-color' }
  }
});

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      {/* Your app */}
    </ThemeProvider>
  );
}

Theme Customizations Not Applying

Problem: Custom theme colors or typography aren't being applied to components.

Causes & Solutions:

Not passing theme to ThemeProvider:

// ❌ Wrong - custom theme not passed
<ThemeProvider>

// ✅ Correct - pass your custom theme
<ThemeProvider theme={customTheme}>

Overriding all defaults instead of extending:

// ❌ Wrong - loses all Nodeblocks defaults
const customTheme = createTheme({
  palette: { primary: { main: '#8B5CF6' } }
});

// ✅ Correct - extends defaultTheme
import { defaultTheme } from '@nodeblocks/frontend-theme';

const customTheme = createTheme(defaultTheme, {
  palette: { primary: { main: '#8B5CF6' } }
});

Not spreading nested defaults:

// ❌ Wrong - loses primary.contrastText, primary.light, etc.
palette: {
  primary: { main: '#8B5CF6' }
}

// ✅ Correct - preserves all primary properties
import { palette as defaultPalette } from '@nodeblocks/frontend-theme';

palette: {
  ...defaultPalette,
  primary: { ...defaultPalette.primary, main: '#8B5CF6' }
}

📖 See our Theming Guide for complete theming documentation.

🖌️ Styling & UI Issues

Components Look Different Than Expected

Problem: Components don't match the expected design or documentation.

Solutions:

Check for global CSS conflicts:

/* Your global styles might be interfering */
* {
  box-sizing: border-box; /* This might affect component layouts */
}

Use component-specific styling:

<SignIn
  style={{
    maxWidth: '400px',
    margin: '0 auto',
    padding: '2rem'
  }}
>
  {/* Component content */}
</SignIn>

When components don't accept styles:

/* Use higher specificity to override component styles */
#root .your-component-class {
  /* Your custom styles here */
  background-color: #f5f5f5;
  border-radius: 8px;
  padding: 1rem;
}

/* For more specific overrides, use multiple selectors */
#root .product-grid .product-item {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s ease;
}

❓ Frequently Asked Questions

General Questions

Q: Do I need to install all components? A: No! Install only the components you need. Each component is a separate package.

Q: Can I customize the styling? A: Absolutely! Components accept sx prop for MUI styling, and can be themed globally. See our Theming Guide.

Q: Why do my components look unstyled? A: Make sure your app is wrapped with ThemeProvider from @nodeblocks/frontend-theme. See Theme Issues.

Technical Questions

Q: Do Nodeblocks work with TypeScript? A: Yes, all components include TypeScript definitions.

Q: Can I use Nodeblocks with state management libraries like Redux? A: Yes, but the Domain App provides built-in state management. You can integrate with external state if needed.

Q: How do I handle form validation? A: Use the onChange prop with setError, getValues, and clearErrors functions.

Q: Can I override component behavior? A: Yes, for example using the block overriding pattern. See our Advanced Usage Guide.

Having a different issue? Contact our support team with details about your specific problem.

📋 Table of Contents​

🚨 Installation Issues​

Package Not Found Error​

Authentication Failed (401 Error)​

🔐 Authentication & Registry​

Cannot Access Private Packages​

Token Environment Variable Not Working​

🔧 Configuration Problems​

Environment Variables Not Working​

🎨 Theme Issues​

Components Not Styled Correctly (Missing ThemeProvider)​

CSS Variables Not Working​

Theme Customizations Not Applying​

🖌️ Styling & UI Issues​

Components Look Different Than Expected​

❓ Frequently Asked Questions​

General Questions​

Technical Questions​

📋 Table of Contents

🚨 Installation Issues

Package Not Found Error

Authentication Failed (401 Error)

🔐 Authentication & Registry

Cannot Access Private Packages

Token Environment Variable Not Working

🔧 Configuration Problems

Environment Variables Not Working

🎨 Theme Issues

Components Not Styled Correctly (Missing ThemeProvider)

CSS Variables Not Working

Theme Customizations Not Applying

🖌️ Styling & UI Issues

Components Look Different Than Expected

❓ Frequently Asked Questions

General Questions

Technical Questions