Contributing

​

Welcome Contributors!

​

Getting Started

​

Prerequisites

nvm install 18
nvm use 18

npm --version

git --version

​

API Keys

1. Google Gemini API Key
   • Sign up at Google AI Studio
   • Create a new API key
   • Free tier available
2. OpenRouter API Key
   • Sign up at OpenRouter
   • Get API key from dashboard
   • Free models available (Deepseek)

​

Development Setup

​

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/OmniSearches.git
cd OmniSearches

​

2. Install Dependencies

npm install

• React and related libraries
• Express.js and backend dependencies
• TypeScript and build tools
• UI component libraries

​

3. Environment Configuration

# Required API Keys
GOOGLE_API_KEY=your_google_api_key_here
REASON_MODEL_API_KEY=your_openrouter_api_key_here

# Optional Configuration
REASON_MODEL_API_URL=https://openrouter.ai/api/v1
REASON_MODEL=deepseek/deepseek-r1-distill-llama-70b:free
NODE_ENV=development
PORT=3000

# Database (if using)
DATABASE_URL=postgresql://user:password@localhost:5432/omnisearches

​

4. Start Development Server

npm run dev

• Express backend on port 3000
• Vite dev server with HMR
• Both frontend and backend in one process

​

5. Verify Setup

http://localhost:3000

​

Project Structure

~/workspace/source/
├── client/src/
│   ├── components/     # React components
│   │   ├── ui/        # shadcn/ui base components
│   │   └── *.tsx      # Feature components
│   ├── pages/         # Route pages (Home, Search)
│   ├── lib/           # Utilities and helpers
│   ├── store/         # Zustand state stores
│   ├── contexts/      # React contexts
│   ├── hooks/         # Custom React hooks
│   └── i18n/          # Internationalization config
├── server/
│   ├── index.ts       # Express server entry
│   ├── routes.ts      # API route handlers
│   ├── env.ts         # Environment setup
│   └── vite.ts        # Vite integration
├── db/                # Database schema
└── package.json       # Dependencies & scripts

​

Development Workflow

​

Making Changes

1. Create a branch
   git checkout -b feature/your-feature-name
   
2. Make your changes
   • Write clean, readable code
   • Follow existing code style
   • Add comments for complex logic
3. Test your changes
   # Type check
   npm run check
   
   # Manual testing in browser
   npm run dev
   
4. Commit your changes
   git add .
   git commit -m "feat: add descriptive commit message"
   

​

Commit Message Convention

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

git commit -m "feat: add image search functionality"
git commit -m "fix: resolve search result rendering issue"
git commit -m "docs: update API documentation"

​

Testing

npm run check

npm run build
npm run start

​

Code Style Guidelines

​

TypeScript

• Use TypeScript for all new code
• Define interfaces for complex objects
• Avoid any types when possible
• Use type inference where appropriate

interface SearchResult {
  title: string;
  url: string;
  snippet: string;
}

const formatResults = (results: SearchResult[]): string[] => {
  return results.map(r => r.title);
};

const formatResults = (results: any) => {
  return results.map((r: any) => r.title);
};

​

React Components

• Use functional components with hooks
• Keep components small and focused
• Extract reusable logic into custom hooks
• Use TypeScript for props

import { useState } from 'react';

interface MyComponentProps {
  title: string;
  onAction?: () => void;
}

export function MyComponent({ title, onAction }: MyComponentProps) {
  const [state, setState] = useState<string>('');
  
  return (
    <div>
      <h2>{title}</h2>
      {/* Component content */}
    </div>
  );
}

​

CSS/Tailwind

• Use Tailwind utility classes
• Follow mobile-first responsive design
• Extract repeated patterns into components
• Use CSS variables from theme

<button className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors">
  Click Me
</button>

​

File Naming

• React components: PascalCase.tsx (e.g., SearchInput.tsx)
• Utilities/hooks: camelCase.ts (e.g., useImageUpload.tsx)
• Pages: PascalCase.tsx (e.g., Home.tsx, Search.tsx)
• Constants: UPPER_SNAKE_CASE

​

Adding Features

​

New UI Components

1. Using shadcn/ui
   npx shadcn-ui@latest add [component-name]
   
   This adds the component to client/src/components/ui/
2. Custom Components Create in client/src/components/:
   // client/src/components/MyFeature.tsx
   export function MyFeature() {
     return <div>My Feature</div>;
   }
   

​

New API Endpoints

