Installation

Prerequisites

Before installing Inmobiliaria Web, ensure you have the following installed:

Node.js 18.x or higher
npm 9.x or higher (comes with Node.js)
PostgreSQL 14.x or higher
Git (for cloning the repository)

This guide assumes you’re setting up a local development environment. For production deployment, see the Deployment Guide.

Installation Steps

Clone the Repository

Clone the Inmobiliaria Web repository to your local machine:

git clone <repository-url>
cd inmobiliaria-web

Install Dependencies

Install all required npm packages:

npm install

This installs the following key dependencies:

{
  "react": "^19.2.3",
  "react-dom": "^19.2.3",
  "@tanstack/react-router": "^1.130.12",
  "better-auth": "^1.3.4",
  "vite": "^7.0.4",
  "typescript": "~5.8.3"
}

Set Up PostgreSQL Database

Create a new PostgreSQL database for the application:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE inmobiliaria_db;

# Exit psql
\q

Import Database Schema

Import the complete database schema from inmobiliaria_complete_schema.sql:

psql -U postgres -d inmobiliaria_db -f inmobiliaria_complete_schema.sql

This creates all necessary tables:Authentication Tables:

users - User accounts (Better Auth compatible)
accounts - OAuth provider accounts
sessions - User sessions
verification_tokens - Email verification tokens
user_passwords - Password hashes for email/password auth

Property Management Tables:

property_types - Casa, Departamento, PH, etc.
property_subtypes - Monoambiente, Casa en country, etc.
operation_types - Venta, Alquiler, etc.
property_statuses - Activo, Vendido, Alquilado, etc.
currencies - ARS, USD, EUR
properties - Main property listings
property_locations - Address and coordinates
property_images - Property photos
property_features - Amenities and features
property_tags - Tags for categorization
conditions - Property conditions
favorites - User favorite properties

The schema includes sample data for property types, subtypes, operation types, and more.

Configure Environment Variables

Create a .env file in the root directory with the following variables:

# API Configuration
VITE_API_URL=http://localhost:10000/api

# Google Maps API Key (required for address autocomplete and maps)
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

# Database Configuration (Backend)
DATABASE_URL=postgresql://postgres:password@localhost:5432/inmobiliaria_db

# Better Auth Configuration (Backend)
BETTER_AUTH_SECRET=your_secret_key_here_min_32_chars
BETTER_AUTH_URL=http://localhost:10000

# Email Configuration (Backend - for verification emails)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASS=your-app-password
SMTP_FROM=[email protected]

# Google OAuth (Optional - for social login)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Never commit your .env file to version control. It’s already included in .gitignore.

Getting API Keys

Google Maps API Key

Go to Google Cloud Console
Create a new project or select existing one
Enable the following APIs:
- Maps JavaScript API
- Places API
- Geocoding API
Create credentials (API Key)
Restrict the API key to your domain for production

Google OAuth Credentials

Go to Google Cloud Console
Navigate to “APIs & Services” > “Credentials”
Create OAuth 2.0 Client ID
Add authorized redirect URI: http://localhost:10000/api/auth/callback/google
Copy Client ID and Client Secret to .env

Verify Configuration

Check that your environment variables are loaded correctly:

// The API base URL is configured in src/lib/api.ts
const getApiBase = () => {
  if (import.meta.env.VITE_API_URL) {
    return import.meta.env.VITE_API_URL;
  }
  if (import.meta.env.PROD) {
    return "http://localhost:10000/api";
  }
  return "http://localhost:10000/api";
};

export const API_BASE = getApiBase();

// Google Maps API key is used in src/lib/googleMaps.ts
const apiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
if (!apiKey) {
  console.error("VITE_GOOGLE_MAPS_API_KEY is not set");
}

Running the Application

Development Mode
Production Build
Linting

Start the development server with hot reload:

npm run dev

The application will be available at:

Frontend: http://localhost:5173
Backend API: http://localhost:10000/api

Vite dev server runs on port 5173 by default. The backend API must be running separately on port 10000.

Build the application for production:

# Type check and build
npm run build

# Preview production build locally
npm run preview

The build output will be in the dist/ directory.

Run ESLint to check code quality:

npm run lint

ESLint configuration is in eslint.config.js.

Project Structure

After installation, your project structure will look like this:

