Skip to main content

❓ 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​

Package Not Found Error​

Problem:

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

Solutions:

  1. Check your .npmrc configuration:
# Verify .npmrc exists and has correct content
cat .npmrc
  1. Ensure token is set:
echo $NODEBLOCKS_DEV_TOKEN
  1. 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:

  1. Check token validity:

    • Contact Nodeblocks team for a new token
    • Ensure token hasn't expired

  2. Verify environment variable:

# Linux/macOS
export NODEBLOCKS_DEV_TOKEN=your_actual_token_here

# Windows
set NODEBLOCKS_DEV_TOKEN=your_actual_token_here
  1. Clear npm cache:
npm cache clean --force

Peer Dependency Warnings​

Problem:

npm WARN peer dep missing: react@^18.0.0, required by @nodeblocks/frontend-navbar-block

Solution: Install the correct React version:

npm install react@^18.0.0 react-dom@^18.0.0
npm install --save-dev @types/react@^18.0.0 @types/react-dom@^18.0.0

βš›οΈ React Compatibility​

React 19 Compatibility Issues​

Problem: Components not working with React 19.

Solution: Nodeblocks currently requires React 18. Downgrade your React version:

# Downgrade to React 18
npm install react@^18.0.0 react-dom@^18.0.0

# Update TypeScript types
npm install --save-dev @types/react@^18.0.0 @types/react-dom@^18.0.0

When will React 19 be supported? We're actively working on React 19 compatibility. Follow our changelog for updates.

πŸ” Authentication & Registry​

Cannot Access Private Packages​

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

Checklist:

  1. βœ… .npmrc file exists in project root
  2. βœ… Registry configuration is correct
  3. βœ… NODEBLOCKS_DEV_TOKEN environment variable is set
  4. βœ… Token is valid and not expired
  5. βœ… 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:

  1. 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"
  1. For permanent setup:
# Linux/macOS - Add to ~/.bashrc or ~/.zshrc
echo 'export NODEBLOCKS_DEV_TOKEN=your_token' >> ~/.bashrc

# Windows - Use System Environment Variables
  1. 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;

🎨 Styling & UI Issues​

Components Look Different Than Expected​

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

Solutions:

  1. Check for global CSS conflicts:
/* Your global styles might be interfering */
* {
  box-sizing: border-box; /* This might affect component layouts */
}
  1. Use component-specific styling:
<SignIn
  style={{
    maxWidth: '400px',
    margin: '0 auto',
    padding: '2rem'
  }}
>
  {/* Component content */}
</SignIn>
  1. 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: Can I use Nodeblocks with React 19? A: Not currently. Nodeblocks requires React 18. React 19 support is in development.

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 style props and can be styled with CSS-in-JS or CSS modules.

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.