Skip to main content

​
Welcome Contributors!

Flow Browser is an open-source project, and we welcome contributions from the community. Whether you’re fixing bugs, adding features, or improving documentation, your help is appreciated!

​
Getting Started

1

Fork and Clone

Fork the repository on GitHub and clone your fork:
git clone https://github.com/YOUR-USERNAME/flow-browser.git
cd flow-browser
2

Set Up Development Environment

Follow the development setup guide to install prerequisites and dependencies:
bun install
bun dev:watch
3

Create a Branch

Create a new branch for your work:
git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • refactor/ - Code refactoring

​
Development Workflow

​
Making Changes

1

Write Code

Make your changes following the project’s coding standards:
  • Use TypeScript for type safety
  • Follow existing code patterns
  • Keep functions small and focused
  • Add comments for complex logic
2

Test Your Changes

Manually test your changes:
bun dev:watch
Flow Browser doesn’t have automated tests. Thoroughly test your changes manually.
3

Run Quality Checks

Before committing, run all quality checks:
bun run lint
bun run typecheck
bun run format
Fix all linting and type errors. The CI will fail if these checks don’t pass.

​
Code Quality Standards

  • Enable strict type checking
  • Avoid any types
  • Use proper interfaces and types
  • Export types for reusability
// Good
interface BookmarkData {
  title: string;
  url: string;
  favicon?: string;
}

// Bad
const bookmark: any = { /* ... */ };
  • Use functional components with hooks
  • Keep components small and focused
  • Extract reusable logic into custom hooks
  • Use proper prop types
interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

export function Button({ label, onClick, disabled }: ButtonProps) {
  return (
    <button onClick={onClick} disabled={disabled}>
      {label}
    </button>
  );
}
Use motion/react, not framer-motion.
import { motion } from 'motion/react';

<motion.div
  initial={{ opacity: 0 }}
  animate={{ opacity: 1 }}
>
  Content
</motion.div>
  • Use TailwindCSS utility classes
  • Follow existing styling patterns
  • Use CSS variables for theming
  • Keep styles consistent across components
<div className="flex items-center gap-2 rounded-lg bg-gray-100 px-4 py-2">
  Content
</div>

​
Commit Guidelines

​
Commit Message Format

Use clear, descriptive commit messages: 
type: brief description

Detailed explanation of what changed and why.
Types:
  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • style: - Formatting, missing semicolons, etc.
  • perf: - Performance improvements
  • test: - Adding or updating tests
  • chore: - Maintenance tasks
Examples: 
feat: add bookmark folders support

Implemented nested folder structure for organizing bookmarks.
Added UI for creating, renaming, and deleting folders.

fix: prevent tab crash when loading large PDFs

Added memory limit check before loading PDF documents.
Fixes #123

​
Submitting Changes

1

Commit Your Changes

git add .
git commit -m "feat: add your feature"
2

Push to Your Fork

git push origin feature/your-feature-name
3

Create Pull Request

  1. Go to your fork on GitHub
  2. Click “Pull Request”
  3. Select your branch
  4. Fill out the PR template with:
    • Description of changes
    • Related issues (if any)
    • Screenshots (for UI changes)
    • Testing performed
4

Code Review

  • Respond to reviewer feedback
  • Make requested changes
  • Keep the PR focused and small
  • Be patient and respectful

​
Pull Request Checklist

  • Code follows project style guidelines
  • bun lint passes without errors
  • bun typecheck passes without errors
  • bun format has been run
  • Changes have been manually tested
  • No console errors or warnings
  • Commit messages are clear and descriptive
  • Tested on multiple screen sizes
  • Dark/light mode both work
  • Animations are smooth
  • Accessibility considered
  • Screenshots included in PR
  • Feature is complete and functional
  • Edge cases handled
  • Error states handled gracefully
  • User feedback provided (toasts, etc.)
  • Documentation updated if needed

​
Reporting Issues

​
Bug Reports

When reporting bugs, include:
  • Description: What happened vs. what should happen
  • Steps to reproduce: Detailed steps to recreate the bug
  • Environment: OS, Flow Browser version, Electron version
  • Screenshots: If applicable
  • Console logs: Any error messages

​
Feature Requests

Submit feature requests at: flowbrowser.userjot.com Include:
  • Description: What feature you want
  • Use case: Why it’s needed
  • Examples: How it might work

​
Communication

GitHub Issues

For bug reports and feature discussions

Pull Requests

For code contributions and reviews

User Feedback

flowbrowser.userjot.com

Documentation

This documentation site

​
Project-Specific Notes

​
Castlabs Electron Fork

Flow Browser uses a Castlabs fork of Electron for Widevine DRM support. This is normal and intentional.
In package.json: 
"electron": "https://github.com/castlabs/electron-releases#v40.1.0+wvcus"
Don’t change this unless updating the Electron version.

​
Database Changes

When modifying the SQLite schema:
  1. Update Drizzle ORM schema files
  2. Generate migrations: bun run drizzle-kit generate
  3. Test migrations with existing data
  4. Document breaking changes

​
Extension API Changes

When modifying extension support:
  • Test with popular Chrome extensions
  • Ensure backward compatibility
  • Document API changes

​
Code of Conduct

Be respectful, inclusive, and professional:
  • Welcome newcomers
  • Provide constructive feedback
  • Focus on the code, not the person
  • Respect different perspectives
  • Help others learn and grow

​
License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 License.
Flow Browser is licensed under the GNU General Public License v3.0 (GPL-3.0). All contributions are subject to this license.

​
Recognition

Contributors are recognized in:
  • GitHub contributors page
  • Release notes (for significant contributions)
  • CONTRIBUTORS.md file (if exists)

​
Need Help?

If you’re stuck or have questions:
  1. Check the documentation
  2. Search existing GitHub issues
  3. Ask in a new GitHub issue
  4. Review the architecture guide

​
Next Steps

Development Setup

Set up your development environment

Architecture

Understand the codebase structure

Building

Learn how to build the application

GitHub Repository

Visit the Flow Browser repository

Build docs developers (and LLMs) love

Get started for freeTalk to us