Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18.x or higher (tested with v24.13.1)

npm or bun

npm comes with Node.js, or install bun for faster builds

Git

For cloning the repository

Supabase Account

Free account at supabase.com

​
Quick Start

1

Clone the Repository

Clone the project repository to your local machine:
git clone <YOUR_GIT_URL>
cd <YOUR_PROJECT_NAME>
Replace <YOUR_GIT_URL> with your actual repository URL.
2

Install Dependencies

Install all required npm packages:
npm install
The project uses modern dependencies including React, TypeScript, Supabase, Tailwind CSS, shadcn-ui, and Tanstack React Query.
3

Configure Environment Variables

Set up your Supabase credentials. The project uses Supabase for:
  • Authentication (email/password)
  • Database (PostgreSQL)
  • Row Level Security (RLS)
  • Real-time subscriptions
The Supabase credentials are currently hardcoded in src/integrations/supabase/client.ts. For production or team development, you should move these to environment variables.
See the Environment Variables guide for detailed configuration.
4

Start Development Server

Launch the development server with hot module replacement:
npm run dev
The application will start on:
  • URL: http://localhost:8080
  • Host: :: (listens on all interfaces)
5

Verify Installation

Open your browser and navigate to http://localhost:8080. You should see the login page.
If this is a fresh Supabase project, you’ll need to apply database migrations. See Database Migrations.

​
Available Scripts

The project includes several npm scripts for development and deployment: 
# Start development server with hot reload
npm run dev

# Runs on http://localhost:8080
# Uses Vite for instant HMR

​
Tech Stack

The Transport Logistics platform is built with modern web technologies:

Vite

Lightning-fast build tool and dev server

React 18

UI library with hooks and concurrent features

TypeScript

Type-safe JavaScript for better DX

Supabase

Backend-as-a-Service with PostgreSQL

Tailwind CSS

Utility-first CSS framework

shadcn-ui

Beautiful, accessible UI components

Tanstack Query

Powerful data fetching and caching

React Router

Client-side routing

Zod

TypeScript-first schema validation

​
Development Workflow

​
Hot Module Replacement (HMR)

The development server uses Vite’s HMR for instant updates:
  • Component changes reflect immediately
  • State is preserved across updates
  • CSS changes apply without refresh

​
TypeScript Integration

The project uses TypeScript with strict mode:
  • Full type safety across the codebase
  • Auto-generated types from Supabase schema
  • Path aliases (@/ maps to src/)

​
Supabase Integration

Supabase provides the entire backend:
  • Authentication: Email/password with JWT tokens
  • Database: PostgreSQL with Row Level Security
  • Real-time: Live updates for shipments and vehicles
  • Storage: For documents and attachments

​
Troubleshooting

If port 8080 is occupied, you can change it in vite.config.ts:
server: {
  host: "::",
  port: 3000, // Change to any available port
}
If you see import errors, ensure path aliases are configured correctly:
  1. Check tsconfig.json includes the paths configuration
  2. Verify vite.config.ts has the @ alias setup
  3. Run npm install to refresh dependencies
If you can’t connect to Supabase:
  1. Verify your Supabase project is active
  2. Check the URL and anon key in src/integrations/supabase/client.ts
  3. Ensure your IP isn’t blocked in Supabase dashboard
  4. Check that RLS policies are properly configured
Common build issues:
  • TypeScript errors: Run npm run lint to identify issues
  • Missing dependencies: Run npm install again
  • Cache issues: Delete node_modules and dist/, then reinstall

​
Next Steps

Environment Variables

Configure Supabase and other environment settings

Database Migrations

Learn how to manage database schema changes

Database Schema

Explore the database structure and types

Deployment Guide

Learn how to deploy the application

Build docs developers (and LLMs) love

Get started for freeTalk to us