Contributing to Uxie

Thank you for your interest in contributing to Uxie! This guide will help you set up your development environment and understand our development workflow.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js v18+

Download from nodejs.org

node --version  # Should be v18.16.0 or higher

pnpm Package Manager

Install pnpm globally:

npm install -g [email protected]

Or use Corepack (recommended):

corepack enable
corepack prepare [email protected] --activate

Git

For cloning the repository and version control.

Getting Started

1. Fork and Clone

Fork the Repository

Visit github.com/zeus-12/uxie and click the “Fork” button to create your own copy.

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/uxie.git
cd uxie

Add Upstream Remote

git remote add upstream https://github.com/zeus-12/uxie.git

This allows you to pull updates from the main repository.

2. Install Dependencies

pnpm install

This will:

Install all npm dependencies
Apply patches to react-pdf-highlighter
Generate Prisma Client types

3. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

Now configure each service:

Database Setup (Supabase)

Go to supabase.com and create a new project
Once created, navigate to Settings → Database
Copy the connection string and add to .env:

DATABASE_URL="postgresql://postgres:[PASSWORD]@[HOST]:[PORT]/postgres"

Run migrations:

pnpm prisma db push

Authentication (NextAuth + Google OAuth)

Go to Google Cloud Console
Create a new project (or select existing)
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth 2.0 Client ID
Configure consent screen if prompted
Set Authorized redirect URIs:
- http://localhost:3000/api/auth/callback/google
Copy credentials to .env:

GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

Generate NextAuth secret:

openssl rand -base64 32

Add to .env:

NEXTAUTH_SECRET="generated-secret"
NEXTAUTH_URL="http://localhost:3000"

File Upload (UploadThing)

Go to uploadthing.com and sign up
Create a new app
Copy your API token:

UPLOADTHING_TOKEN="your-token"

Vector Database (Pinecone)

Go to pinecone.io and sign up
Create a new index with:
- Name: uxie
- Dimensions: 768
- Metric: cosine
- Region: Choose closest to you
Copy your API key:

PINECONE_API_KEY="your-api-key"
PINECONE_ENVIRONMENT="your-environment"  # e.g., us-east-1

AI Services

HuggingFace (Embeddings)

Sign up at huggingface.co
Go to Settings → Access Tokens
Create a new token:

HUGGINGFACE_API_KEY="hf_..."

Google AI (Gemini)

Go to ai.google.dev
Get an API key
Add to .env:

GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"

Collaboration (Optional - Liveblocks)

Currently disabled in production due to free tier limits, but you can enable locally:

Go to liveblocks.io and sign up
Create a new project
Copy your public API key:

NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_API_KEY="pk_..."

4. Start Development Server

pnpm dev

The app will be available at http://localhost:3000

Development Workflow

Creating a New Branch

Always create a new branch for your changes:

git checkout -b feature/your-feature-name

Or for bug fixes:

git checkout -b fix/bug-description

Making Changes

Write Code

Make your changes following our coding standards (see below).

Test Locally

Ensure your changes work:

pnpm dev

Type Check

Verify TypeScript types:

pnpm typecheck

Lint

Check code quality:

pnpm lint

Format

Format code with Prettier:

pnpm format

Committing Changes

We follow conventional commit messages:

git add .
git commit -m "feat: add PDF thumbnail preview"

Commit Types:

Type	Description	Example
`feat`	New feature	`feat: add export to markdown`
`fix`	Bug fix	`fix: resolve highlight position offset`
`docs`	Documentation	`docs: update contributing guide`
`style`	Code style (no logic change)	`style: format with prettier`
`refactor`	Code refactoring	`refactor: extract PDF utils`
`perf`	Performance improvement	`perf: optimize vector search`
`test`	Add/update tests	`test: add flashcard tests`
`chore`	Maintenance	`chore: update dependencies`

Opening a Pull Request

Push to Your Fork

git push origin feature/your-feature-name

Create Pull Request

Go to github.com/zeus-12/uxie
Click “Compare & pull request”
Fill in the PR template
Link any related issues

Review Process

Maintainers will review your PR
Address any feedback
Once approved, your PR will be merged!

Coding Standards

TypeScript

Strict Mode

Always use TypeScript in strict mode.

No any types (use unknown)
Explicit return types for functions
Null checks required

Type Inference

Prefer type inference when obvious:

// Good
const count = 5;

// Unnecessary
const count: number = 5;

React Components

Prefer Function Components:

// ✅ Good
export function MyComponent({ title }: { title: string }) {
  return <h1>{title}</h1>;
}

// ❌ Avoid
export const MyComponent: React.FC<{ title: string }> = ({ title }) => {
  return <h1>{title}</h1>;
};

Use Semantic JSX:

// ✅ Good
<button type="button" onClick={handleClick}>
  Click me
</button>

// ❌ Avoid
<div onClick={handleClick}>Click me</div>

File Organization

Component Structure

components/
├── feature-name/
│   ├── index.tsx          # Main component
│   ├── sub-component.tsx  # Related components
│   └── utils.ts           # Helper functions

Import Order

Prettier will auto-sort, but follow this pattern:

React imports
Third-party libraries
Internal utilities
Types
Styles

Naming Conventions

