Skip to main content

​
Installation Guide

This guide walks you through installing and configuring both the client and server applications.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
RequirementMinimum VersionCheck Installation
Node.js18.xnode --version
npm9.xnpm --version
Git2.xgit --version
You’ll also need a MongoDB Atlas account (free tier available) or a local MongoDB instance.

​
Installation Steps

1

Clone the Repository

Clone the project repository to your local machine:
git clone <repository-url>
cd t1-component-libray-irvincnt-test
2

Install Server Dependencies

Navigate to the server directory and install dependencies:
cd server
npm install
The server uses TypeScript and includes packages like Express, Mongoose, JWT, and bcryptjs for authentication.
3

Configure Server Environment

Create a .env file in the server directory:
cp env.example .env
Edit the .env file with your configuration:
.env
# Server Configuration
PORT=3001
NODE_ENV=development

# MongoDB Atlas Connection
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/component-library?retryWrites=true&w=majority

# JWT Configuration
JWT_SECRET=tu_clave_secreta_muy_segura_aqui
JWT_EXPIRES_IN=7d
Important: Replace <username> and <password> with your MongoDB Atlas credentials. Never commit your .env file to version control.

​
Environment Variables Explained

VariableDescriptionExample
PORTPort for the Express server3001
NODE_ENVEnvironment modedevelopment, production
MONGODB_URIMongoDB connection stringSee example above
JWT_SECRETSecret key for signing JWT tokensUse a strong random string
JWT_EXPIRES_INToken expiration time7d, 24h, 30m
4

Set Up MongoDB Atlas

If you don’t have a MongoDB Atlas cluster yet:
  1. Go to MongoDB Atlas
  2. Create a free account and cluster
  3. Click “Connect” on your cluster
  4. Choose “Connect your application”
  5. Copy the connection string
  6. Replace <password> with your database user password
  7. Paste the complete URI into your .env file
Make sure to whitelist your IP address in MongoDB Atlas Network Access settings, or allow access from anywhere (0.0.0.0/0) for development.
5

Start the Server

Run the development server with hot reload:
npm run dev
You should see output like:
🚀 Servidor corriendo en http://localhost:3001
📚 Health check: http://localhost:3001/api/health
6

Verify Server Installation

Test that the server is running correctly:
curl http://localhost:3001/api/health
Expected response:
{
  "success": true,
  "status": "healthy",
  "timestamp": "2026-03-03T12:00:00.000Z",
  "uptime": "5s",
  "services": {
    "database": {
      "status": "connected",
      "connected": true
    }
  }
}
If the database status shows “disconnected”, verify your MongoDB URI and network settings.
7

Install Client Dependencies

Open a new terminal window and navigate to the client directory:
cd client
npm install
The client uses Next.js 16, React 19, TanStack Query, Zustand, and Tailwind CSS 4.
8

Configure Client Environment (Optional)

The client works out of the box with default settings. If you need to customize the API URL, create a .env.local file:
.env.local
# API Server URL
NEXT_PUBLIC_API_URL=http://localhost:3001/api
Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.
9

Start the Client

Run the Next.js development server:
npm run dev
You should see:
▲ Next.js 16.0.4
- Local:        http://localhost:3000
10

Verify Installation

Open your browser and visit:You should see the component showcase with interactive examples.

​
Verification Checklist

Make sure everything is working correctly:
  • Server responds at http://localhost:3001/api/health with status “healthy”
  • Client loads at http://localhost:3000
  • Status page shows server as “connected”
  • You can register a new user at http://localhost:3000/register
  • You can login at http://localhost:3000/login
  • Component interactions are tracked (check dashboard)

​
Available Commands

​
Server Commands

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run production server
npm start

# Run linter
npm run lint

​
Client Commands

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Run linter
npm run lint

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

​
Troubleshooting

Another process is using port 3001. Either:
  • Stop the other process
  • Change the PORT in your .env file to a different port
Common causes:
  • Invalid MongoDB URI in .env
  • Incorrect username/password
  • IP address not whitelisted in MongoDB Atlas
  • Network/firewall issues
Verify your connection string and Atlas configuration.
Ensure:
  • Server is running on port 3001
  • NEXT_PUBLIC_API_URL points to the correct server URL
  • No CORS issues (server has CORS enabled by default)
Delete node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Now that you have everything installed:

Quick Start Guide

Learn how to use the component showcase

API Reference

Explore the REST API endpoints

Components

Browse available components

Testing Guide

Learn about the testing workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us