Electron Browser (starter)

A minimal tabbed web browser built with Electron. All icons are placeholders generated by a script so you can swap in your own artwork without touching any code.

New in v1.1.0 — Extension support! Surf FED can now load Chrome-style extensions (Manifest V2/V3). See EXTENSIONS.md for the full guide, or click the 🧩 button in the toolbar to open the Extensions Manager. Three built-in example extensions are included (Ad Blocker, Dark Reader, Page Info).

Run it

npm install
npm start

Project layout

electron-browser/
├── main.js              # Electron main process (creates the window)
├── preload.js            # Safe bridge between main and renderer
├── index.html             # Browser chrome (toolbar, tab bar, webviews)
├── renderer.js             # Tab management, navigation, address bar logic
├── styles.css               # Browser UI styling
├── assets/
│   └── icons/
│       ├── icon.png              # 512x512 master app icon (placeholder)
│       ├── icon-16x16.png ... icon-1024x1024.png   # sized app icons
│       └── ui/
│           ├── back.png
│           ├── forward.png
│           ├── reload.png
│           ├── home.png
│           ├── new-tab.png
│           └── close.png
├── build/
│   └── icon.png            # source icon electron-builder uses for packaging
├── scripts/
│   ├── make_placeholder_icons.py   # regenerates assets/icons/*
│   └── make_ui_icons.py             # regenerates assets/icons/ui/*
└── package.json
└── extensions/                 # Extension support (new)
    ├── builtin/                # Extensions that ship with the browser
    │   ├── ad-blocker/         # declarativeNetRequest ad/tracker blocker
    │   ├── dark-reader/        # content-script dark theme for pages
    │   ├── fed-gram/           # Instagram image downloader (toolbar popup)
    │   └── page-info/          # popup that shows page metadata
    └── user/                   # (empty) drop your own extensions here (dev)

Extensions

Surf FED supports loading unpacked Chrome extensions (Manifest V2 and V3). Click the 🧩 button in the toolbar to open the Extensions Manager, where you can enable/disable, load, and remove extensions. Full instructions for adding your own extensions are in EXTENSIONS.md.

Replacing the placeholder icons

Nothing else needs to change — just overwrite files in place, keeping the same filenames and (ideally) the same pixel sizes:

• App icon (taskbar/dock/window icon): replace the files in assets/icons/ — icon.png and each icon-<size>x<size>.png.

• Toolbar icons: replace the files in assets/icons/ui/ — back.png, forward.png, reload.png, home.png, new-tab.png, close.png. Keep them at 24x24 (or update the #toolbar img size in styles.css if you want them bigger/smaller).

• Packaged app icon (.ico for Windows, .icns for macOS): the placeholders only include build/icon.png. Before running npm run dist, generate the platform-specific formats from your final artwork, e.g. with the electron-icon-builder package:

  npx electron-icon-builder --input=build/icon.png --output=build --flatten

  That produces build/icon.ico and build/icon.icns alongside the PNG, which package.json's build config already points to.

If you ever want a fresh set of placeholders back (e.g. to check sizes), run:

npm run icons                 # regenerates assets/icons/*
python3 scripts/make_ui_icons.py   # regenerates assets/icons/ui/*

Building distributables

npm run dist

Uses electron-builder with the config already set in package.json (build field).

Pushing this to GitHub

cd electron-browser
git init
git add .
git commit -m "Initial commit: Electron browser starter with placeholder icons"
git branch -M main
git remote add origin https://github.com/<your-username>/<your-repo>.git
git push -u origin main

Notes

• The address bar accepts URLs or search terms (falls back to a Google search if it doesn't look like a URL).
• Each tab is a separate <webview> element with its own back/forward history.
• This is a starting point, not a security-hardened browser — before shipping anything real, review Electron's security guidelines.