Quickstart Guide

This guide will walk you through setting up TamborraData for local development. You’ll have a fully functional instance running with mock data in under 10 minutes.

Prerequisites

Before starting, ensure you have the following installed:

Node.js 18+

Required for running Next.js

pnpm

Fast, disk space efficient package manager

Supabase Account

Free PostgreSQL database hosting

Make sure you have Node.js 18 or higher. The project uses Next.js 16 which requires modern Node.js features.

Installing pnpm

If you don’t have pnpm installed:

npm install -g pnpm

Verify the installation:

node --version  # Should be 18.0.0 or higher
pnpm --version  # Should be 8.0.0 or higher

Step 1: Clone the Repository

Clone the TamborraData repository to your local machine:

git clone https://github.com/ramistodev/tamborradata.git
cd tamborradata

Step 2: Install Dependencies

Install all project dependencies using pnpm:

pnpm install

This will install:

Next.js 16 (React 19 framework)
Supabase Client (Database access)
React Query 5 (Data fetching and caching)
TailwindCSS 4 (Styling)
Nivo Charts (Data visualizations)
Framer Motion 12 (Animations)

pnpm creates a node_modules directory and uses symlinks for efficient disk usage. First installation may take 1-2 minutes.

Step 3: Set Up Supabase Database

Create a Supabase Project

Go to supabase.com and create a free account.

Create a new project

Click New Project and fill in:

Name: tamborradata-dev (or any name)
Database Password: Choose a strong password
Region: Select closest to your location
Pricing Plan: Free tier is sufficient

Wait 2-3 minutes for project provisioning.

Get your credentials

Navigate to Settings > API and copy:

