Bookmarklet Guide - homepage.dev

Complete guide for installing and using the homepage.dev bookmarklet to save webpages with one click.

🔖 What is the Bookmarklet?

The homepage.dev bookmarklet is a one-click browser tool that lets you save any webpage to your homepage dashboard instantly. It captures:

Page title
URL
Description (from meta tags)
Featured image (Open Graph/Twitter)
Favicon

🚀 Quick Installation

For Development (localhost:3017)

Start your dev server:
```
pnpm dev
```
Visit the bookmarklet page:
```
http://localhost:3017/tools/bookmarklet
```
Install the bookmarklet:
- Desktop: Drag the blue "Add to homepage.dev" button to your bookmarks bar
- Mobile: Tap the button to copy, then save as a bookmark
Test it:
- Visit any webpage
- Click the bookmarklet in your bookmarks bar
- A popup window opens with the add bookmark form

For Production (homepage.dev)

Visit the bookmarklet page:
```
https://homepage.dev/tools/bookmarklet
```
Install the bookmarklet:
- Desktop: Drag the blue "Add to homepage.dev" button to your bookmarks bar
- Mobile: Tap the button to copy, then save as a bookmark
Test it:
- Visit any webpage
- Click the bookmarklet in your bookmarks bar
- A popup window opens with the add bookmark form

🖥️ Browser-Specific Instructions

Google Chrome

Make sure your bookmarks bar is visible:
- Press Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (Mac)
- Or go to: Menu → Bookmarks → Show bookmarks bar
Visit the bookmarklet page (see URLs above)
Drag the "Add to homepage.dev" button to your bookmarks bar
Alternative: Right-click the button and select "Bookmark this link"

Mozilla Firefox

Make sure your bookmarks toolbar is visible:
- Right-click the top toolbar area
- Check "Bookmarks Toolbar"
Visit the bookmarklet page (see URLs above)
Drag the "Add to homepage.dev" button to your bookmarks toolbar
Alternative: Right-click the button and select "Bookmark this link"

Safari

Enable the bookmarks bar:
- Go to View → Show Bookmarks Bar
- Or press Cmd+Shift+B
Visit the bookmarklet page (see URLs above)
Drag the "Add to homepage.dev" button to your bookmarks bar

Note: Safari may require you to enable JavaScript bookmarklets in Preferences → Security

Microsoft Edge

Make sure your favorites bar is visible:
- Press Ctrl+Shift+B (Windows) or Cmd+Shift+B (Mac)
- Or go to: Menu → Favorites → Show favorites bar
Visit the bookmarklet page (see URLs above)
Drag the "Add to homepage.dev" button to your favorites bar
Alternative: Right-click the button and select "Add to favorites"

Mobile Browsers (iOS Safari / Chrome)

Visit the bookmarklet page (see URLs above)
Tap the "Add to homepage.dev" button to copy the bookmarklet code
iOS Safari:
- Tap the Share button
- Select "Add Bookmark"
- Paste the copied code into the URL field
- Name it "Add to homepage.dev"
- Save
Mobile Chrome:
- Tap the three-dot menu (⋮)
- Select "Bookmarks"
- Choose "Add bookmark"
- Paste the copied code into the URL field
- Name it "Add to homepage.dev"
- Save

📖 How to Use

Adding a Bookmark

Navigate to any webpage you want to save
Click the bookmarklet in your bookmarks bar
A popup window opens with the add bookmark form pre-filled:
- Title (from page title)
- URL (current page)
- Description (from meta tags)
- Image (Open Graph or Twitter image)
- Favicon (site icon)
Choose destination:
- Select which homepage, page, and tab to save to
- Add tags or notes (optional)
Click "Add Bookmark" to save
Done! The popup closes and the bookmark is saved

Size: 600x630 pixels (optimized for all browsers)
Position: Centered on your screen
Behavior: Closes automatically after saving
Blocked popups: If your browser blocks popups, you'll see an alert to enable them

🔧 Technical Details

Environment Detection

The bookmarklet automatically detects your environment:

Local development: Uses http://localhost:3017
Production: Uses https://homepage.dev

No manual configuration needed!

Data Captured

The bookmarklet extracts:

{
  title: document.title,
  url: window.location.href,
  description: <meta name="description"> or <meta property="og:description">,
  image: <meta property="og:image"> or <meta name="twitter:image">,
  favicon: <link rel="icon"> or <link rel="shortcut icon">
}

Browser Compatibility

