Skip to main content

​
Overview

MotorDesk is a modern vehicle fleet management SaaS application with electronic billing capabilities, built as an offline-first Progressive Web App (PWA). This guide will help you set up your development environment.

​
Prerequisites

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

Node.js and npm

Install Node.js 18.x or higher. This will also install npm (Node Package Manager).Verify your installation:
node --version  # Should be 18.x or higher
npm --version   # Should be 8.x or higher
2

Git

Install Git for version control.
git --version
3

Code Editor

We recommend Visual Studio Code with the following extensions:
  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • TypeScript and JavaScript Language Features

​
Installation

1

Clone the repository

git clone <repository-url>
cd fleet-pwa
2

Install dependencies

npm install
This will install all required packages including:
  • React 18.2
  • TypeScript 5.3
  • Vite 7.3
  • Redux Toolkit with Redux Saga
  • TailwindCSS 4.2
  • React Router Dom 7.13
3

Start the development server

npm run dev
The application will be available at http://localhost:5173

​
Available Scripts

The project includes several npm scripts defined in package.json:6-10: 
npm run dev

​
Script Details

ScriptCommandDescription
devviteStarts the Vite development server with HMR
buildtsc -b && vite buildType-checks with TypeScript then builds for production
linteslint .Runs ESLint to check code quality
previewvite previewPreview the production build locally

​
Vite Configuration

The project uses Vite as the build tool with the following key configurations (vite.config.ts:7-44):

​
Plugins

react()
Enables Fast Refresh for React components during development.
tailwindcss()
Integrates TailwindCSS v4 for utility-first styling.
VitePWA({
  registerType: "autoUpdate",
  includeAssets: ["favicon.ico", "apple-touch-icon.png", "mask-icon.svg"],
  manifest: {
    name: "Sistema de Gestión de Flotas SUNAT 2026",
    short_name: "FleetSUNAT",
    description: "Gestión logística y facturación electrónica offline-first",
    theme_color: "#ffffff",
    background_color: "#ffffff",
    display: "standalone",
    icons: [
      { src: "pwa-192x192.png", sizes: "192x192", type: "image/png" },
      { src: "pwa-512x512.png", sizes: "512x512", type: "image/png" }
    ]
  }
})
Configures the application as a Progressive Web App with offline capabilities.

​
Path Aliases

The project uses TypeScript path aliases for cleaner imports (vite.config.ts:28-42): 
alias: {
  "@": path.resolve(__dirname, "./src"),
  "@components": path.resolve(__dirname, "./src/components"),
  "@pages": path.resolve(__dirname, "./src/pages"),
  "@routes": path.resolve(__dirname, "./src/routes"),
  "@hooks": path.resolve(__dirname, "./src/hooks"),
  "@store": path.resolve(__dirname, "./src/store"),
  "@services": path.resolve(__dirname, "./src/services"),
  "@constants": path.resolve(__dirname, "./src/constants"),
  "@data": path.resolve(__dirname, "./src/data"),
  "@styles": path.resolve(__dirname, "./src/styles"),
  "@icons": path.resolve(__dirname, "./src/ui/icons"),
  "@assets": path.resolve(__dirname, "./src/assets")
}
This allows you to import modules using clean paths: 
import { Button } from '@components/ui/Button';
import { useAuth } from '@hooks/useAuth';
import { db } from '@data/db';

​
TypeScript Configuration

The project uses strict TypeScript settings (tsconfig.app.json:2-39):
  • Target: ES2022
  • Module: ESNext with bundler resolution
  • JSX: react-jsx (automatic runtime)
  • Strict mode: Enabled
  • Path aliases: Matching Vite configuration
Key compiler options: 
{
  "strict": true,
  "noUnusedLocals": true,
  "noUnusedParameters": true,
  "noFallthroughCasesInSwitch": true
}

​
Development Workflow

1

Start the dev server

npm run dev
Hot Module Replacement (HMR) will be active.
2

Make your changes

Edit files in the src/ directory. Changes will be reflected immediately in the browser.
3

Run linting

npm run lint
Fix any ESLint warnings or errors.
4

Build for production

npm run build
This creates an optimized production build in the dist/ directory.

​
Troubleshooting

If port 5173 is already occupied, Vite will automatically try the next available port. You can also specify a custom port:
npm run dev -- --port 3000
If you see module resolution errors:
  1. Clear node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install
  1. Restart your TypeScript server in VS Code:
  • Press Cmd/Ctrl + Shift + P
  • Type “TypeScript: Restart TS Server”
The build script runs TypeScript type checking before building:
tsc -b && vite build
Fix all TypeScript errors shown in the terminal. You can run type checking separately:
npx tsc -b
PWA features (offline support, service workers) work best in production builds. To test:
npm run build
npm run preview
Then open the preview URL in your browser.
If HMR stops working:
  1. Check for syntax errors in your code
  2. Restart the dev server
  3. Clear browser cache and reload
  4. Check that you’re not exceeding file watcher limits (Linux):
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

​
Next Steps

Now that your environment is set up:

​
Environment Variables

Create a .env file in the root directory for environment-specific configuration: 
# API Configuration (when backend is ready)
VITE_API_URL=http://localhost:3000/api
VITE_DECOLECTA_TOKEN=your-api-token-here

# Feature Flags
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_DEBUG=true
Never commit .env files containing sensitive data. Use .env.example for documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us