Dosu Logo
Home
Documents
How to contribute Read Frog
How to contribute Read Frog
Type
Document
Status
Published
Created
Sep 18, 2025
Updated
Mar 21, 2026
Updated by
Dosu Bot

Read Frog welcomes contributions in several forms: promoting the project, reporting issues or feedback, and contributing code. All contribution instructions are documented in the README and the official Contribution Guide.

Ways to contribute:

  • Share Read Frog with others.
  • Report issues or feedback using GitHub issues.
  • Submit code improvements or new features.

Getting started with code contributions:

  1. Repository Setup
    Fork the repository and clone your fork.

git clone https://github.com//read-frog.git
cd read-frog


2. **Database Initialization** 
   Set up a local Postgres database. Supabase is recommended for local development. 
   - Follow the [Supabase local development guide](https://supabase.com/docs/guides/local-development?queryGroups=package-manager&package-manager=brew).
   - After setup, copy the database connection URL (`DB URL`) into `packages/db/.env`:
     ```
     DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
     NODE_ENV=development
     ```
   - Initialize the schema:
     ```bash
     pnpm db:migrate
     ```

3. **Environment Configuration** 
   Create `apps/website/.env.local` and set required environment variables. 
   Example:

BETTER_AUTH_SECRET=<SOME_BETTER_AUTH_SECRET>
BETTER_AUTH_URL=http://localhost:8888
GOOGLE_CLIENT_ID=<SOME_GOOGLE_CLIENT_ID>
GOOGLE_CLIENT_SECRET=<SOME_GOOGLE_CLIENT_SECRET>
DATABASE_URL=postgresql://postgres@....0.0.1:54322/postgres

You can copy the example file:
```bash
cp apps/website/.env.example apps/website/.env.local

Extension Build Environment Variables
When building zip releases of the extension (WXT_ZIP_MODE=true), additional environment variables are required:

  • WXT_POSTHOG_API_KEY: PostHog API key for analytics tracking
  • WXT_POSTHOG_HOST: PostHog host URL for analytics tracking
  • WXT_POSTHOG_TEST_UUID (optional): Custom test UUID for development analytics. In development mode, if not set or contains only whitespace, analytics will automatically use a default test UUID (00000000-0000-0000-0000-000000000001). This helps contributors test analytics without needing to configure a custom test UUID. Contributors can override this default by explicitly setting WXT_POSTHOG_TEST_UUID to their own UUID.

These variables enable anonymous analytics tracking (opt-in by default on Chromium-based browsers, opt-out on Firefox) to help improve user experience.

Note on API key validation: WXT's production build normally validates that API keys matching the pattern WXT_*_API_KEY are not bundled into production builds. However, WXT_POSTHOG_API_KEY is explicitly whitelisted in ALLOWED_BUNDLED_API_KEYS in wxt.config.ts and is permitted to be bundled without causing validation errors.

CI/CD: In GitHub Actions workflows, these environment variables can be sourced from either Secrets or Variables using fallback syntax (e.g., ${{ secrets.WXT_POSTHOG_API_KEY || vars.WXT_POSTHOG_API_KEY }}).

  1. Start Development Server

    pnpm dev

    Access the site at http://localhost:8888/.

  2. Extension Development
    Configure browser paths in apps/extension/web-ext.config.ts if needed. For persistent Chrome profiles, use:

    export default defineWebExtConfig({
  chromiumArgs: ["--user-data-dir=./.wxt/chrome-data"],
});

    For Chrome 137+, use Chrome for Testing.

Development Tips

Working with Configuration Migration Scripts#

When adding a new config schema version, you need to create a migration script to handle upgrading user configurations. The migration system uses automatic script discovery:

  • Create migration script files in src/utils/config/migration-scripts/ following the naming convention: v{XXX}-to-v{YYY}.ts (e.g., v063-to-v064.ts).
  • Export a migrate function from your script that takes the old config format and returns the new format.
  • The system automatically discovers and loads migration scripts using Vite's import.meta.glob feature — you don't need to manually import them in migration.ts.

File organization:

  • src/utils/config/storage.ts — Local config storage functions
  • src/utils/config/sync.ts — Config syncing functions (getLastSyncedConfigAndMeta, setLastSyncConfigAndMeta)
  • src/utils/config/migration.ts — Auto-discovers migration scripts from the migration-scripts/ directory

This auto-discovery approach simplifies adding new migrations; just create the properly named file with a migrate export, and the system will handle the rest.

Code Style#

The project uses ESLint to enforce code style conventions. Contributors should follow these guidelines:

  • Use double quotes for strings in TypeScript, JavaScript, and TSX files. ESLint is configured to enforce double quotes (e.g., "hello" not 'hello').
  • Import ordering: ESLint enforces consistent import ordering using perfectionist/sort-imports with custom groups:
    • Setup imports (like @/utils/zod-config) must appear at the top of the import list, before all other imports.
    • The "setup" custom group is defined in the ESLint configuration for side-effect imports that configure libraries before they're used (e.g., imports that set global configuration).
    • This is enforced automatically by the perfectionist/sort-imports rule and is particularly important for the Zod configuration import (@/utils/zod-config), which prevents CSP violations in MV3 extensions by disabling Zod's JIT mode.
    • The rule will flag incorrectly ordered imports during linting.
    • Example of correct import order: 
      import "@/utils/zod-config" // Setup import - must be first
import { browser, defineBackground } from "#imports"
import { WEBSITE_URL } from "@/utils/constants/url"
import { logger } from "@/utils/logger"
  • Run pnpm lint to check your code for style issues before submitting.
  • Most style issues can be fixed automatically with pnpm lint:fix.

Note: The project switched to double quotes in PR #1004. You may see single quotes in older code that hasn't been updated yet.

Using npx with pnpm Node.js Management#

We're using pnpm's built-in Node.js version management (introduced in pnpm 10.14). You may encounter EBADDEVENGINES errors when running npx commands. There are two solutions:

Solution 1: Use pnpm dlx or pnpx instead of npx

# Instead of npx
npx some-package@latest

# Use pnpm dlx
pnpm dlx some-package@latest

# Or use pnpx (alias for pnpm dlx)
pnpx some-package@latest

Solution 2: Align Node.js version with pnpm

When it's not convenient to replace npx (e.g., for user-scoped MCP installations in Claude Code), align your Node.js version:

# Install and use the required Node.js version globally
pnpm env use --global 22.18.0

Submitting code changes:

  • Create a new branch:

git checkout -b feat/your-feature

or#

git checkout -b fix/your-bug

or#

git checkout -b docs/your-docs-change

- Add a changeset before opening a pull request: 
  ```bash
  pnpm changeset
  • Follow the Conventional Commits specification for commit messages.
  • Open a pull request and complete the checklist: test changes locally, update documentation if needed, follow code style, and ensure no breakage of existing functionality.

Special instructions for contributors in mainland China:
Set the environment variable SKIP_FREE_API=true when pushing code to skip Google API tests, which may fail due to access restrictions:

SKIP_FREE_API=true git push

PR Review and Merging Expectations

If you are new to contributing, maintainers will help you adapt to the development process and code style. Your first PRs are generally not rejected for quality issues, but you should:

  • Start with small issues, such as those labeled "Good First Issue" in the repository. Small, simple PRs help you learn smoothly.
  • Ensure your PR passes all GitHub Actions and local tests.

Common reasons a PR may not be reviewed or merged:

  • The PR is overly complex before you are familiar with the codebase, requiring many changes.
  • The code contains many basic errors, such as unused code snippets, excessive repetition, or arbitrary naming.
  • AI-assisted code is encouraged, but you must carefully review AI-generated code to avoid low-quality, unmaintainable, or over-engineered submissions.
  • If maintainers provide modification suggestions multiple times and you do not follow them or do not address the root issues, your PR may not be merged.

Reporting issues and requesting features:

For full details, refer to the Contribution Guide and project documentation.