⚡ 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

# Theme package (recommended)
npm install @nodeblocks/frontend-theme

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

🏗️ 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

# Install react dependencies
npm install react@^19.0.0 react-dom@^19.0.0
npm install --save-dev @types/react@^19.0.0 @types/react-dom@^19.0.0

npm install

🎯 Build Your First App

Step 1: Create the Application Shell

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

import React from 'react';
import { ThemeProvider } from '@nodeblocks/frontend-theme';
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 (
    <ThemeProvider>
      <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}) => {
          // 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);
                        }
                      }}
                      onChange={(setError, getValues, clearErrors) => {
                        const values = getValues();
                        if (values.email && !/\S+@\S+\.\S+/.test(values.email)) {
                          setError('email', {message: 'Invalid email format', type: 'pattern'});
                        } else {
                          clearErrors('email');
                        }
                      }}
                      signupUrl="#signup"
                      resetPasswordUrl="#reset-password"
                      sx={{ maxWidth: 400, mx: 'auto' }}>
                      <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.GotoSignUp>
                        <span>Don't have an account? <a href="#signup">Sign up</a></span>
                      </SignIn.GotoSignUp>
                      <SignIn.ResetPassword>
                        <a href="#reset-password">Forgot password?</a>
                      </SignIn.ResetPassword>
                    </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',
                          status: 'active',
                          createdAt: '2025-01-15T10:30:00Z'
                        },
                        {
                          id: '2',
                          name: 'Jane Smith',
                          status: 'active',
                          createdAt: '2025-01-20T09:15:00Z'
                        }
                      ]}
                      labels={{
                        headerRow: {
                          name: 'Name',
                          status: 'Status',
                          createdAt: 'Joined'
                        },
                        cellData: {
                          statusInUse: 'Active',
                          statusNotInUse: 'Inactive'
                        },
                        emptyStateMessage: 'No users found'
                      }}
                      rowHref={(row) => `#users/${row.id}`}
                      onNavigate={(path) => console.log('Navigate to:', path)}>
                      <ListUsers.Header>
                        <ListUsers.Title />
                      </ListUsers.Header>
                      <ListUsers.Content />
                    </ListUsers>
                  </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: '#006ead', 
                      borderRadius: '4px'
                    }} />
                    <span style={{fontWeight: 'bold', fontSize: '1.2rem'}}>MyApp</span>
                  </div>
                }
                centerContent={
                  <div style={{display: 'flex', gap: 16}}>
                    <Navbar.Link href="#" onClick={(e) => {e.preventDefault(); middleware.redirect('/users');}}>
                      Users
                    </Navbar.Link>
                  </div>
                }
                rightContent={
                  state.loggedInUser ? (
                    <div style={{display: 'flex', gap: '1rem', alignItems: 'center'}}>
                      <span>Hello, {state.loggedInUser.name}!</span>
                      <Navbar.ButtonLink onClick={() => middleware.onActionLogout()}>
                        Logout
                      </Navbar.ButtonLink>
                    </div>
                  ) : (
                    <Navbar.ButtonLink onClick={() => middleware.redirect('/login')}>
                      Sign In
                    </Navbar.ButtonLink>
                  )
                }
                sx={{ backgroundColor: 'white', boxShadow: 1 }}>
                <Navbar.Left />
                <Navbar.Center />
                <Navbar.Right />
              </Navbar>

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

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

export default App;

Step 2: Add Environment Variables (Optional)

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

# For Vite projects (recommended)
VITE_USER_SERVICE_URL=https://your-user-api.com
VITE_AUTH_SERVICE_URL=https://your-auth-api.com
VITE_ORG_SERVICE_URL=https://your-org-api.com
VITE_CATALOG_SERVICE_URL=https://your-catalog-api.com
VITE_CHAT_SERVICE_URL=https://your-chat-api.com
VITE_ORDER_SERVICE_URL=https://your-order-api.com

Note: Access these in code via import.meta.env.VITE_USER_SERVICE_URL

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@0.5.0
npm install @nodeblocks/frontend-list-products-grid-block@0.2.0

# 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@0.2.0
npm install @nodeblocks/frontend-chat-conversation-list-block

Learn More

🧩 Browse All Components - Discover 30+ available components
🎨 Theming Guide - Customize colors, typography, and styling
🏗️ Domain Apps Guide - Learn about application architecture
🔧 Advanced Customization - Master block overriding
🚀 Full Setup Guide - Comprehensive project setup
❓ 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​