Components: PascalCase (PdfReader.tsx)
Utilities: camelCase (formatDate.ts)
Constants: UPPER_SNAKE_CASE
Types/Interfaces: PascalCase

tRPC Procedures

Input Validation:

import { z } from "zod";

export const documentRouter = createTRPCRouter({
  getById: protectedProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ ctx, input }) => {
      return await ctx.prisma.document.findUnique({
        where: { id: input.id },
      });
    }),
});

Always use protected procedures for authenticated routes.

Prisma Schema

When modifying schema.prisma:

Make changes

Generate migration:

pnpm prisma migrate dev --name describe_change

Generate client:
```
pnpm prisma generate
```

Tailwind CSS

Use utility classes:

// ✅ Good
<div className="flex items-center gap-4 rounded-lg bg-white p-4">

// ❌ Avoid custom CSS
<div className="my-custom-class">

Use cn() helper for conditional classes:

import { cn } from "@/lib/utils";

<div className={cn(
  "base-classes",
  isActive && "active-classes",
  className  // Allow external classes
)} />

Testing Locally

Manual Testing Checklist

Before submitting a PR, test:

Authentication Flow

Can sign in with Google
Can sign out
Protected routes redirect to login

Document Management

Can upload PDF
Can view PDF in reader
Can add highlights
Can add notes

AI Features

Chat works and streams responses
Flashcard generation works
Flashcard evaluation works

Database Inspection

Use Prisma Studio to inspect database:

pnpm prisma studio

Opens at http://localhost:5555

Common Issues

Port Already in Use

If port 3000 is taken:

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

# Or use different port
PORT=3001 pnpm dev

Prisma Client Not Generated

If you see Prisma import errors:

pnpm prisma generate

This regenerates the Prisma Client.

Type Errors After Pull

After pulling latest changes:

pnpm install  # Install new dependencies
pnpm prisma generate  # Regenerate Prisma types

Environment Variable Issues

Ensure .env is in root directory (same level as package.json).Restart dev server after changing .env.

Project Scripts

Command	Description
`pnpm dev`	Start development server
`pnpm build`	Build for production
`pnpm start`	Start production server
`pnpm lint`	Run ESLint
`pnpm typecheck`	Check TypeScript types
`pnpm format`	Format code with Prettier
`pnpm prisma studio`	Open Prisma Studio
`pnpm prisma migrate dev`	Create/apply migration
`pnpm prisma db push`	Push schema without migration

Areas for Contribution

Looking for where to help? Check these areas:

Bug Fixes

Fix .tippy-arrow appearing on screen
Improve error and loading pages
Fix highlight positioning issues

Features

Build category/tags system
Implement rate limiting with Redis
Semantic search improvements
PDF summary generation

Performance

Optimize PDF rendering
Reduce bundle size
Improve vector search speed

Documentation

Add JSDoc comments
Write component docs
Create user guides

Code Review Guidelines

When reviewing PRs:

Be kind and constructive
Focus on code, not the person
Explain the “why” behind feedback
Approve when ready, request changes when needed
Test the changes locally if possible

Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Feedback: Feedback Form

License

By contributing to Uxie, you agree that your contributions will be licensed under the project’s license.

Contributing

Contributing Guide

Contributing to Uxie

Prerequisites

Getting Started

1. Fork and Clone

2. Install Dependencies

3. Set Up Environment Variables

4. Start Development Server

Development Workflow

Creating a New Branch

Making Changes

Committing Changes

Opening a Pull Request

Coding Standards

TypeScript

Strict Mode

Type Inference

React Components

File Organization

tRPC Procedures

Prisma Schema

Tailwind CSS

Testing Locally

Manual Testing Checklist

Database Inspection

Common Issues

Project Scripts

Areas for Contribution

Bug Fixes

Features

Performance

Documentation

Code Review Guidelines

Community

License

Next Steps

Architecture

Deployment

Build docs developers (and LLMs) love

Contributing

​Contributing to Uxie

​Prerequisites

​Getting Started

​1. Fork and Clone

​2. Install Dependencies

​3. Set Up Environment Variables

​4. Start Development Server

​Development Workflow

​Creating a New Branch

​Making Changes

​Committing Changes

​Opening a Pull Request

​Coding Standards

​TypeScript

Strict Mode

Type Inference

​React Components

​File Organization

​tRPC Procedures

​Prisma Schema

​Tailwind CSS

​Testing Locally

​Manual Testing Checklist

​Database Inspection

​Common Issues

​Project Scripts

​Areas for Contribution

Bug Fixes

Features

Performance

Documentation

​Code Review Guidelines

​Community

​License

​Next Steps

Architecture

Deployment

Build docs developers (and LLMs) love

Contributing to Uxie

Prerequisites

Getting Started

1. Fork and Clone

2. Install Dependencies

3. Set Up Environment Variables

4. Start Development Server

Development Workflow

Creating a New Branch

Making Changes

Committing Changes

Opening a Pull Request

Coding Standards

TypeScript

React Components

File Organization

tRPC Procedures

Prisma Schema

Tailwind CSS

Testing Locally

Manual Testing Checklist

Database Inspection

Common Issues

Project Scripts

Areas for Contribution

Code Review Guidelines

Community

License

Next Steps