inmobiliaria-web/
├── src/
│   ├── components/          # Reusable React components
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   ├── PropertyCard.tsx
│   │   ├── PropertyMap.tsx
│   │   ├── SearchBar.tsx
│   │   ├── FilterSidebar.tsx
│   │   ├── AddressAutocomplete.tsx
│   │   └── SecureRoute.tsx  # Role-based route protection
│   ├── pages/               # Page components
│   │   ├── HomePage.tsx
│   │   ├── ListingsPage.tsx
│   │   ├── PropertyDetailPage.tsx
│   │   ├── PropertyFormPage.tsx
│   │   ├── AdminPage.tsx
│   │   └── AuthPage.tsx
│   ├── routes/              # TanStack Router route definitions
│   │   ├── __root.tsx
│   │   ├── index.tsx
│   │   ├── propiedades.tsx
│   │   ├── admin.tsx
│   │   └── auth/
│   ├── lib/                 # Core libraries and utilities
│   │   ├── api.ts           # API client with all endpoints
│   │   ├── auth-client.ts   # Better Auth client configuration
│   │   └── googleMaps.ts    # Google Maps API loader
│   ├── hooks/               # Custom React hooks
│   │   ├── useSEO.ts
│   │   └── usePermissions.ts
│   ├── contexts/            # React contexts
│   │   └── AuthContext.tsx
│   ├── types/               # TypeScript type definitions
│   │   ├── index.ts
│   │   └── api.ts           # API response types
│   ├── utils/               # Utility functions
│   │   ├── search.ts
│   │   ├── seo.ts
│   │   ├── youtube.ts
│   │   └── errorHandler.ts
│   └── main.tsx             # Application entry point
├── public/                  # Static assets
├── inmobiliaria_complete_schema.sql  # Database schema
├── package.json             # Dependencies and scripts
├── vite.config.ts           # Vite configuration
├── tsconfig.json            # TypeScript configuration
├── tailwind.config.js       # Tailwind CSS configuration
└── .env                     # Environment variables (create this)

Verify Installation

To ensure everything is set up correctly:

Check Database Connection

Verify that PostgreSQL is running and the database is accessible:

psql -U postgres -d inmobiliaria_db -c "SELECT COUNT(*) FROM property_types;"

Expected output: 14 (number of property types in the schema)

Start Development Server

Run the development server:

npm run dev

You should see:

VITE v7.0.4  ready in XXX ms
➜  Local:   http://localhost:5173/

Test API Connection

Open your browser and navigate to http://localhost:5173The application should load without errors. Check the browser console for any configuration issues.

Verify Google Maps

Navigate to the property creation form at /admin/property/new (after authentication).The address autocomplete field should load without errors. If you see “VITE_GOOGLE_MAPS_API_KEY is not set” in the console, verify your .env file.

Troubleshooting

Database connection failed

Error: ECONNREFUSED or connection refusedSolutions:

Ensure PostgreSQL is running: sudo service postgresql start
Check database credentials in .env
Verify database exists: psql -U postgres -l
Check PostgreSQL is listening on port 5432

Google Maps not loading

Error: VITE_GOOGLE_MAPS_API_KEY is not setSolutions:

Verify .env file exists in project root
Check environment variable name is exactly VITE_GOOGLE_MAPS_API_KEY
Restart development server after adding environment variables
Ensure Google Maps APIs are enabled in Google Cloud Console

Type errors during build

Error: TypeScript compilation errorsSolutions:

Run npm install to ensure all type definitions are installed
Check tsconfig.json configuration
Clear TypeScript cache: rm -rf node_modules/.vite
Verify you’re using TypeScript 5.8.3 or compatible version

Port already in use

Error: Port 5173 is already in useSolutions:

Stop other Vite processes: pkill -f vite
Use a different port: npm run dev -- --port 3000
Check what’s using the port: lsof -i :5173

API requests failing

Error: Failed to fetch or CORS errorsSolutions:

Ensure backend API is running on port 10000
Check VITE_API_URL in .env matches backend URL
Verify CORS is configured on backend to allow http://localhost:5173
Check browser network tab for detailed error messages

Next Steps

Now that your environment is set up:

Quickstart Guide

Create your first property listing in minutes

Authentication Setup

Configure user authentication and roles

API Reference

Explore all available API endpoints

Component Library

Learn about available UI components

Additional Configuration

Tailwind CSS

Tailwind is pre-configured in tailwind.config.js. To customize:

// tailwind.config.js
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: "#your-color",
      },
    },
  },
  plugins: [],
}

Better Auth Configuration

Better Auth is configured in src/lib/auth-client.ts:

import { createAuthClient } from "better-auth/react";
import { adminClient } from "better-auth/client/plugins";
import { API_ORIGIN } from "./api";

export const authClient = createAuthClient({
  baseURL: API_ORIGIN, // Auto-configured from VITE_API_URL
  plugins: [adminClient()], // Enables admin features
});

Vite Configuration

Vite is configured with React and TanStack Router plugins:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { tanstackRouter } from "@tanstack/router-plugin/vite";

export default defineConfig({
  plugins: [
    tanstackRouter({
      target: "react",
      autoCodeSplitting: true,
    }),
    react(),
  ],
});

For production deployment, see the Deployment Guide for instructions on hosting with Caddy, Docker, or other platforms.

Get Started

Core Features

User Guide

Components

Prerequisites

Installation Steps

Getting API Keys

Running the Application

Project Structure

Verify Installation

Troubleshooting

Next Steps

Quickstart Guide

Authentication Setup

API Reference

Component Library

Additional Configuration

Tailwind CSS

Better Auth Configuration

Vite Configuration

Build docs developers (and LLMs) love

Get Started

Core Features

User Guide

Components

​Prerequisites

​Installation Steps

​Getting API Keys

​Running the Application

​Project Structure

​Verify Installation

​Troubleshooting

​Next Steps

Quickstart Guide

Authentication Setup

API Reference

Component Library

​Additional Configuration

​Tailwind CSS

​Better Auth Configuration

​Vite Configuration

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Getting API Keys

Running the Application

Project Structure

Verify Installation

Troubleshooting

Next Steps

Additional Configuration

Tailwind CSS

Better Auth Configuration

Vite Configuration