Skip to main content

​
Quick Start Guide

This guide will help you get the full stack running locally and create your first component interaction.

​
Goal

By the end of this guide, you’ll have:
  • Both client and server running locally
  • A working component showcase
  • Your first tracked interaction
  • Understanding of basic component usage

​
Prerequisites

Make sure you have completed the installation guide before proceeding.

​
Running the Stack

1

Start the Server

Open a terminal and start the Express server:
cd server
npm run dev
Wait for the confirmation message:
🚀 Servidor corriendo en http://localhost:3001
📚 Health check: http://localhost:3001/api/health
Keep this terminal window open. The server will auto-reload when you make changes.
2

Start the Client

Open a new terminal window and start the Next.js client:
cd client
npm run dev
Wait for Next.js to compile:
▲ Next.js 16.0.4
- Local:        http://localhost:3000
- Ready in 2.1s
3

Verify the Health Check

Open your browser or use curl to check the server status:
curl http://localhost:3001/api/health
You should receive:
{
  "success": true,
  "status": "healthy",
  "services": {
    "database": {
      "status": "connected",
      "connected": true
    }
  }
}
If the database status is “disconnected”, verify your MongoDB Atlas configuration in the .env file.
4

Open the Application

Navigate to http://localhost:3000 in your browser.You should see the component showcase homepage with:
  • Navigation bar with theme toggle
  • Interactive component sections
  • Button variants and examples
  • Input fields and forms
  • Cards and modals

​
Your First Component

Let’s explore how components work in the T1 Component Library by examining the Button component.

​
Understanding the Button Component

The Button component from client/app/components/Button.tsx supports multiple variants, sizes, and states:
Button.tsx
'use client';

import { ButtonHTMLAttributes, forwardRef } from 'react';

export type ButtonVariant = 'primary' | 'secondary' | 'accent' | 'destructive' | 'ghost' | 'outline';
export type ButtonSize = 'sm' | 'md' | 'lg';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  isLoading?: boolean;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      variant = 'primary',
      size = 'md',
      isLoading = false,
      leftIcon,
      rightIcon,
      disabled,
      className = '',
      children,
      ...props
    },
    ref
  ) => {
    const isDisabled = disabled || isLoading;

    return (
      <button
        ref={ref}
        disabled={isDisabled}
        className={`
          inline-flex items-center justify-center font-medium
          rounded-[var(--radius-md)]
          transition-all duration-[var(--transition-fast)]
          ${variantStyles[variant]}
          ${sizeStyles[size]}
          ${isDisabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}
          ${className}
        `}
        {...props}
      >
        {isLoading && (
          <svg className="animate-spin h-4 w-4" /* ... */>
            {/* Loading spinner SVG */}
          </svg>
        )}
        {!isLoading && leftIcon && <span>{leftIcon}</span>}
        {children}
        {!isLoading && rightIcon && <span>{rightIcon}</span>}
      </button>
    );
  }
);

​
Using the Button Component

Here are practical examples of using the Button component: 
import { Button } from '@/app/components/Button';

export default function Example() {
  return (
    <Button onClick={() => console.log('Clicked!')}>
      Click Me
    </Button>
  );
}

​
Interaction Tracking

All component interactions are automatically tracked using the InteractionContext. Here’s how it works:

​
How Tracking Works

From the homepage (client/app/page.tsx):
page.tsx
'use client';

import { useInteractions } from './context/InteractionContext';
import { ButtonSection } from './components/home';

export default function HomePage() {
  const { trackInteraction } = useInteractions();

  return (
    <div className="min-h-[calc(100vh-4rem)]">
      <ButtonSection onTrackInteraction={trackInteraction} />
    </div>
  );
}

​
Testing Interaction Tracking

1

Register a User (Optional)

Navigate to http://localhost:3000/registerCreate an account with:
Registered users have their interactions tracked with their user ID. Anonymous users are tracked without identification.
2

Interact with Components

Go back to the homepage and click on various buttons, open modals, type in inputs, and hover over cards.Each interaction sends a request to the API:
POST /api/components/track
{
  "nombre": "Button",
  "accion": "click",
  "tipo_usuario": "registered",
  "usuario": "507f1f77bcf86cd799439011"
}
3

View Statistics

Navigate to http://localhost:3000/dashboardYou’ll see:
  • Total interaction count
  • Interactions per component
  • Interactions per action type
  • Anonymous vs registered user breakdown
4

Export Data (Authenticated Only)

If you’re logged in, visit http://localhost:3000/exportsYou can:
  • View paginated tracking data
  • See timestamps and user information
  • Export data for analysis

​
API Endpoints

Here are the key API endpoints you’ll use:

​
Authentication

# Register a new user
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"nombre":"John Doe","email":"[email protected]","password":"password123"}'

# Login
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password123"}'

​
Tracking

# Track an interaction (public)
curl -X POST http://localhost:3001/api/components/track \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Button","accion":"click","tipo_usuario":"anonymous"}'

# Get statistics (public)
curl http://localhost:3001/api/components/stats

​
Data Export (requires authentication)

# Get paginated data
curl "http://localhost:3001/api/components/export/view?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Export all data
curl http://localhost:3001/api/components/export \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Development Workflow

When developing, you’ll typically run both servers simultaneously: Terminal 1 - Server: 
cd server
npm run dev
Terminal 2 - Client: 
cd client
npm run dev
Both servers have hot reload enabled. Changes to your code will automatically refresh the application.

​
Testing

Run the test suite to ensure everything works correctly: 
cd client
npm run test:coverage
The project maintains 80%+ test coverage across:
  • Components (Button, Card, Input, Modal, Navbar)
  • Contexts (Theme, Interaction)
  • Utilities (API client)
  • Integration tests

​
Common Tasks

  1. Create the component in client/app/components/
  2. Add tests in client/app/__tests__/components/
  3. Create a showcase section in client/app/components/home/
  4. Add documentation to the docs page
Edit client/app/globals.css to modify CSS variables:
:root {
  --primary: 220 90% 56%;
  --primary-foreground: 0 0% 100%;
  /* ... more variables */
}
  1. Create route in server/src/routes/
  2. Add controller in server/src/controllers/
  3. Implement service logic in server/src/services/
  4. Add validation middleware if needed
  5. Update API documentation
Server logs appear in the terminal where you ran npm run dev.The server uses Morgan for HTTP logging and includes custom loggers for debugging.

​
Next Steps

Now that you have the basics down:

Explore Components

Learn about all available components

API Reference

Dive into the complete API documentation

Theming Guide

Customize the look and feel

Testing Guide

Learn about testing
Need help? Check the API Reference for detailed endpoint documentation or explore the Components guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us