Contributing
Contributing
How to set up the Cursorist project locally and submit your first contribution.
Thank you for your interest in contributing to Cursorist. This guide walks you through the local setup, project structure, and contribution workflow.
Prerequisites
- Node.js 18+ and npm
- Git
- Supabase CLI (optional, for running the backend locally)
Clone and Install
git clone https://github.com/gurkanfikretgunak/cursorist.git
cd cursorist
npm installRun the Development Server
npm run devOpen http://localhost:3000. The app hot-reloads on file changes.
Project Structure
| Directory | What It Contains |
|---|---|
app/ | Next.js App Router pages and API routes |
components/ | React components (UI, navigation, plugin wizard) |
lib/ | Shared utilities, Supabase client, source loader |
cli/ | CLI tool source (commands, types, utilities) |
content/docs/ | Documentation pages (Fumadocs MDX) |
supabase/ | Migrations, edge functions, seed data |
hooks/ | Custom React hooks |
public/ | Static assets |
Tech Stack
| Technology | Role |
|---|---|
| Next.js 16 | App Router, React Server Components, API routes |
| Supabase | Auth (GitHub OAuth), Postgres database, storage, edge functions |
| Tailwind CSS 4 | Styling, CSS-based configuration |
| Fumadocs | MDX-powered documentation |
| TypeScript | Type safety across the entire project |
| Shadcn UI | Reusable UI components |
Making Changes
- Create a branch from
main:
git checkout -b feature/your-feature-
Make your changes — code, docs, or both.
-
Test locally — run
npm run devand verify your changes work. -
Build check — make sure the production build passes:
npm run build- Commit with a descriptive message:
git commit -m "feat: add plugin upgrade notification"- Push and open a PR:
git push origin feature/your-featureCommit Message Convention
Use conventional commits:
| Prefix | When to Use |
|---|---|
feat: | New feature |
fix: | Bug fix |
docs: | Documentation only |
refactor: | Code change that does not add a feature or fix a bug |
chore: | Build config, dependencies, tooling |
Contributing to Documentation
Docs live in content/docs/ as .mdx files. Each file needs YAML frontmatter:
---
title: Page Title
description: One-line description for search and SEO.
---
Your content here...When adding a new page:
- Create the
.mdxfile in the appropriate section folder - Update the
meta.jsonin that folder to include your new page slug - Run
npm run devto preview
Code Style
- TypeScript strict mode — no
anyunless absolutely necessary - Tailwind CSS — use utility classes, avoid custom CSS
- Shadcn UI — use existing components before creating new ones
- Functional components — with hooks, no class components
Where to Start
Not sure what to work on? Good first contributions:
- Improve documentation clarity or add missing examples
- Fix typos or broken links
- Add error handling to CLI commands
- Improve accessibility in UI components