Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Node.js

Node.js version 18.x or higher is required. We recommend using the latest LTS version.Check your Node.js version:
node --version
2

Package Manager

Choose one of the following package managers:
  • npm (comes with Node.js)
  • yarn (install via npm install -g yarn)
  • pnpm (install via npm install -g pnpm)

​
Installation Steps

1

Clone the Repository

Clone the Cat Web repository to your local machine:
git clone <repository-url>
cd cat-web
2

Install Dependencies

Install the required dependencies using your preferred package manager:
npm install
This will install all dependencies defined in package.json, including:
  • React 19 and React DOM
  • Material-UI components
  • Auth0 React SDK
  • React Router
  • TypeScript and build tools
3

Configure Environment Variables

Create a .env file in the root directory with the required configuration.See the Configuration guide for detailed setup instructions.
4

Start the Development Server

Run the development server with hot module replacement:
npm run dev
The application will be available at http://localhost:5173 (default Vite port).
Once the development server is running, you should see the login page when you navigate to http://localhost:5173.

​
Project Structure

After installation, your project structure will look like this: 
cat-web/
├── node_modules/        # Installed dependencies
├── public/              # Static assets
├── src/                 # Source code
│   ├── assets/         # Images, fonts, etc.
│   ├── components/     # Reusable components
│   │   ├── AuthGuard.tsx
│   │   ├── Login.tsx
│   │   ├── MasterLayout.tsx
│   │   └── ApiTesting.tsx
│   ├── hooks/          # Custom React hooks
│   │   └── useApiService.ts
│   ├── pages/          # Page components
│   │   ├── Dashboard/
│   │   ├── EditItem/
│   │   └── ApiTests/
│   ├── services/       # API and business logic
│   │   └── api-service.ts
│   ├── App.tsx         # Root component
│   ├── AppRoutes.tsx   # Route definitions
│   ├── main.tsx        # Application entry point
│   └── index.css       # Global styles
├── .env                # Environment variables (create this)
├── index.html          # HTML template
├── package.json        # Project metadata and scripts
├── tsconfig.json       # TypeScript configuration
├── vite.config.ts      # Vite configuration
└── eslint.config.js    # ESLint configuration

​
Available Scripts

The following npm scripts are available:

​
npm run dev

Starts the development server with hot module replacement. Changes to your code will be instantly reflected in the browser. 
npm run dev

​
npm run build

Builds the application for production. This compiles TypeScript and creates optimized bundles: 
npm run build
The build output will be in the dist/ directory.

​
npm run lint

Runs ESLint to check your code for potential issues: 
npm run lint

​
npm run preview

Serves the production build locally for testing: 
npm run preview
Always run npm run build before npm run preview to ensure you’re previewing the latest build.

​
Troubleshooting

If port 5173 is already in use, Vite will automatically try the next available port. You can also specify a custom port in vite.config.ts:
export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  server: {
    port: 3000
  }
})
If you encounter module not found errors:
  1. Delete node_modules and lock files: 
    rm -rf node_modules package-lock.json
  2. Reinstall dependencies: 
    npm install
Ensure you’re using TypeScript 5.7 or compatible version:
npm list typescript
If needed, update TypeScript:
npm install typescript@~5.7.2

​
Next Steps

Now that you have Cat Web installed, proceed to configure your environment variables and Auth0 settings.

Configuration

Set up environment variables and Auth0 authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us