Contributing

How to contribute to Emberly — development setup, code standards, and the pull request process.

Thanks for your interest in contributing to Emberly. This guide covers the development workflow, code standards, and how to submit a pull request.

For initial setup, see the Development Setup guide.

Workflow

1. Fork and Clone

Fork the repo on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/Emberly.git
cd Emberly
bun install

2. Create a Branch

Branch from main using the appropriate prefix:

git checkout main && git pull origin main
git checkout -b feat/your-feature-name

Prefix	Use for
`feat/`	New features
`fix/`	Bug fixes
`docs/`	Documentation only
`refactor/`	Code cleanup with no behavior change
`perf/`	Performance improvements

3. Make Changes and Commit

Commit messages must follow Conventional Commits:

feat(upload): add file compression on upload

Implements client-side GZIP compression before upload to reduce storage.

Closes #123

Common types: feat, fix, docs, refactor, perf, test, ci.

4. Verify Before Pushing

bun run typecheck   # TypeScript — must pass
bun run lint        # ESLint — must pass
bun run build       # Production build — must succeed

5. Open a Pull Request

Push to your fork and open a PR against main. Fill out the PR template:

What does this change?
Why is it needed?
How was it tested?
Are there breaking changes?

Code Standards

TypeScript

All code uses strict: true. Avoid any — use unknown and narrow it:

// Good
function processResult(value: unknown) {
  if (typeof value === "string") return value.trim();
  throw new Error("unexpected type");
}
 
// Bad
function processResult(value: any) {
  return value.trim();
}

API Routes

API handlers live in app/api/. Use the shared response helpers — do not construct raw NextResponse objects:

import { apiResponse, apiError, HTTP_STATUS } from "@/packages/lib/api/response";
import { requireAdmin } from "@/packages/lib/auth/api-auth";

Logging

Never use console.*. Use named loggers from @/packages/lib/logger:

import { loggers } from "@/packages/lib/logger";
const log = loggers.files;
log.info("upload complete", { fileId, size });
log.error("upload failed", error as Error, { fileId });