Thank you for your interest in contributing to ɳChat! This document provides guidelines and instructions for contributing to the project.

• Code of Conduct
• Getting Started
• Development Workflow
• Code Standards
• Testing Requirements
• Pull Request Process
• Issue Guidelines
• License

By participating in this project, you agree to:

• Be respectful and inclusive to all contributors
• Provide constructive feedback
• Focus on what's best for the community
• Show empathy towards other community members

• Node.js 20+ - Use the version specified in .node-version
• pnpm 9.15.4+ - Install with npm install -g pnpm
• Docker (optional) - For running backend services locally

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/nself-chat.git
cd nself-chat

# 2. Install dependencies
pnpm install

# 3. Create environment file
cp .env.example .env.local
# Edit .env.local with your configuration

# 4. Start development server
pnpm dev

Visit http://localhost:3000 to see the application running.

To run with full backend (PostgreSQL, Hasura, Auth, Storage):

# Option 1: Using nself CLI (recommended)
cd .backend
nself start

# Option 2: Using Docker Compose
docker-compose up -d

• feature/feature-name - New features
• fix/bug-description - Bug fixes
• docs/description - Documentation updates
• refactor/description - Code refactoring
• test/description - Test additions or fixes
• chore/description - Build/tooling changes

Follow Conventional Commits:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Build process or tooling changes
• perf: Performance improvements

Examples:

feat(chat): add message reactions
fix(auth): resolve login redirect issue
docs(readme): update installation instructions

• Use TypeScript for all new code
• TypeScript strict mode is enforced ("strict": true in tsconfig.json); all PRs must pass pnpm tsc --noEmit
• Define proper types/interfaces (avoid any)
• Use proper return types for functions

// ✅ Good - Functional component with proper types
interface ButtonProps {
  variant?: 'primary' | 'secondary'
  children: React.ReactNode
  onClick?: () => void
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return <button className={cn(variant)} onClick={onClick}>{children}</button>
}

// ❌ Bad - No types, inline styles
export function Button(props) {
  return <button style={{ color: 'red' }}>{props.children}</button>
}

src/
├── app/              # Next.js App Router pages
├── components/       # React components
│   ├── ui/          # Reusable UI components (buttons, inputs, etc.)
│   └── [feature]/   # Feature-specific components
├── hooks/           # Custom React hooks
├── lib/             # Utility functions and helpers
├── contexts/        # React contexts
├── services/        # API and service integrations
├── types/           # TypeScript type definitions
└── graphql/         # GraphQL queries and mutations

• Use Tailwind CSS utility classes
• Use CVA (class-variance-authority) for component variants
• Use cn() helper for conditional classes
• Avoid inline styles

// ✅ Good
<div className={cn('rounded-lg p-4', isActive && 'bg-primary')}>

// ❌ Bad
<div style={{ borderRadius: '8px', padding: '16px' }}>

• Use Zustand for global state
• Use React Context for feature-specific state
• Use Apollo Client for GraphQL data
• Keep state as local as possible

# Unit/integration tests (Jest)
pnpm test              # Run once
pnpm test:watch        # Watch mode
pnpm test:coverage     # With coverage report

# E2E tests (Playwright)
pnpm test:e2e          # Run E2E tests
pnpm test:e2e:ui       # Interactive UI mode

# Type checking
pnpm type-check        # Check TypeScript types

# Linting
pnpm lint              # Check for errors
pnpm lint:fix          # Auto-fix issues

# Format checking
pnpm format:check      # Check formatting
pnpm format            # Auto-format files

• Minimum 80% coverage for new code
• All bug fixes must include regression tests
• Critical features require E2E tests

// Component test example
import { render, screen } from '@testing-library/react'
import { Button } from './button'

describe('Button', () => {
  it('renders with correct text', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('calls onClick handler', () => {
    const handleClick = jest.fn()
    render(<Button onClick={handleClick}>Click me</Button>)
    screen.getByText('Click me').click()
    expect(handleClick).toHaveBeenCalledTimes(1)
  })
})

1. Update your branch with the latest main:

   git checkout main
   git pull origin main
   git checkout your-branch
   git rebase main

2. Run all checks:

   pnpm check-all

3. Update documentation if needed

4. Add tests for new functionality

Use the same format as commit messages:

feat(chat): add message reactions
fix(auth): resolve login redirect issue

## Description

Brief description of what this PR does.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] Unit tests added/updated
- [ ] E2E tests added/updated
- [ ] Manual testing completed

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests pass locally