app.get('/api/my-endpoint', async (req, res) => {
  try {
    const { param } = req.query;
    
    // Your logic here
    
    res.json({ success: true, data: result });
  } catch (error: any) {
    console.error('Error:', error);
    res.status(500).json({
      message: error.message || 'An error occurred'
    });
  }
});

​

State Management

// client/src/store/myStore.ts
import { create } from 'zustand';

interface MyState {
  value: string;
  setValue: (value: string) => void;
}

export const useMyStore = create<MyState>((set) => ({
  value: '',
  setValue: (value) => set({ value }),
}));

// In your component
import { useQuery } from '@tanstack/react-query';

const { data, isLoading } = useQuery({
  queryKey: ['my-data'],
  queryFn: async () => {
    const response = await fetch('/api/my-endpoint');
    return response.json();
  },
});

​

Internationalization

1. Add to English (client/public/locales/en/translation.json):
   {
     "myFeature": {
       "title": "My Feature",
       "description": "Feature description"
     }
   }
   
2. Add to other languages (zh, zh-HK, etc.)
3. Use in components:
   import { useTranslation } from 'react-i18next';
   
   const { t } = useTranslation();
   
   return <h1>{t('myFeature.title')}</h1>;
   

​

Database Changes

1. Update schema (db/schema.ts):
   export const myTable = pgTable('my_table', {
     id: serial('id').primaryKey(),
     name: text('name').notNull(),
   });
   
2. Push changes:
   npm run db:push
   

​

Submitting Your Contribution

​

Pull Request Process

1. Push your branch
   git push origin feature/your-feature-name
   
2. Create Pull Request
   • Go to GitHub repository
   • Click “New Pull Request”
   • Select your branch
   • Fill out the PR template
3. PR Description Template
   ## Description
   Brief description of what this PR does.
   
   ## Type of Change
   - [ ] Bug fix
   - [ ] New feature
   - [ ] Breaking change
   - [ ] Documentation update
   
   ## Testing
   - [ ] Tested locally
   - [ ] Type checking passes
   - [ ] No console errors
   
   ## Screenshots (if applicable)
   Add screenshots here
   
   ## Related Issues
   Closes #issue_number
   
4. Code Review
   • Address reviewer feedback
   • Make requested changes
   • Push updates to same branch

​

PR Guidelines

​

Common Issues

​

TypeScript Errors

# Run type checker
npm run check

# Fix errors shown
# Add type annotations where needed

​

Port Already in Use

# Find and kill process using port 3000
lsof -ti:3000 | xargs kill -9

# Or change port in .env
PORT=3001

​

API Key Issues

• Verify .env file exists in root directory
• Check API keys are correct (no extra spaces)
• Restart dev server after changing .env
• Ensure environment variables are loaded in server/env.ts

​

Build Failures

# Clear build cache
rm -rf dist/ node_modules/.vite/

# Reinstall dependencies
rm -rf node_modules/
npm install

# Try build again
npm run build

​

Development Tips

​

Hot Reload

• Frontend changes reload automatically (Vite HMR)
• Backend changes require server restart
• To restart server: Ctrl+C then npm run dev

​

Debugging

• Use React DevTools browser extension
• Console logs in browser DevTools
• Inspect TanStack Query cache in DevTools

• Server logs printed to terminal
• Add console.log() statements
• Check request/response in Network tab

• Use tools like Postman or Thunder Client
• Test endpoints directly: curl http://localhost:3000/api/search?q=test

​

Performance Profiling

// React profiling
import { Profiler } from 'react';

<Profiler id="MyComponent" onRender={(id, phase, actualDuration) => {
  console.log({ id, phase, actualDuration });
}}>
  <MyComponent />
</Profiler>

​

Resources

​

Documentation

• React Docs
• Express.js Guide
• TypeScript Handbook
• Tailwind CSS
• Vite Guide
• Gemini API Docs

​

Component Libraries

• shadcn/ui
• Radix UI
• Lucide Icons

​

Community

• GitHub Issues - Report bugs or request features
• GitHub Discussions - Ask questions and share ideas

​

Code of Conduct

​

Be Respectful

• Treat all contributors with respect
• Welcome newcomers and help them learn
• Provide constructive feedback
• Focus on the code, not the person

​

Be Professional

• Use clear, professional language
• Stay on topic in discussions
• Respect different opinions and approaches
• Credit others for their contributions

​

Be Collaborative

• Share knowledge and help others
• Ask questions when unsure
• Review PRs constructively
• Celebrate successes together

​

Recognition

• GitHub contribution graph
• Project README (significant contributions)
• Release notes

​

Questions?

1. Check existing documentation
2. Search GitHub issues
3. Open a new issue with the “question” label
4. Join community discussions