Contributing Guide

​

Getting Started

​

Prerequisites

• Node.js (v18 or higher recommended)
• npm (comes with Node.js)
• Git for version control

​

Setting Up Development Environment

1. Clone the repository
   git clone <repository-url>
   cd source
   
2. Install dependencies
   npm install
   
3. Start the development server
   npm run dev
   
   The application will be available at http://localhost:5173
4. Verify the setup
   • Open the URL in your browser
   • Check that the application loads correctly
   • Try navigating between pages

​

Available Scripts

​

Development

npm run dev

​

Building

npm run build

• Bundles all JavaScript and CSS
• Minifies and optimizes assets
• Generates static files ready for deployment

​

Preview

npm run preview

​

Linting

npm run lint

​

Code Style and Standards

​

ESLint Configuration

• React Hooks Rules: Enforces Rules of Hooks and exhaustive deps
• React Refresh: Ensures components support HMR
• No Unused Variables: Error, except for uppercase variables (components)

​

Code Formatting

• Use ES6+ features (arrow functions, destructuring, etc.)
• Use functional components with hooks (no class components)
• Use named exports for components
• Keep components focused and single-purpose

import { useState } from 'react'
import styles from './MyComponent.module.css'

export function MyComponent({ propName }) {
  const [state, setState] = useState(initialValue)
  
  return (
    <div className={styles.container}>
      {/* Component JSX */}
    </div>
  )
}

• Use @/ path alias for src imports
• Group imports: React → third-party → local components → hooks → styles
• Use named imports from the components barrel file

• Use CSS Modules for component-specific styles
• Name CSS files with .module.css extension
• Use semantic class names

​

Adding New Components

​

Step 1: Create Component Directory

mkdir src/components/MyNewComponent

​

Step 2: Create Component File

import styles from './MyNewComponent.module.css'

export function MyNewComponent({ prop1, prop2 }) {
  return (
    <div className={styles.container}>
      {/* Your component markup */}
    </div>
  )
}

​

Step 3: Create Styles (Optional)

.container {
  /* Component styles */
}

​

Step 4: Export Component

export * from './MyNewComponent/MyNewComponent.jsx'

​

Step 5: Use the Component

import { MyNewComponent } from '@/components'

function ParentComponent() {
  return <MyNewComponent prop1="value" prop2={data} />
}

​

Adding New Pages

​

Step 1: Create Page Component

import { Header, Footer } from '@/components'
import styles from './MyPage.module.css'

export function MyPage() {
  return (
    <>
      <Header />
      <main className={styles.main}>
        {/* Page content */}
      </main>
      <Footer />
    </>
  )
}

​

Step 2: Add Route

import { Routes, Route } from 'react-router-dom'
import { MyPage } from './pages/MyPage'

function App() {
  return (
    <Routes>
      {/* Existing routes */}
      <Route path="/my-page" element={<MyPage />} />
    </Routes>
  )
}

​

Step 3: Add Navigation (Optional)

import { Link } from '@/components'

<Link href="/my-page">My Page</Link>

​

Creating Custom Hooks

​

Hook Structure

• Start with use prefix
• Be placed in src/hooks/
• Return values and functions needed by components
• Encapsulate reusable logic

// src/hooks/useMyHook.js
import { useState, useEffect } from 'react'

export function useMyHook(initialValue) {
  const [state, setState] = useState(initialValue)
  
  useEffect(() => {
    // Side effects
  }, [dependencies])
  
  return { state, setState }
}

​

Using Hooks

import { useMyHook } from '@/hooks/useMyHook'

function MyComponent() {
  const { state, setState } = useMyHook(initialValue)
  // Use the hook values
}

​

Testing Approach

​

Recommended Testing Strategy

1. Unit Tests: Test individual components and hooks
2. Integration Tests: Test component interactions
3. E2E Tests: Test complete user workflows

​

Suggested Tools

• Vitest: Fast unit testing with Vite integration
• React Testing Library: Component testing
• Playwright or Cypress: E2E testing

​

Manual Testing Checklist

• Component renders correctly
• All interactive features work (buttons, forms, links)
• Responsive design works on different screen sizes
• No console errors or warnings
• Navigation works correctly
• Browser back/forward buttons work as expected
• ESLint passes (npm run lint)

​

Submitting Changes

​

Before You Commit

1. Run the linter
   npm run lint
   
   Fix any errors or warnings.
2. Test your changes
   • Run the dev server and verify functionality
   • Test edge cases and different scenarios
   • Check responsive design
3. Review your code
   • Remove console.logs and debug code
   • Check for commented-out code
   • Ensure proper formatting

​

Commit Message Guidelines

type: Short description (50 chars or less)

Optional detailed explanation of what changed and why.

• feat: New feature
• fix: Bug fix
• refactor: Code refactoring
• style: Formatting, missing semicolons, etc.
• docs: Documentation changes
• chore: Maintenance tasks

feat: Add job filtering by experience level

fix: Correct pagination offset calculation

refactor: Extract search logic into useSearchForm hook

​

Pull Request Process

1. Create a feature branch
   git checkout -b feature/my-new-feature
   
2. Make your changes and commit
   git add .
   git commit -m "feat: Add my new feature"
   
3. Push to remote
   git push origin feature/my-new-feature
   
4. Open a Pull Request
   • Provide a clear title and description
   • Reference any related issues
   • Add screenshots for UI changes
   • Request review from maintainers
5. Address feedback
   • Make requested changes
   • Push updates to the same branch
   • Respond to comments

​

Common Issues and Solutions

​

Port Already in Use

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

# Or specify a different port
vite --port 3000

​

Module Not Found

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

​

ESLint Errors

# Check specific files
npm run lint -- --fix

# Manually fix issues that can't be auto-fixed

​

Import Path Issues

• Use @/components instead of relative paths
• Check vite.config.js and jsconfig.json for alias configuration

​

Getting Help

1. Check existing documentation in this docs site
2. Review project structure to understand the codebase
3. Look at existing components for examples
4. Check the console for error messages
5. Ask for help from maintainers or other contributors

​

Code Review Guidelines

• Code follows project conventions
• Component structure is logical
• No unnecessary dependencies added
• Styles use CSS Modules appropriately
• Imports use path aliases
• No console.logs or debug code
• Code is readable and well-organized
• Changes are focused and purposeful

​

Next Steps

1. Explore the Project Structure to understand the codebase
2. Pick an issue or feature to work on
3. Set up your development environment
4. Start coding and have fun!