Skip to main content

​
Prerequisites

Better Home uses Bun as its package manager and runtime. Ensure you have Bun installed before proceeding. 
curl -fsSL https://bun.sh/install | bash
After installation, restart your terminal and verify with bun --version.

​
Clone and Install

1

Clone the repository

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

Install dependencies

bun install

​
Development Server

Start the development server with hot module replacement: 
bun run dev
This launches a local dev server at http://localhost:5173 with hot reload for rapid development.
Hot reload works in the browser preview, but to test the full extension experience you must rebuild and reload the extension after code changes.

​
Build for Production

Build the extension for production: 
bun run build
This command:
  1. Runs TypeScript type checking (tsc -b)
  2. Bundles the extension using Vite
  3. Outputs production-ready files to the dist/ folder

​
Load Extension in Browser

After building, load the extension in your Chromium-based browser:
  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!
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.

​
Testing Changes

During development:
  1. Make your code changes
  2. Rebuild the extension: 
    bun run build
  3. Go to your browser’s extensions page (e.g., chrome://extensions)
  4. Click the refresh icon on the better-home card
  5. Open a fresh new tab to see your changes
Keep DevTools open on the new-tab page during active development - it sometimes forces a reload automatically.

​
Additional Commands

​
Type Checking

Run TypeScript type checking without building: 
bun x tsc --noEmit

​
Linting

Check code style with Biome: 
bun run lint

​
Auto-fix Issues

Automatically fix linting issues: 
bun run fix
For unsafe fixes (use with caution): 
bun run fix:unsafe

​
Preview Build

Preview the production build locally: 
bun run preview

​
Common Issues

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 to ~/.bashrc or ~/.zshrc: 
      export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
    • Windows: Ensure %USERPROFILE%\.bun\bin is in your system PATH
  3. Verify with bun --version
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
This usually means @/ path aliases aren’t resolving correctly.Fix:
  1. Verify vite.config.ts contains: 
    resolve: {
  alias: {
    "@": path.resolve(__dirname, "./src"),
  },
},
  2. Confirm tsconfig.json mirrors the alias: 
    "paths": {
  "@/*": ["./src/*"]
}
  3. Restart the dev server
Chrome aggressively caches unpacked extensions.Steps:
  1. Go to your browser’s extensions page (e.g., chrome://extensions)
  2. Click the refresh icon on the better-home card
  3. Open a fresh new tab
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

Build docs developers (and LLMs) love

Get started for freeTalk to us