Skip to main content

​
Installation Guide

Better Home is built from source and loaded as an unpacked extension. This guide will walk you through the installation process for all supported browsers.

​
Prerequisites

This project uses Bun as the package manager. You’ll need to install it before proceeding.
Bun is a fast, all-in-one JavaScript runtime and package manager. It’s significantly faster than npm or yarn.
curl -fsSL https://bun.sh/install | bash
After installation, restart your terminal and verify with bun --version.

​
Build from Source

1

Clone the repository

git clone https://github.com/SatyamVyas04/better-home.git
cd better-home
2

Install dependencies

bun install
3

Build the extension

bun run build
The production build outputs to the dist/ folder. This is what you’ll load in your browser.

​
Install in Your Browser

Better Home is compatible with all Chromium-based browsers. Choose your browser below:
1

Open Chrome extensions

Navigate to chrome://extensions in your browser.
2

Enable Developer mode

Toggle Developer mode in the top-right corner.
3

Load the extension

Click Load unpacked and select the dist folder from your cloned repository.
4

Open a new tab

Open a new tab - welcome home!
When you first open a new tab, Chrome may display a warning about the changed new tab appearance. Select “Keep it” - this is the intended behavior for the extension.

​
Development Mode

If you’re developing or customizing Better Home, you can run a local dev server with hot reload: 
bun run dev
This starts a development server at localhost:5173 where you can preview your changes in real-time.
Hot reload works in the browser preview, but to test the full extension experience you must rebuild with bun run build and reload the extension in chrome://extensions after code changes.

​
Troubleshooting

​
Bun command not found

Your shell may not have reloaded the PATH after installing Bun. Solution:
  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

​
Extension not updating after changes

Chrome aggressively caches unpacked extensions. Solution:
  1. Go to chrome://extensions
  2. Click the refresh icon on the better-home card
  3. Open a fresh new tab
During active development, keep DevTools open on the new-tab page - it sometimes forces a reload.

​
New tab shows blank page or old content

This can happen when extension files are outdated or corrupted. Solution:
  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)

​
Path alias errors (“Cannot find module”)

This usually means @/ path aliases aren’t resolving correctly during development. Solution:
  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

​
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)
Solution:
  • 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-

​
Port 5173 already in use

Another process is using the default Vite port. Solution: 
# 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

​
Next Steps

Now that Better Home is installed, learn how to use its features:

Build docs developers (and LLMs) love

Get started for freeTalk to us