From 92f9db255fff5ba9520fc17c83d19ae83a19a993 Mon Sep 17 00:00:00 2001 From: siddesh-privy Date: Tue, 23 Sep 2025 18:46:29 +0700 Subject: [PATCH] feat: external contributions guide --- .github/ISSUE_TEMPLATE/example-request.yml | 63 +++++ .github/pull_request_template.md | 50 ++++ CONTRIBUTING.md | 256 +++++++++++++++++++++ 3 files changed, 369 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/example-request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/example-request.yml b/.github/ISSUE_TEMPLATE/example-request.yml new file mode 100644 index 0000000..3a00458 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/example-request.yml @@ -0,0 +1,63 @@ +name: Example Request +description: Request a new Privy integration example +title: "[REQUEST] " +labels: ["example-request"] +body: + - type: input + id: framework + attributes: + label: Framework + description: What framework would you like to see integrated? + placeholder: e.g., Vue, Svelte, Flutter, Python + validations: + required: true + - type: input + id: integration + attributes: + label: Integration/Use Case + description: What specific integration or use case? + placeholder: e.g., Tron integration, Account Abstraction, DeFi protocol + validations: + required: true + - type: input + id: blockchain + attributes: + label: Blockchain/Chain + description: Which blockchain or chain (if applicable)? + placeholder: e.g., Tron, Bitcoin, Base, Arbitrum + validations: + required: false + - type: textarea + id: description + attributes: + label: Description + description: Brief description of the example you'd like to see + validations: + required: true + - type: checkboxes + id: features + attributes: + label: Key Privy Features + description: What specific Privy features should this example demonstrate? + options: + - label: Authentication + - label: Wallet connection + - label: Smart wallets + - label: Cross-chain operations + - label: Gasless transactions + - label: Session keys + - label: Account abstraction + - type: textarea + id: use-case + attributes: + label: Use Case & Value + description: Why would this example be valuable to the community? + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional Context + description: Any additional information, links, or references that would help build this example + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..9a77438 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,50 @@ +## Description + +Brief description of the example and what it demonstrates. + +## Type of Example + +- [ ] New framework integration +- [ ] New blockchain integration +- [ ] New use case implementation +- [ ] Advanced feature demonstration +- [ ] Developer tooling +- [ ] Enhancement to existing example + +## Framework & Integration + +- **Framework**: (e.g., Vue, Svelte, Flutter) +- **Blockchain/Chain**: (e.g., Tron, Bitcoin, Base) +- **Key Integration**: (e.g., Uniswap, Account Abstraction, Cross-chain) + +## Features Implemented + +- [ ] Feature 1 +- [ ] Feature 2 +- [ ] Feature 3 + +## Testing Checklist + +- [ ] Fresh installation works from README instructions +- [ ] All environment variables documented in `.env.example` +- [ ] README instructions are accurate and complete +- [ ] No secrets or API keys committed + +## Template Used (if applicable) + +- [ ] Started from existing Privy template: +- [ ] Built from scratch + +## Related Issues + +Fixes #issue-number (if applicable) + +--- + +### Contributor Checklist + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] My example is placed in `community-maintained-examples/` +- [ ] I have followed the naming convention `{framework}-{usecase}` +- [ ] I have included all mandatory files (README.md, .env.example, package.json) +- [ ] I have tested the example in a fresh environment diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f6ff562 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,256 @@ +# Contributing to Privy Examples + +This collection showcases various integrations and use cases around Privy. + +## What We're Looking For + +We welcome community examples showcasing **Privy integrations** with: + +- **New Frameworks** (Vue, Svelte, Angular, Flutter, etc.) +- **Blockchain Integrations** (Tron, Bitcoin, Base, Arbitrum, etc.) +- **DeFi & Web3 Protocols** (Uniswap, Aave, NFT marketplaces, gaming) +- **Advanced Features** (Account abstraction, cross-chain, gasless transactions) +- **Mobile & Backend** (React Native, Node.js, Python, webhooks) +- **Developer Tools** (CLI tools, testing utilities, deployment scripts) + +## Before You Start + +1. **Check Existing Examples**: Review the [README.md](./README.md) to ensure your idea isn't already covered +2. **Choose Your Starting Point**: You can either: + - Use an existing Privy template (`privy-next-starter/`, `privy-react-starter/`, etc.) as your base + - Build from scratch following our structure patterns +3. **Follow the Structure**: Use our established patterns for consistency + +**Optional**: If you want to request a specific example or discuss a complex integration before building, feel free to open an issue first. + +## Repository Structure + +``` +# Official Privy examples (maintained by Privy team) +privy-next-starter/ +privy-react-starter/ +privy-expo-starter/ +examples/ +├── privy-next-farcaster/ +├── privy-react-funding/ +└── ... + +# Community contributions go here +community-maintained-examples/ +├── {framework}-{usecase}/ # Your example directory +│ ├── README.md # Setup and usage instructions +│ ├── package.json # Dependencies and scripts +│ ├── .env.example # Environment variable template +│ ├── src/ # Source code +│ └── public/ # Static assets (if applicable) +└── ... +``` + +## Getting Started + +### 1. Fork and Clone + +```bash +# Fork the repository on GitHub, then clone your fork +git clone https://github.com/YOUR-USERNAME/examples.git +``` + +### 2. Create Your Example + +```bash +# Option A: Copy an existing Privy template as starting point +cp -r privy-next-starter community-maintained-examples/{framework}-{usecase} +cd community-maintained-examples/{framework}-{usecase} + +# Option B: Create from scratch +mkdir community-maintained-examples/{framework}-{usecase} +cd community-maintained-examples/{framework}-{usecase} +``` + +### 3. Example Naming Convention + +Use this pattern: `{framework}-{usecase/feature/integration}` + +**Good Examples:** + +- `vue-smart-wallets` +- `svelte-farcaster-integration` +- `angular-permissionless` +- `node-webhook-handler` +- `python-analytics-dashboard` +- `flutter-defi-wallet` + +**Avoid:** + +- Generic names like `example` or `test-app` +- Overly long names with multiple features +- Using "privy-" prefix (reserved for official examples) + +## Example Requirements + +### Mandatory Files + +#### 1. README.md Template + +**Follow the exact structure used in official Privy examples** (see `privy-next-starter/`, `privy-react-whitelabel-starter/`, etc.). + +Your README should include these sections: + +```markdown +# {Framework} {Feature} Example + +Brief description of what this example demonstrates and its key value proposition. + +## Live Demo (if applicable) + +[View Demo](https://your-demo-url.com/) + +## Getting Started + +### 1. Clone the Project + + git clone https://github.com/privy-io/examples.git + cd community-maintained-examples/{framework}-{usecase} + +### 2. Install Dependencies + + npm install + +### 3. Configure Environment + +Copy the example environment file and configure your Privy app credentials: + + cp .env.example .env.local + +Update `.env.local` with your Privy app credentials: + + # Public - Safe to expose in the browser + NEXT_PUBLIC_PRIVY_APP_ID=your_app_id_here + # Add other environment variables as needed + +**Important:** Get your credentials from the [Privy Dashboard](https://dashboard.privy.io). + +### 4. Configure Dashboard Settings (if needed) + +1. Enable desired login methods in the [Privy Dashboard](https://dashboard.privy.io/apps?page=login-methods) +2. [Optional] Enable guest accounts under Settings > Advanced settings > Guest accounts +3. [Optional] Configure any additional settings specific to your example + +### 5. Start Development Server + + npm run dev + +## Core Functionality + +Brief explanation of key features and implementation details with code snippets when helpful. + +## Learn More + +- [Privy Documentation](https://docs.privy.io) +- [Framework-specific Documentation] +- [Integration-specific Documentation] +``` + +#### 2. .env.example File + +Always include an `.env.example` with necessary environment variables: + +```bash +# Privy Configuration +NEXT_PUBLIC_PRIVY_APP_ID=your-app-id-here + +# Additional variables as needed +# NEXT_NEYNAR_API_KEY= +``` + +### Code Quality Standards + +1. **TypeScript First**: Use TypeScript when possible +2. **Modern Practices**: Use latest framework patterns and best practices +3. **Clean Code**: Meaningful variable names, proper comments, modular structure +4. **Error Handling**: Implement proper error boundaries and user feedback + +## Testing Your Example + +Before submitting: + +1. **Fresh Installation Test**: Clone your example in a clean environment +2. **Environment Setup**: Verify `.env.example` contains all required variables +3. **Documentation Accuracy**: Follow your README step-by-step +4. **Cross-Platform Testing**: Test on different operating systems if possible +5. **Mobile Testing**: Verify mobile responsiveness for web applications + +## Submission Process + +### 1. Create a Pull Request + +```bash +# Create a new branch +git checkout -b feature/{framework}-{usecase} + +# Add your files +git add community-maintained-examples/{framework}-{usecase}/ + +# Commit with descriptive message +git commit -m "Add {framework}-{usecase} example + +- Brief description of what it demonstrates +- Key features implemented +- Any notable technical details" + +# Push to your fork +git push origin feature/{framework}-{usecase} +``` + +### 2. Pull Request Template + +When creating your PR, use our standard template (automatically loaded) that includes: + +- Description of your example +- Type of integration/feature +- Framework and blockchain details +- Testing checklist +- Whether you used an existing Privy template as a base + +The template ensures all necessary information is provided for efficient review. + +### 3. Review Process + +Your PR will be reviewed for: + +- **Functionality**: Does the example work as described? +- **Documentation**: Is the setup process clear and complete? +- **Code Quality**: Does it follow best practices? +- **Security**: Are there any security concerns? +- **Consistency**: Does it match our repository patterns? + +## Feature Requests + +Have an idea for a new example? + +1. **Check existing examples** to avoid duplicates +2. **Open an issue** with: + - Clear description of the proposed example + - Target framework and blockchain + - Key features to demonstrate + - Potential use cases + - Why it would be valuable to the community + +## Resources + +### Privy Documentation + +- [Privy Docs](https://docs.privy.io) +- [React SDK Reference](https://docs.privy.io/reference/react-auth) +- [Node SDK Reference](https://docs.privy.io/reference/server-auth) + +### Development Tools + +- [Privy Dashboard](https://dashboard.privy.io) +- [Canonical Starters](./) + +## Questions? + +- **Slack**: [Privy Developer Slack](https://privy.io/slack) + +---