Skip to main content

​
Development Environment Setup

Cat Web uses Vite as its build tool, providing an extremely fast development experience with instant hot module replacement (HMR).

​
Prerequisites

Before starting development, ensure you have:
  • Node.js (v18 or higher recommended)
  • npm (comes with Node.js)
  • A code editor (VS Code recommended for TypeScript support)

​
Environment Variables

Cat Web requires Auth0 configuration and API connection settings. Create a .env file in the project root:
.env
VITE_AUTH0_DOMAIN=your-auth0-domain.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id
VITE_AUTH0_AUDIENCE=your-api-audience
VITE_API_BASE_URL=http://localhost:3000
All environment variables must be prefixed with VITE_ to be exposed to the client-side code. This is a Vite security feature.

​
Starting the Development Server

1

Install Dependencies

First, install all project dependencies:
npm install
2

Start Dev Server

Run the development server:
npm run dev
This command starts Vite’s development server, typically on http://localhost:5173.
3

Open in Browser

Navigate to the URL shown in your terminal (usually http://localhost:5173) to view the application.

​
Hot Module Replacement

Vite provides instant hot reload during development:
  • React Components: Changes to .tsx files trigger instant updates without losing component state
  • CSS Changes: Style updates apply immediately without page refresh
  • Fast Refresh: Powered by @vitejs/plugin-react, preserving React state across updates
If you see unexpected behavior, the dev server automatically recovers from most errors. Check the browser console and terminal for any error messages.

​
ESLint Configuration

Cat Web uses ESLint with TypeScript support to maintain code quality.

​
Running the Linter

npm run lint
This command checks all TypeScript and TSX files for:
  • TypeScript errors and type safety issues
  • React Hooks rule violations
  • React Refresh compatibility issues
  • General JavaScript/TypeScript best practices

​
Current ESLint Setup

The project uses a modern flat config (eslint.config.js) with:
  • @eslint/js - Core ESLint rules
  • typescript-eslint - TypeScript-specific linting
  • eslint-plugin-react-hooks - React Hooks rules enforcement
  • eslint-plugin-react-refresh - Fast Refresh compatibility checks

​
Enhancing ESLint (Optional)

For production applications, consider enabling type-aware lint rules:
eslint.config.js
import tseslint from 'typescript-eslint'

export default tseslint.config({
  extends: [
    ...tseslint.configs.recommendedTypeChecked,
    // Or for stricter rules:
    ...tseslint.configs.strictTypeChecked,
  ],
  languageOptions: {
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})

​
Project Structure

Understanding the file structure helps when adding new features: 
src/
├── components/       # Reusable React components
│   ├── AuthGuard.tsx
│   ├── Login.tsx
│   └── MasterLayout.tsx
├── pages/            # Page-level components
│   ├── Dashboard/
│   ├── EditItem/
│   └── ApiTests/
├── services/         # API and external service integration
│   └── api-service.ts
├── hooks/            # Custom React hooks
│   └── useApiService.ts
├── assets/           # Static assets (images, fonts)
├── App.tsx           # Root application component
├── AppRoutes.tsx     # Route configuration
├── main.tsx          # Application entry point
└── index.css         # Global styles

​
Development Workflow

​
Adding a New Feature

1

Create Component Files

Add your component in the appropriate directory:
  • Shared components → src/components/
  • Page components → src/pages/
  • Utilities → src/services/ or src/hooks/
2

Update Routes (if needed)

If creating a new page, register it in src/AppRoutes.tsx:
import { Routes, Route } from 'react-router-dom'
import { NewFeature } from '@Spa/pages/NewFeature'

export function AppRoutes() {
  return (
    <Routes>
      <Route path="/new-feature" element={<NewFeature />} />
      {/* other routes */}
    </Routes>
  )
}
3

Test Locally

The dev server will automatically reload. Test your changes in the browser.
4

Run Linter

Ensure code quality before committing:
npm run lint

​
Path Aliases

The project uses @Spa/* as a path alias for cleaner imports: 
// Instead of:
import { Dashboard } from '../../../pages/Dashboard/Dashboard'

// You can write:
import { Dashboard } from '@Spa/pages/Dashboard/Dashboard'
This is configured via vite-tsconfig-paths plugin in vite.config.ts.

​
TypeScript Configuration

Cat Web uses strict TypeScript settings for type safety:
  • Strict mode enabled: Catches more potential bugs at compile time
  • No unused locals/parameters: Enforces clean code
  • Target: ES2020: Modern JavaScript features
  • Module resolution: bundler: Optimized for Vite

​
Common Development Tasks

npm run dev

​
Troubleshooting

​
Port Already in Use

If port 5173 is occupied, Vite automatically tries the next available port. Check the terminal output for the actual URL.

​
Environment Variables Not Loading

Ensure:
  • Variables are prefixed with VITE_
  • .env file is in the project root
  • Dev server was restarted after changing .env

​
Hot Reload Not Working

Try:
  1. Save the file again
  2. Refresh the browser manually
  3. Restart the dev server
  4. Check for syntax errors in the terminal

​
ESLint Errors

Run npm run lint to see all linting issues. Fix them before committing code.

​
Next Steps

Building for Production

Learn how to create optimized production builds

Configuration

Configure Auth0 and environment variables

Build docs developers (and LLMs) love

Get started for freeTalk to us