Skip to main content

​
Welcome Contributors!

Contributions, issues, and feature requests are welcome! This guide will help you get started with contributing to Better Home.

​
Getting Started

1

Fork the repository

Fork the Better Home repository to your GitHub account.
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/better-home.git
cd better-home
3

Install dependencies

bun install
4

Create a feature branch

git checkout -b feat/amazing-feature

​
Development Workflow

​
1. Make Your Changes

Develop your feature or fix: 
bun run dev
  • Make incremental, logical commits
  • Test your changes thoroughly in the browser
  • Ensure the extension builds successfully

​
2. Code Style

Better Home uses Biome for linting and formatting, configured with the Ultracite preset for consistent code style. 
bun run lint
The pre-commit hook automatically runs ultracite fix on staged files before each commit, ensuring code style consistency.

​
3. Type Checking

Ensure your code passes TypeScript type checking: 
bun x tsc --noEmit
Or run the full build: 
bun run build

​
4. Commit Your Changes

Better Home uses Conventional Commits enforced by commitlint.

​
Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

​
Commit Types

A new feature for the user
git commit -m "feat: add context menu to todo items"
git commit -m "feat(calendar): add hold-to-clear functionality"
A bug fix
git commit -m "fix: resolve todo list spacing issue"
git commit -m "fix(backup): improve restore functionality"
Documentation changes only
git commit -m "docs: update installation instructions"
git commit -m "docs(readme): clarify browser compatibility"
Code style changes (formatting, missing semicolons, etc.)
git commit -m "style: format with Biome"
Code change that neither fixes a bug nor adds a feature
git commit -m "refactor: simplify calendar layout logic"
git commit -m "refactor(hooks): extract storage sync logic"
Performance improvement
git commit -m "perf: optimize calendar render performance"
Adding or updating tests
git commit -m "test: add tests for todo-utils"
Changes to build process, dependencies, or tooling
git commit -m "chore: update dependencies"
git commit -m "chore(deps): upgrade motion to v12"
The commit-msg hook automatically validates your commit messages. Invalid commits will be rejected.

​
Example Commits

# Good commits
git commit -m "feat: add drag-to-reorder for todo items"
git commit -m "fix: prevent duplicate quick links"
git commit -m "docs: add troubleshooting section to README"
git commit -m "refactor(calendar): extract month grid logic"

# Bad commits (will be rejected)
git commit -m "updated stuff"           # Missing type
git commit -m "Fix: bug fix"            # Wrong capitalization
git commit -m "feat:add feature"        # Missing space after colon

​
5. Push Your Changes

Push your feature branch to your fork: 
git push origin feat/amazing-feature

​
6. Open a Pull Request

1

Create the PR

Go to the Better Home repository and click “New Pull Request”.
2

Write a descriptive title

Use conventional commit format for the PR title:
feat: add drag-to-reorder for todo items
3

Provide context in the description

  • Summarize what changed and why
  • Link related issues (e.g., “Closes #123”)
  • Include screenshots for UI changes
  • Note any breaking changes
4

Ensure checks pass

  • All commits follow conventional commit format
  • Code passes linting (bun run lint)
  • Project builds successfully (bun run build)

​
Code Style Guidelines

​
TypeScript

  • Use strict types - no any unless absolutely necessary
  • Prefer interfaces for object shapes
  • Use type inference when possible
  • Export types from src/types/ directory
// Good
interface TodoItem {
  id: string;
  text: string;
  completed: boolean;
}

function addTodo(todo: TodoItem): void {
  // ...
}

// Avoid
function addTodo(todo: any) {
  // ...
}

​
React

  • Functional components only - no class components
  • Use hooks for state and effects
  • Extract custom hooks for reusable logic
  • Keep components focused - single responsibility
// Good
export function TodoList() {
  const [todos, setTodos] = useLocalStorage<TodoItem[]>("better-home-todos", []);
  
  return (
    <div>
      {todos.map((todo) => (
        <TodoItem key={todo.id} todo={todo} />
      ))}
    </div>
  );
}

​
Styling

  • Use Tailwind utilities - avoid custom CSS
  • Use design system variables for colors
  • Responsive-first - mobile to desktop
  • Dark mode support - test both themes
// Good
<div className="flex flex-col gap-2 rounded-lg bg-card p-4 shadow-sm">
  <h2 className="font-semibold text-foreground">Tasks</h2>
</div>

// Avoid inline styles
<div style={{ padding: "16px", backgroundColor: "white" }}>

​
File Organization

  • Group by feature - related files together
  • Use index exports sparingly
  • Keep utilities pure - no side effects in /lib
  • Type files in /types - shared type definitions

​
Git Hooks

Better Home uses Husky for Git hooks:

​
Pre-commit Hook

Automatically runs before each commit:
  1. Checks for staged files
  2. Runs ultracite fix on staged files
  3. Re-stages formatted files
  4. Preserves unstaged changes via stash
Set ULTRACITE_UNSAFE=1 environment variable to enable unsafe fixes during commit.

​
Commit-msg Hook

Validates commit messages:
  1. Checks conventional commit format
  2. Enforces allowed types (feat, fix, docs, etc.)
  3. Rejects invalid commits with helpful error messages

​
Testing Checklist

Before submitting a PR, ensure:
  • Project builds without errors: bun run build
  • No TypeScript errors: bun x tsc --noEmit
  • Extension loads in browser successfully
  • No console errors in DevTools

​
Questions or Issues?

If you have questions or run into issues:

​
License

By contributing, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to Better Home! Your efforts help make this extension better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us