Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 20.x or higher

npm

Version 10.x or higher

Git

Latest version

​
Installation

1

Clone the repository

git clone <repository-url>
cd microcbm
2

Install dependencies

npm install
This will install all dependencies defined in package.json.
3

Configure environment variables

Create a .env.local file in the root directory with the required variables:
NEXT_PUBLIC_API_URL=https://your-api-url.com
SESSION_SECRET=your-session-secret-key
The NEXT_PUBLIC_API_URL should point to your backend API. For development, this might be a local server or a staging environment.
4

Start the development server

npm run dev
The application will be available at http://localhost:3000.

​
Environment Variables

​
Required Variables

VariableDescriptionExample
NEXT_PUBLIC_API_URLBackend API base URLhttps://api.example.com
SESSION_SECRETSecret key for session encryptionyour-secret-key-here
Never commit .env.local to version control. The .env.local file should be added to .gitignore.

​
Backend API Considerations

MicroCBM requires a running backend API to function properly. Without a connected backend:
  • Authentication pages will render but login will fail
  • Protected pages will show loading states or errors
  • Data-dependent features will not display information
The backend API hosted on Render’s free tier may require 30-60 seconds for cold starts on the first request.

​
Package Dependencies

​
Core Dependencies

Key packages used in MicroCBM: 
// package.json:12
{
  "dependencies": {
    "next": "15.5.9",
    "react": "19.1.0",
    "react-dom": "19.1.0",
    "@tanstack/react-query": "^5.90.2",
    "zustand": "^5.0.9",
    "react-hook-form": "^7.64.0",
    "zod": "^4.1.11",
    "@hookform/resolvers": "^5.2.2"
  }
}
Next.js 15.5.9 - React framework with App Router
  • Server Components by default
  • File-based routing
  • Built-in API routes
  • Server Actions support

​
UI Component Libraries

{
  "dependencies": {
    "@radix-ui/react-dialog": "^1.1.15",
    "@radix-ui/react-dropdown-menu": "^2.1.16",
    "@radix-ui/react-select": "^2.1.5",
    "@radix-ui/react-tabs": "^1.1.13",
    "recharts": "^3.2.1",
    "framer-motion": "^12.23.24",
    "@xyflow/react": "^12.10.1"
  }
}
Unstyled, accessible UI components:
  • Dialog/Modal
  • Dropdown Menu
  • Select
  • Tabs
  • Checkbox
  • Radio Group
  • Switch
  • Popover
  • Scroll Area
All Radix components are styled with Tailwind CSS and customized for MicroCBM’s design system.
Composable charting library built on React components:
  • Area charts for trend analysis
  • Bar charts for comparisons
  • Pie charts for distributions
  • Line charts for time series data
Used extensively in dashboards and analytics pages.
Node-based UI library for building interactive diagrams:
  • Used for Logic Tree visualization in RCA module
  • Drag-and-drop node creation
  • Custom node types
  • Auto-layout capabilities
Animation library for React:
  • Page transitions
  • Modal animations
  • Loading states
  • Interactive feedback

​
Development Scripts

// package.json:5
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "update-icons": "node scripts/update-icons.js"
  }
}

​
Available Commands

npm run dev
Starts the Next.js development server with:
  • Hot Module Replacement (HMR)
  • Fast Refresh for instant updates
  • Error overlay for debugging
  • Runs on http://localhost:3000

​
IDE Setup

Recommended extensions: 
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "styled-components.vscode-styled-components"
  ]
}

​
TypeScript Configuration

MicroCBM uses strict TypeScript settings: 
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
The @/ path alias allows importing from the src/ directory: 
import { Button } from "@/components";
import { useContentGuard } from "@/hooks";
import { Asset } from "@/types";

​
Middleware & Security

MicroCBM includes authentication middleware that protects all routes except /auth/*: 
// src/middleware.ts:1
import { NextRequest, NextResponse } from "next/server";
import { ROUTES } from "./utils";
import { isTokenExpired } from "./libs/jwt";

const publicPaths = new Set([
  ROUTES.AUTH.LOGIN,
  ROUTES.AUTH.REGISTER,
  ROUTES.AUTH.RESET_PASSWORD,
]);

function isPublicPath(pathname: string): boolean {
  return publicPaths.has(pathname) || pathname.startsWith("/auth/");
}

export default async function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;
  const token = req.cookies.get("token")?.value;
  const isPublic = isPublicPath(pathname);

  if (token && isTokenExpired(token)) {
    const response = isPublic
      ? NextResponse.next()
      : NextResponse.redirect(new URL(ROUTES.AUTH.LOGIN, req.nextUrl));
    response.cookies.delete("token");
    response.cookies.delete("userData");
    return response;
  }

  if (!isPublic && !token) {
    return NextResponse.redirect(new URL(ROUTES.AUTH.LOGIN, req.nextUrl));
  }

  if (isPublic && token) {
    return NextResponse.redirect(new URL(ROUTES.HOME, req.nextUrl));
  }

  return NextResponse.next();
}

export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|assets|favicon.ico|robots.txt|sitemap.xml|manifest.webmanifest).*)",
  ],
};
The middleware excludes static assets, API routes, and public metadata files from authentication checks.

​
Troubleshooting

If port 3000 is already occupied:
# Kill the process using port 3000
npx kill-port 3000

# Or run on a different port
PORT=3001 npm run dev
If you see API connection errors:
  1. Verify NEXT_PUBLIC_API_URL is correct in .env.local
  2. Check if the backend API is running
  3. Wait 30-60 seconds for cold start if using Render free tier
  4. Check browser console for detailed error messages
If you encounter module resolution errors:
# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Restart dev server
npm run dev
For TypeScript compilation issues:
# Check TypeScript configuration
npx tsc --noEmit

# Restart TypeScript server in VS Code
# Command Palette > TypeScript: Restart TS Server

​
Next Steps

Project Structure

Understand the codebase organization

Routing

Learn about Next.js App Router patterns

Build docs developers (and LLMs) love

Get started for freeTalk to us