1. Automated checks must pass (CI/CD pipeline)
2. At least one approval required from maintainers
3. All conversations resolved before merging
4. Merges use squash and merge strategy

Use the appropriate issue template:

• Bug Report - For reporting bugs
• Feature Request - For suggesting new features
• Documentation - For documentation improvements
• Question - For asking questions

Be specific and descriptive:

✅ Good:
- "Chat: Messages not loading in Safari 16"
- "Feature: Add message scheduling"
- "Docs: Update deployment guide for Kubernetes"

❌ Bad:
- "Bug"
- "Feature request"
- "Help needed"

1. Search existing issues to avoid duplicates
2. Check documentation for answers
3. Try latest version to see if already fixed

# Development
pnpm dev                  # Start dev server
pnpm dev:turbo           # Start with Turbopack

# Building
pnpm build               # Production build
pnpm build:analyze       # Build with bundle analyzer
pnpm build:docker        # Build Docker image

# Testing
pnpm test                # Run Jest tests
pnpm test:e2e            # Run Playwright tests
pnpm test:coverage       # Test with coverage

# Code Quality
pnpm lint                # Run ESLint
pnpm lint:fix            # Fix linting issues
pnpm format              # Format with Prettier
pnpm type-check          # Check TypeScript types

# Validation
pnpm check-all           # Run all checks
pnpm validate            # Type-check, lint, test, build

# Backend (nself CLI)
pnpm backend:start       # Start backend services
pnpm backend:stop        # Stop backend services
pnpm backend:status      # Check service status

# Database
pnpm db:migrate          # Run migrations
pnpm db:seed             # Seed database
pnpm db:types            # Generate TypeScript types

nself-chat/
├── .backend/                # nself CLI backend (gitignored)
├── .github/                # GitHub workflows and templates
├── deploy/                 # Deployment configurations
├── docs/                   # Documentation
├── e2e/                    # End-to-end tests
├── platforms/              # Platform-specific builds
│   ├── capacitor/         # iOS/Android (Capacitor)
│   ├── electron/          # Desktop (Electron)
│   ├── tauri/             # Desktop (Tauri)
│   └── react-native/      # Mobile (React Native)
├── public/                 # Static assets
├── scripts/                # Build and utility scripts
├── src/
│   ├── app/               # Next.js App Router
│   ├── components/        # React components
│   ├── contexts/          # React contexts
│   ├── graphql/           # GraphQL operations
│   ├── hooks/             # Custom hooks
│   ├── lib/               # Utilities and helpers
│   ├── providers/         # React providers
│   ├── services/          # API services
│   ├── stores/            # Zustand stores
│   └── types/             # TypeScript types
├── .env.example           # Environment variables template
├── package.json           # Dependencies and scripts
└── README.md              # Project overview

• Frontend: Next.js 15 + React 19 + TypeScript 5.7
• Backend: nself CLI (PostgreSQL + Hasura + Nhost Auth)
• State: Zustand + Apollo Client
• UI: Radix UI + Tailwind CSS + CVA
• Real-time: Socket.io + GraphQL subscriptions
• Testing: Jest + Playwright
• CI/CD: GitHub Actions

1. Config-First: All behavior controlled via AppConfig
2. CVA Pattern: Component variants with class-variance-authority
3. Provider Stack: Nhost → AppConfig → Theme → Apollo → Auth
4. Dual Auth: Development (FauxAuth) and Production (Nhost)
5. LocalStorage-First: Config loads from localStorage, syncs with DB

• Documentation: Check docs/ directory
• Issues: Search existing issues or create new one
• Discussions: Use GitHub Discussions for questions
• Discord: Join our community server (link in README)

By contributing to ɳChat, you agree that your contributions will be licensed under the same license as the project. See LICENSE for details.

Contributors will be recognized in:

• CHANGELOG.md for each release
• GitHub contributors page
• Project website (if applicable)

Thank you for contributing to ɳChat! 🎉