Project URL (e.g., https://xxxxx.supabase.co)
anon/public key (starts with eyJ...)

Create the Database Schema

Open SQL Editor

In your Supabase project, go to SQL Editor from the left sidebar.

Execute schema file

Open the file mocked_data/tamborradata_schema.sql from your cloned repository, copy its contents, and paste into the SQL Editor.Click Run to execute. This creates:

statistics table
available_years table
sys_status table
participants table
available_companies_view view
Row Level Security (RLS) policies

Verify tables created

Go to Table Editor in the sidebar. You should see 4 tables listed.

The schema includes Row Level Security (RLS) configured for read-only access. This means anonymous users can query data but cannot modify it.

Import Mock Data

Now let’s populate the database with synthetic data for development:

Import participants data

Go to Table Editor > participants
Click Insert > Import data from CSV
Select mocked_data/participants.csv from your project
Click Import (100 rows will be imported)

Import statistics data

Go to Table Editor > statistics
Click Insert > Import data from CSV
Select mocked_data/statistics.csv
Click Import

Verify data imported

participants table should have ~100 rows
statistics table should have multiple rows
available_years should already have 2024, 2025, and ‘global’
sys_status should have 1 row with is_updating = false

All names in the mock data are completely fictional and randomly generated. Any resemblance to real people is purely coincidental.

Step 4: Configure Environment Variables

Create a .env.local file in the project root:

cp .env.example .env.local

Edit .env.local and add your Supabase credentials:

.env.local

SUPABASE_URL="https://xxxxx.supabase.co"
SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Replace the values with the credentials you copied from Supabase Settings > API.

Environment Variables Explained

Variable	Purpose	Required
`SUPABASE_URL`	Your Supabase project URL	✅ Yes
`SUPABASE_ANON_KEY`	Anonymous/public API key	✅ Yes

The .env.local file is ignored by Git (via .gitignore), so your credentials won’t be committed.

Step 5: Start the Development Server

Start the Next.js development server:

pnpm dev

You should see:

  ▲ Next.js 16.1.0
  - Local:        http://localhost:3000
  - Network:      http://192.168.1.x:3000

 ✓ Ready in 2.5s

Open your browser and navigate to http://localhost:3000

Success! You should see the TamborraData homepage with statistics and visualizations.

Available Scripts

Here are the main npm scripts available in the project:

pnpm dev
# Starts Next.js development server on http://localhost:3000
# Hot reload enabled
# React Query Devtools available

Verify Your Setup

To confirm everything is working correctly:

Homepage loads

Navigate to http://localhost:3000 and verify the homepage displays.

Statistics display

You should see statistics for years 2024 and 2025 with charts and visualizations.

Search functionality

Try searching for a participant:

Click on “Buscar Participante” (Search Participant)
Search for “Pepito Garcia Lopez” from “Compañia de prueba”
Results should appear

API endpoints work

Test API endpoints directly:

http://localhost:3000/api/years - Should return available years
http://localhost:3000/api/statistics?year=2024 - Should return 2024 statistics

Troubleshooting

Port 3000 Already in Use

Error: Port 3000 is already in use Solution: Either stop the process using port 3000 or use a different port:

pnpm dev -- -p 3001

Database Connection Error

Error: Could not connect to database or Invalid API key Solutions:

Verify your SUPABASE_URL is correct in .env.local
Check your SUPABASE_ANON_KEY is the anon/public key, not the service key
Ensure your Supabase project is not paused (free tier pauses after inactivity)
Restart the dev server after changing .env.local

No Data Displayed

Error: App loads but shows no statistics or participants Solutions:

Verify data was imported correctly:
- Check Supabase Table Editor for statistics and participants tables
- Ensure available_years has entries for 2024, 2025, and ‘global’
Check browser console for API errors
Verify RLS policies are enabled (should be created by schema)

TypeScript Errors

Error: Type errors during pnpm build Solutions:

Delete .next folder and rebuild:
```
rm -rf .next
pnpm build
```

Ensure all dependencies are installed:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Module Not Found Errors

Error: Cannot find module '@/...' Solution: The project uses path aliases. Ensure your tsconfig.json has:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

If you continue to have issues, try deleting node_modules, .next, and pnpm-lock.yaml, then reinstall:

rm -rf node_modules .next pnpm-lock.yaml
pnpm install
pnpm dev

Next Steps

Mock Data

Learn about the structure of synthetic data

Configuration

Understand environment variables and config files

Contributing

Read contribution guidelines

Architecture

Explore the technical architecture

Development Tips

React Query Devtools: When running pnpm dev, React Query Devtools are automatically available in the bottom-left corner. Click the icon to inspect queries, cache, and refetch data.

Hot Reload: Next.js has fast refresh enabled. Changes to components and pages automatically reload without losing state.

Server vs Client Components: This project uses Next.js 16 App Router with Server Components by default. If you need client-side interactivity, add 'use client' at the top of your component file.

The development server has verbose logging enabled. Check your terminal for detailed request/response information.

Get Started

Core Features

Architecture

Development

Advanced Topics

Quickstart

Quickstart Guide

Prerequisites

Node.js 18+

pnpm

Supabase Account

Installing pnpm

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Set Up Supabase Database

Create a Supabase Project

Create the Database Schema

Import Mock Data

Step 4: Configure Environment Variables

Environment Variables Explained

Step 5: Start the Development Server

Available Scripts

Verify Your Setup

Troubleshooting

Port 3000 Already in Use

Database Connection Error

No Data Displayed

TypeScript Errors

Module Not Found Errors

Next Steps

Mock Data

Configuration

Contributing

Architecture

Development Tips

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Development

Advanced Topics

​Quickstart Guide

​Prerequisites

Node.js 18+

pnpm

Supabase Account

​Installing pnpm

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Set Up Supabase Database

​Create a Supabase Project

​Create the Database Schema

​Import Mock Data

​Step 4: Configure Environment Variables

​Environment Variables Explained

​Step 5: Start the Development Server

​Available Scripts

​Verify Your Setup

​Troubleshooting

​Port 3000 Already in Use

​Database Connection Error

​No Data Displayed

​TypeScript Errors

​Module Not Found Errors

​Next Steps

Mock Data

Configuration

Contributing

Architecture

​Development Tips

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

Installing pnpm

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Set Up Supabase Database

Create a Supabase Project

Create the Database Schema

Import Mock Data

Step 4: Configure Environment Variables

Environment Variables Explained

Step 5: Start the Development Server

Available Scripts

Verify Your Setup

Troubleshooting

Port 3000 Already in Use

Database Connection Error

No Data Displayed

TypeScript Errors

Module Not Found Errors

Next Steps

Development Tips