⚡ Quickstart Guide

Build your first Nodeblocks application in under 10 minutes 🚀

This guide will get you up and running with Nodeblocks frontend components quickly. You'll create a complete application with navigation, authentication, and data management.

⏱️ Time to Complete: 5-10 minutes
💻 What You'll Build: A complete user management application
📋 Prerequisites: Node.js 18+, React knowledge

📋 Prerequisites

System Requirements

Node.js 18.0+ (Download here)
npm 8.0+ or yarn 1.22+
React 18.0+ (we'll set this up)
Basic TypeScript knowledge (recommended)

Registry Access Setup

Before installing Nodeblocks packages, configure access to the private npm registry:

Step 1: Create .npmrc File

# Create .npmrc file in your project root
touch .npmrc

Step 2: Add Registry Configuration

Add this to your .npmrc file:

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

Step 3: Set Environment Token

# Linux/macOS
export NODEBLOCKS_DEV_TOKEN=your_token_here

# Windows
set NODEBLOCKS_DEV_TOKEN=your_token_here

💡 Need a token? Contact the Nodeblocks team to obtain your development access token.

📦 Installation

# Core domain package for state management
npm install @nodeblocks/matching-app-domain

# Essential UI components
npm install @nodeblocks/frontend-navbar-block
npm install @nodeblocks/frontend-footer-block
npm install @nodeblocks/frontend-signin-block
npm install @nodeblocks/frontend-list-users-block

🏗️ Project Setup

Create New React Project (if needed)

If you're starting fresh, create a new React project:

# Using Vite (recommended)
npm create vite@latest my-nodeblocks-app -- --template react-ts
cd my-nodeblocks-app

# Downgrade to React 18 (Nodeblocks requirement)
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

npm install

⚠️ Important: Nodeblocks currently requires React 18. React 19 support is coming soon.

🎯 Build Your First App

Step 1: Create the Application Shell

Replace your src/App.tsx with this complete example:

import React from 'react';
import { MatchingAppDomain } from '@nodeblocks/matching-app-domain';
import { Navbar } from '@nodeblocks/frontend-navbar-block';
import { Footer } from '@nodeblocks/frontend-footer-block';
import { SignIn } from '@nodeblocks/frontend-signin-block';
import { ListUsers } from '@nodeblocks/frontend-list-users-block';

function App() {
  return (
    <MatchingAppDomain 
      applicationType={['admin']}
      serviceEndpoints={{
        user: 'http://localhost:3000/users',
        auth: 'http://localhost:3000/auth',
        organization: 'http://localhost:3000/orgs',
        catalog: 'http://localhost:3000/catalog',
        chat: 'http://localhost:3000/chat',
        order: 'http://localhost:3000/orders',
      }}
      logoutRedirectUrl="/login"
      loggedInRedirectUrl="/users"
      sessionType="local_storage"
    >
      {({state, middleware, updateState}) => {
        // Simple page routing based on current state
        const renderCurrentPage = () => {
          switch (state.currentPage) {
            case 'login':
              return (
                <div style={{maxWidth: '400px', margin: '2rem auto', padding: '2rem'}}>
                  <SignIn
                    onSubmit={async (formData) => {
                      try {
                        await middleware.onActionLogin(formData.email, formData.password);
                        console.log('Login successful!');
                      } catch (error) {
                        console.error('Login failed:', error);
                      }
                    }}
                    style={{
                      backgroundColor: 'white',
                      boxShadow: '0 0 10px 0 rgba(0, 0, 0, 0.1)',
                      padding: '2rem',
                      border: '1px solid lightgray',
                      display: 'flex',
                      flexDirection: 'column',
                      alignItems: 'center',
                      justifyContent: 'center',
                      gap: '1rem'
                    }}
                    onChange={(setError, getValues, clearErrors) => {
                      const values = getValues();
                      // Add validation if needed
                      if (values.email && !/\S+@\S+\.\S+/.test(values.email)) {
                        setError('email', {message: 'Invalid email format', type: 'pattern'});
                      } else {
                        clearErrors('email');
                      }
                    }}
                  >
                    <SignIn.SignInTitle>Welcome Back</SignIn.SignInTitle>
                    <SignIn.EmailField label="Email" placeholder="Enter your email" />
                    <SignIn.PasswordField label="Password" placeholder="Enter your password" />
                    <SignIn.SignInButton>Sign In</SignIn.SignInButton>
                  </SignIn>
                </div>
              );

            case 'users_list':
              return (
                <div style={{padding: '2rem'}}>
                  <h1>Welcome to your Dashboard!</h1>
                  <p>Hello, {state.loggedInUser?.name || 'User'}!</p>
                  
                  <ListUsers
                    listUsersTitle="Team Members"
                    data={[
                      {
                        id: '1',
                        name: 'John Doe',
                        email: 'john@example.com',
                        status: 'Active',
                        createdAt: '2024-01-15'
                      },
                      {
                        id: '2',
                        name: 'Jane Smith',
                        email: 'jane@example.com',
                        status: 'Active',
                        createdAt: '2024-01-20'
                      }
                    ]}
                    labels={{
                      headerRow: {
                        name: 'Name',
                        email: 'Email',
                        status: 'Status',
                        createdAt: 'Joined'
                      },
                      cellData: {
                        statusInUse: 'In Use',
                        statusNotInUse: 'Not In Use'
                      },
                      emptyStateMessage: 'No users found'
                    }}
                    onSelect={(user) => console.log('Selected user:', user)}
                  />
                </div>
              );

            default:
              return (
                <div style={{textAlign: 'center', padding: '4rem'}}>
                  <h2>Welcome to Nodeblocks!</h2>
                  <p>Your application is running successfully.</p>
                  <p>Current page: {state.currentPage}</p>
                </div>
              );
          }
        };

        return (
          <div style={{minHeight: '100vh', width: '100vw', display: 'flex', flexDirection: 'column'}}>
            {/* Navigation Header */}
            <Navbar
              leftContent={
                <div style={{display: 'flex', alignItems: 'center', gap: '0.5rem'}}>
                  <div style={{
                    width: '32px', 
                    height: '32px', 
                    backgroundColor: 'var(--ifm-color-primary)', 
                    borderRadius: '4px'
                  }}></div>
                  <span style={{fontWeight: 'bold', fontSize: '1.2rem', color: 'black'}}>MyApp</span>
                </div>
              }
              centerContent={
                <nav style={{display: 'flex', gap: '2rem'}}>
                  <a 
                    href="#" 
                    onClick={(e) => {e.preventDefault(); middleware.redirect('/users');}}
                    style={{textDecoration: 'none', color: 'black'}}
                  >
                    Users
                  </a>
                </nav>
              }
              rightContent={
                <div>
                  {state.loggedInUser ? (
                    <div style={{display: 'flex', gap: '1rem', alignItems: 'center'}}>
                      <span>Hello, {state.loggedInUser.name}!</span>
                      <button 
                        onClick={() => middleware.onActionLogout()}
                        style={{
                          padding: '0.5rem 1rem',
                          backgroundColor: 'red',
                          color: 'white',
                          border: 'none',
                          borderRadius: '4px',
                          cursor: 'pointer'
                        }}
                      >
                        Logout
                      </button>
                    </div>
                  ) : (
                    <button 
                      onClick={() => middleware.redirect('/login')}
                      style={{
                        padding: '0.5rem 1rem',
                        backgroundColor: 'white',
                        color: 'black',
                        border: '1px solid black',
                        borderRadius: '4px',
                        cursor: 'pointer'
                      }}
                    >
                      Sign In
                    </button>
                  )}
                </div>
              }
            />

            {/* Main Content */}
            <main style={{flex: 1, backgroundColor: 'white'}}>
              {renderCurrentPage()}
            </main>

            {/* Footer */}
            <Footer
              logoSrc=""
              content={
                <div style={{textAlign: 'center'}}>
                  <p>Built with Nodeblocks - The React Component Library for Business Applications</p>
                </div>
              }
              copyright="© 2024 Your Company Name. All rights reserved."
              style={{marginTop: 'auto'}}
            />
          </div>
        );
      }}
    </MatchingAppDomain>
  );
}

export default App;

Step 2: Add Environment Variables (Optional)

Create a .env file in your project root for API endpoints:

REACT_APP_USER_SERVICE_URL=https://your-user-api.com
REACT_APP_AUTH_SERVICE_URL=https://your-auth-api.com
REACT_APP_ORG_SERVICE_URL=https://your-org-api.com
REACT_APP_CATALOG_SERVICE_URL=https://your-catalog-api.com
REACT_APP_CHAT_SERVICE_URL=https://your-chat-api.com
REACT_APP_ORDER_SERVICE_URL=https://your-order-api.com

Step 3: Start Your Application

npm start
# or with Vite
npm run dev

🎉 Congratulations! Your Nodeblocks application is now running. You should see:

A navigation bar
Authentication flow (click "Sign In" to test)
User management dashboard (after login)
A footer

✅ What You've Built

Your application now includes:

🔐 Authentication System - Complete login/logout flow
👥 User Management - List and manage team members
🧭 Navigation - Navigation with routing
📱 Responsive Design - Works on all devices

🚀 Next Steps

Expand Your Application

Add more components to build a complete solution:

# E-commerce features
npm install @nodeblocks/frontend-create-product-block
npm install @nodeblocks/frontend-list-products-grid-block

# Organization management
npm install @nodeblocks/frontend-create-organization-block
npm install @nodeblocks/frontend-list-organizations-block

# Communication features
npm install @nodeblocks/frontend-chat-conversation-block
npm install @nodeblocks/frontend-chat-conversation-list-block

Learn More

🧩 Browse All Components - Discover 30+ available components
🏗️ Domain Apps Guide - Learn about application architecture
🎨 Advanced Customization - Master block overriding
❓ Troubleshooting - Solutions to common issues

💡 Tips

🎯 Start Small
Begin with basic components like Navbar and SignIn. Add complexity gradually as you learn.

🔧 Use TypeScript
All components include full TypeScript support for better development experience.

📚 Read the Docs
Each component has detailed documentation with examples and customization options.

🎉 You're ready to build amazing applications with Nodeblocks!

Need help? Check our ❓ Troubleshooting Guide or contact our support team.

📋 Prerequisites​

System Requirements​

Registry Access Setup​

Step 1: Create .npmrc File​

Step 2: Add Registry Configuration​

Step 3: Set Environment Token​

📦 Installation​

🏗️ Project Setup​

Create New React Project (if needed)​

🎯 Build Your First App​

Step 1: Create the Application Shell​

Step 2: Add Environment Variables (Optional)​

Step 3: Start Your Application​

✅ What You've Built​

🚀 Next Steps​

Expand Your Application​

Learn More​

💡 Tips​