better-home

an.overview.mp4

A minimal, delightful new-tab replacement for Chromium-based browsers.
Tasks · Quick Links · Mood Calendar - everything you need, nothing you don't.

---

Table of Contents

• Features
• Installation
  • Prerequisites
  • From Source
  • Compatible Browsers
    • Chrome
    • Edge
    • Brave
  • Development Mode
• Customization Notes
• Troubleshooting
• Tech Stack
• Contributing
• License
• Author

---

Features

Widget	Description
Tasks	A lightweight to-do list that remembers your items across sessions. Add, check-off, and delete tasks in a snap.
Quick Links	One-click bookmarks with auto-fetched favicons. Save your most-visited sites and jump to them instantly.
Mood Calendar	Track how you feel every day of 2026 with a beautiful, color-coded calendar. Supports quadrimester and full-year views with smooth Motion animations, optional day-number toggle, and inline notes.
Responsive Layout	Works seamlessly from ultrawide monitors to small laptops.
Customizable	Enable or disable any widget via the extension popup - make it your home.
Undo / Redo + Session Restore	Local changes save instantly. Use Ctrl+Z / Ctrl+Shift+Z for in-session undo/redo, then restore a whole previous editing session from history after reopening a new tab.
Backup & Restore	Keep manual JSON exports/restores, plus daily file backups and opportunistic file sync on page leave when changes were made.

---

Installation

Prerequisites

This project uses Bun as the package manager. If you don't have it installed:

macOS / Linux / WSL:

curl -fsSL https://bun.sh/install | bash

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"

Or via npm (if you have Node.js):

npm install -g bun

Tip

After installation, restart your terminal and verify with bun --version.

From Source (Development)

# Clone the repository
git clone https://github.com/SatyamVyas04/better-home.git
cd better-home

# Install dependencies
bun install

# Build the extension
bun run build

Note

The production build outputs to the dist/ folder.

Compatible Browsers

This extension is compatible with Chromium-based browsers, including Chrome, Edge, and Brave. Follow the steps below for your browser.

Chrome

1. Navigate to chrome://extensions
2. Enable Developer mode (toggle in the top-right corner)
3. Click Load unpacked
4. Select the dist folder
5. Open a new tab - welcome home!

Edge

1. Navigate to edge://extensions
2. Enable Developer mode (toggle in the bottom-left corner)
3. Click Load unpacked
4. Select the dist folder
5. Open a new tab - welcome home!

Brave

1. Navigate to brave://extensions
2. Enable Developer mode (toggle in the top-right corner)
3. Click Load unpacked
4. Select the dist folder
5. Open a new tab - welcome home!

Customization Notes

• Chrome/Brave Warning: When you first open a new tab after installing, Chrome/Brave may display a warning about the changed new tab appearance. Select "Keep it" as this is the intended behavior for the extension.

Development Mode

Spin up a local dev server with hot reload:

bun run dev

Warning

Hot reload works in the browser preview (localhost:5173), but to test the full extension experience you must rebuild and reload the extension after code changes.

---

Troubleshooting

Below are common issues you might encounter while developing with Vite + React + TypeScript - and how to fix them.

"Cannot find module" or path alias errors

This usually means @/ path aliases aren't resolving correctly.

Fix:

1. Ensure vite.config.ts contains the alias:

   resolve: {
     alias: {
       "@": path.resolve(__dirname, "./src"),
     },
   },

2. Confirm tsconfig.json mirrors the alias:

   "paths": {
     "@/*": ["./src/*"]
   }

3. Restart the dev server.

TypeScript build errors (tsc)

If bun run build fails with type errors:

# Run type-check only to see all issues
bunx tsc --noEmit

• Check for missing types - install @types/... packages as needed.
• Ensure strict mode settings in tsconfig.json match your code expectations.

Vite HMR not working / stale cache

Try clearing the cache and restarting:

rm -rf node_modules/.vite
bun run dev

If issues persist, delete node_modules entirely and reinstall:

rm -rf node_modules bun.lockb
bun install

Motion / Framer-motion import errors

This project uses motion (v11). If you see bundler errors about missing exports:

# Remove conflicting packages and reinstall motion
bun remove framer-motion
bun add motion@11

Then verify imports use:

import { motion, AnimatePresence } from "motion/react";

Extension not updating after changes

Chrome aggressively caches unpacked extensions.

Steps:

1. Go to chrome://extensions
2. Click the refresh icon on the better-home card
3. Open a fresh new tab

[!TIP] During active development, keep DevTools open on the new-tab page - it sometimes forces a reload.

Bun command not found after installation

Your shell may not have reloaded the PATH.

Fix:

1. Close and reopen your terminal completely.
2. If still not working, manually add Bun to your PATH:
   • macOS/Linux: Add export BUN_INSTALL="$HOME/.bun" and export PATH="$BUN_INSTALL/bin:$PATH" to your ~/.bashrc or ~/.zshrc.
   • Windows: Ensure %USERPROFILE%\.bun\bin is in your system PATH.
3. Verify with bun --version.

Port 5173 already in use

Another process is using the default Vite port.

Fix:

# Find and kill the process (Linux/macOS)
lsof -ti:5173 | xargs kill -9

# Or run Vite on a different port
bun run dev -- --port 3000

New tab shows blank page or old content

This can happen when the extension files are outdated or corrupted.

Fix:

1. Rebuild the project: bun run build
2. Go to chrome://extensions
3. Remove the existing better-home extension
4. Re-load it by clicking Load unpacked and selecting the fresh dist folder
5. Hard-refresh any open new-tab pages with Ctrl+Shift+R (or Cmd+Shift+R on macOS)

localStorage data not persisting

Extension storage can behave differently in certain scenarios.

Possible causes:

• Running the extension in Incognito mode (storage is cleared on close)
• Browser privacy settings blocking local storage
• Extension was reinstalled (clears extension-specific storage)

Fix:

• Ensure you're not in Incognito/Private mode
• Check chrome://settings/content/cookies - ensure "Block third-party cookies" isn't affecting extensions
• Use the Backup & Restore feature in the extension popup to save and restore your data
• Your data lives in localStorage under keys prefixed with better-home-

---

Tech Stack

Technology	Purpose
React 19	UI framework
TypeScript 5.9	Type safety
Vite 7	Lightning-fast bundler
Tailwind CSS 4	Utility-first styling
shadcn/ui	Accessible, beautiful components
Motion	Smooth animations
Tabler Icons	Crisp iconography
Bun	Ultra-fast package manager & runtime
Biome	Linting & formatting (via Ultracite preset)

---

Contributing

Contributions, issues, and feature requests are welcome!

1. Fork this repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Commit your changes: git commit -m "feat: add amazing feature"
4. Push to your branch: git push origin feat/amazing-feature
5. Open a Pull Request

Note

Please run bun run lint and bun run build before submitting to ensure your code passes all checks.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Author

Satyam Vyas · LinkedIn · GitHub · X