Tested and working on:

✅ Google Chrome (latest)
✅ Mozilla Firefox (latest)
✅ Safari (latest)
✅ Microsoft Edge (latest)
✅ Opera (latest)
✅ Brave (latest)

Mobile support:

✅ iOS Safari
✅ Chrome Mobile (Android/iOS)
✅ Firefox Mobile
⚠️ Limited support on older mobile browsers

Version Information

Current Version: 3.0
Format: javascript:(function(){ ... })()
Size: ~2KB minified
Dependencies: None (vanilla JavaScript)

🐛 Troubleshooting

Problem: Browser blocks the popup window

Solution:

Allow popups for homepage.dev in your browser settings
Chrome: Settings → Privacy and security → Site Settings → Popups
Firefox: Options → Privacy & Security → Permissions → Block pop-up windows
Safari: Preferences → Websites → Pop-up Windows

Bookmarklet Doesn't Work

Problem: Nothing happens when clicking the bookmarklet

Solutions:

Check JavaScript: Make sure JavaScript is enabled in your browser
Reinstall: Delete the old bookmarklet and install a fresh copy
Check Console: Open browser DevTools (F12) and check for errors
Try Manual Copy: Use the "Copy Code" button and manually save as bookmark

Wrong Environment

Problem: Dev bookmarklet points to production (or vice versa)

Solution:

Delete the existing bookmarklet
Visit the correct bookmarklet page:
- Dev: http://localhost:3017/tools/bookmarklet
- Prod: https://homepage.dev/tools/bookmarklet
Reinstall with drag-and-drop

Missing Data

Problem: Page title, description, or image not captured

Explanation: Not all websites include proper meta tags. The bookmarklet extracts available data only.

Workaround: Manually edit the bookmark fields after saving.

Mobile Installation Issues

Problem: Can't drag on mobile devices

Solution:

Tap the bookmarklet button to copy
Manually create a new bookmark
Paste the copied code into the URL field
Name it "Add to homepage.dev"

🔐 Security & Privacy

What the Bookmarklet Does

✅ Extracts public page metadata
✅ Opens a popup to your homepage.dev dashboard
✅ Runs only when you click it
❌ Does NOT track your browsing
❌ Does NOT send data to third parties
❌ Does NOT run automatically

Code Transparency

The full bookmarklet source code is available at:

/apps/homepage-web/lib/bookmarklet.ts (development version)
/apps/homepage-web/app/tools/bookmarklet/page.tsx (UI page)

You can inspect the code before installation.

Data Privacy

Page data is sent only to your homepage.dev account
Uses HTTPS in production
No tracking or analytics in the bookmarklet
You control all saved bookmarks

📝 Developer Notes

Modifying the Bookmarklet

To customize the bookmarklet:

Edit source code:
```
apps/homepage-web/lib/bookmarklet.ts
```

Test locally:

pnpm dev
# Visit http://localhost:3017/tools/bookmarklet

Deploy changes:
```
pnpm build
# Deploy to production
```

Environment Configuration

The bookmarklet automatically detects environment:

const getBaseUrl = () => {
  if (typeof window !== "undefined") {
    const hostname = window.location.hostname
    if (hostname === "localhost" || hostname.includes("localhost")) {
      return "http://localhost:3017"
    }
  }
  return "https://homepage.dev"
}

Adjust popup size per browser:

const CONFIG = {
  popup: {
    default: { width: 600, height: 630 },
    firefox: { height: 650 },
    safari: { height: 640 },
    opera: { width: 620, height: 670 }
  }
}

🎯 Best Practices

For Users

Organize bookmarks bar: Create a dedicated "Tools" folder for bookmarklets
Test on various sites: Try the bookmarklet on different types of websites
Backup bookmarklets: Export your browser bookmarks regularly
Check for updates: Reinstall if functionality changes

For Developers

Keep it minimal: Bookmarklet code should be <5KB
Test all browsers: Chrome, Firefox, Safari, Edge, Opera
Handle errors gracefully: Always include try-catch blocks
Version tracking: Include version number in metadata
Document changes: Update this guide when modifying functionality

📞 Support

Issues or Questions?

🐛 Bug Reports: Open an issue in the repository
💬 Questions: Check existing documentation first
🆘 Help: Contact the development team

Main README - Project overview
Architecture Documentation - Technical details
Development Guide - Build and deployment

Last Updated: January 2025 Version: 3.0 Status: Active Development

On this page