Development Setup and Configuration

Prerequisites

• Node.js 18+ (or Bun)
• npm, yarn, pnpm, or bun package manager
• Git

Installation

# Clone the repository
git clone <repository-url>
cd ibw-admin
 
# Install dependencies
npm install
# or
bun install

Environment Configuration

Create a .env file in the root directory:

VITE_BASE_URL=http://localhost:8080

Environment Variables

• VITE_BASE_URL: Base URL for the backend API
  • Development: http://localhost:8080
  • Production: https://ibw-app-service.lemonpebble-d3abe181.southeastasia.azurecontainerapps.io

Development Server

# Start development server
npm run dev
# or
bun run dev

The application will be available at http://localhost:5173 (default Vite port).

Build

# Build for production
npm run build
# or
bun run build

The production build will be output to the dist/ directory.

Preview Production Build

# Preview production build locally
npm run preview
# or
bun run preview

Linting

# Run ESLint
npm run lint
# or
bun run lint

Project Configuration

Vite Configuration (vite.config.ts)

import path from "path";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
 
export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

Key Features:

• React plugin for JSX/TSX support
• Tailwind CSS plugin for styling
• Path alias @ pointing to src/ directory

TypeScript Configuration

tsconfig.json

Main TypeScript configuration.

tsconfig.app.json

Application-specific TypeScript configuration.

tsconfig.node.json

Node.js-specific TypeScript configuration (for Vite config).

ESLint Configuration (eslint.config.js)

ESLint configuration for code quality and consistency.

Directory Structure

ibw-admin/
├── public/                 # Public static files
│   ├── favicon.ico
│   └── vite.svg
├── src/
│   ├── app/               # Application data
│   │   └── dashboard/
│   │       └── data.json
│   ├── assets/            # Static assets
│   │   ├── react.svg
│   │   └── telegram_bg.png
│   ├── components/        # React components
│   │   ├── ui/           # UI primitives
│   │   ├── quest/        # Quest components
│   │   └── users/        # User components
│   ├── contexts/         # React contexts
│   ├── hooks/            # Custom hooks
│   ├── lib/              # Utilities and API client
│   ├── pages/            # Page components
│   ├── App.tsx           # Main app component
│   ├── App.css           # App styles
│   ├── index.css         # Global styles
│   └── main.tsx          # Entry point
├── dist/                 # Build output
├── node_modules/         # Dependencies
├── .env                  # Environment variables (not in git)
├── .gitignore
├── components.json       # shadcn/ui configuration
├── eslint.config.js      # ESLint config
├── index.html            # HTML template
├── package.json          # Dependencies and scripts
├── README.md             # Project documentation
├── tsconfig.json         # TypeScript config
├── tsconfig.app.json     # TypeScript app config
├── tsconfig.node.json    # TypeScript node config
└── vite.config.ts        # Vite configuration

Path Aliases

The project uses path aliases for cleaner imports:

• @/ → src/

Example:

import { apiClient } from "@/lib/api";
import { Button } from "@/components/ui/button";

Code Style

TypeScript

• Use TypeScript for all new code
• Define interfaces for all data structures
• Use type inference where appropriate
• Avoid any type (use unknown if needed)

React

• Use functional components with hooks
• Use TypeScript for component props
• Follow React best practices
• Use proper key props for lists

Styling

• Use Tailwind CSS utility classes
• Follow mobile-first responsive design
• Use consistent spacing and sizing
• Maintain accessibility standards

Development Workflow

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Make changes

   • Write code following project conventions
   • Add/update tests if applicable
   • Update documentation if needed

3. Test locally

   npm run dev
   npm run lint

4. Commit changes

   git add .
   git commit -m "feat: your feature description"

5. Push and create PR

   git push origin feature/your-feature-name

Common Issues and Solutions

Port Already in Use

If port 5173 is already in use:

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

Or specify a different port:

npm run dev -- --port 3000

Module Resolution Issues

If you encounter module resolution errors:

1. Delete node_modules and package-lock.json
2. Run npm install again
3. Restart your IDE/editor

TypeScript Errors

If TypeScript shows errors:

1. Restart TypeScript server in your IDE
2. Check tsconfig.json configuration
3. Ensure all dependencies are installed

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Performance Optimization

• Code splitting via React.lazy()
• Image optimization
• Bundle size monitoring
• Lazy loading for routes
• Memoization for expensive computations

Security Considerations

• Never commit .env files
• Validate all user inputs
• Sanitize data before rendering
• Use HTTPS in production
• Implement proper authentication checks
• Validate API responses