Contributing to Scrawn

Thank you for your interest in contributing to Scrawn! We're building open-source billing infrastructure for developers, and we welcome contributions from the community.

Google Summer of Code 2026

We're participating in GSoC 2026! Check out our project ideas if you're a student interested in contributing.

Choose Your Area

Scrawn consists of multiple repositories under the ScrawnDotDev organization. Pick the one that matches your interest:

Backend (gRPC Server)

Repository: github.com/ScrawnDotDev/Scrawn
Tech Stack: TypeScript, gRPC, PostgreSQL Good for: Backend development, database optimization, API design

The core backend handles event tracking, usage calculation, and payment processing with a beautiful event-driven architecture. All contributions must preserve this event-driven design. See Quick Start for setup.

SDK (Scrawn.js)

Repository: github.com/ScrawnDotDev/Scrawn.js
Tech Stack: TypeScript
Good for: SDK design, developer experience, client libraries

The TypeScript/JavaScript SDK that developers integrate into their applications. See SDK Guide for usage.

Dashboard

Repository: github.com/ScrawnDotDev/Dashboard
Tech Stack: Next.js, React, TypeScript
Good for: Frontend development, UI/UX, data visualization

The admin dashboard for monitoring events, managing API keys, and viewing analytics. See Dashboard Setup for details.

Documentation

Repository: github.com/ScrawnDotDev/Documentation
Tech Stack: Next.js, Fumadocs, MDX
Good for: Technical writing, examples, tutorials

Help improve our docs by fixing typos, adding examples, or writing guides.

How to Contribute

1. Find an Issue

Browse good first issues
Check help wanted labels
Review our GSoC 2026 project ideas

2. Set Up Your Environment

For backend contributions:

git clone https://github.com/ScrawnDotDev/Scrawn.git
cd Scrawn
bun install

Follow the Quick Start guide for complete setup including database configuration.

For SDK contributions:

git clone https://github.com/ScrawnDotDev/Scrawn.js.git
cd Scrawn.js
bun install
bun run build

Testing SDK Changes Locally

When working on the SDK, you can test your changes in the examples without publishing:

Link the SDK package:

cd packages/scrawn
bun link

Link in your test project:

cd ../../examples  # or any other project
bun link @scrawn/core

Run examples (use Node to avoid Bun's HTTP/2 bugs):

cd examples
npx ts-node middleware-usage.ts
npx ts-node ai-token-stream-usage.ts
npx ts-node sdkcall-usage.ts

After making changes to the SDK, rebuild and examples will automatically use the updated code:

cd packages/scrawn
bun run build

3. Make Your Changes

Create a feature branch: git checkout -b feature/your-feature
Write clean, well-documented code
Add tests for new functionality
Ensure all tests pass: bun test

4. Submit a Pull Request

Push your branch: git push origin feature/your-feature
Open a PR with a clear description
Link related issues
Wait for review and address feedback

Contribution Guidelines

Code Quality

Follow existing code style and conventions
Keep PRs focused and atomic
Add JSDoc comments for public APIs
Ensure TypeScript types are properly defined

Commit Standards

All commits must follow Conventional Commits format and be signed off:

feat: add payment collection endpoint
fix: resolve database connection timeout
docs: update API reference examples
chore: upgrade dependencies

Sign your commits:

git commit -s -m "feat: add new feature"

This adds Signed-off-by: Your Name <your.email@example.com> to your commit message, certifying that you have the right to submit the code under the project's license.