Skip to content

CONTRIBUTION.md

Latest commit

 

History

History
214 lines (138 loc) · 4.09 KB

CONTRIBUTION.md

File metadata and controls

214 lines (138 loc) · 4.09 KB

🤝 Contributing to useSend

Thanks for your interest in contributing to useSend! We’re an open-source email infrastructure platform, and we’d love your help to make it even better. This guide will walk you through how to get started, set up the project locally, and submit contributions.

🧰 Getting Started

All contributions begin with setting up the project locally. Follow the steps below to get started.

📖 Refer to the full setup guide:
https://docs.usesend.com/get-started/local

⚙️ Prerequisites

You’ll need:

  • A GitHub account
  • Node.js v18+
  • pnpm (use corepack enable to activate)
  • Docker (recommended)
  • AWS & Cloudflare accounts (free tiers are fine)

🛠 Setting Up the Project

1. Fork & Clone

git clone https://github.com/YOUR-USERNAME/usesend.git
cd usesend

2. Install Dependencies

corepack enable
pnpm install

3. Setup Environment Variables

cp .env.example .env

Then:

  • Generate a secret:
openssl rand -base64 32

  • Add this to .env as NEXTAUTH_SECRET.

  • Create symlink for Next.js:

ln -s ../../.env apps/web/.env

Next.js requires the .env file in its directory. This symlink ensures both root and apps/web can access the same environment variables.

4. GitHub OAuth (Optional for Dev)

Set up a GitHub OAuth App:

  • Homepage: http://localhost:3000/login
  • Callback: http://localhost:3000/api/auth/callback/github

Add credentials to .env:

GITHUB_ID=your_client_id
GITHUB_SECRET=your_client_secret

5. AWS Credentials (Optional for local email)

If you want to send real emails, add:

AWS_ACCESS_KEY=your_access_key
AWS_SECRET_KEY=your_secret_key

You can skip this by using the local-sen-sns image for local-only email development.

🚀 Running the App

Option 1: Docker (Recommended)

pnpm d

To test GitHub login, run:

cloudflared tunnel --url http://localhost:3000

Paste the Cloudflare URL in your GitHub App callback settings.

Option 2: Manual DB Setup

If you're using your own PostgreSQL & Redis:

  1. Add in .env:
DATABASE_URL=your_postgres_url
REDIS_URL=your_redis_url
  1. Migrate database:
pnpm db:migrate-dev
  1. Start dev server:
pnpm dev
  1. Use cloudflared as mentioned above if needed.

📝 Run Documentation Locally

pnpm dev:docs

📂 Code Structure Overview

apps/
├── web          # Dashboard & Email Infra
├── marketing    # Landing page
├── docs         # This documentation site

packages/
├── eslint-config     # Shared ESLint rules
├── sdk               # TypeScript SDK for useSend REST API
├── tailwind-config   # Shared Tailwind setup
├── typescript-config # Shared tsconfig
├── ui                # Shared UI components (buttons, modals, etc.)

🧑‍💻 Making Contributions

  1. Create a Feature Branch
git checkout -b feat/your-feature

  1. Make Your Changes

    • Follow the existing project structure.
    • Write clean, modular, and reusable code.
    • Formatting is enforced with Prettier.

  2. Commit Your Work

git add .
git commit -m "feat: your message here"
  1. Push and Open a Pull Request
git push origin feat/your-feature
  • Open a PR against the main branch
  • Fill in the PR template

💬 Community and Support

🙋 Questions?

Need help or unsure where to begin? Just ask!

We’re excited to see your ideas and contributions! 💌