Epoch Buddy

A browser extension that converts epoch timestamps into human-readable dates (and vice-versa) -- from any web page selection or the extension popup.

Installation

• Chrome Web Store
• Firefox Add-ons

Features

• On-page selection: Select a 10 or 13 digit epoch on any website to see an inline conversion popup with one row per timezone you have configured.

  

• Epoch to Date: Paste or type an epoch and get a row per configured timezone (each with its UTC offset) plus Relative time. A dedicated clock button copies the current millisecond timestamp to your clipboard and populates the input field.

  

• Date to Epoch: Enter date/time using numeric fields with inline validation. Pick any of your configured timezones from the dropdown (Local, UTC, or any IANA zone). Time presets (Now, Start of Day, End of Day) sit alongside the time fields for quick access. Switch to ISO string mode to paste an ISO 8601 value (e.g. 2026-03-19T12:00:00.000Z); if the string has no offset, the fallback-timezone picker resolves it against any of your configured zones.

  

• Relative to Epoch: Enter a duration (ago / from now) and get Epoch plus per-configured-zone timestamps and Relative time. Overflow values are automatically normalized on blur (e.g. 90 minutes becomes 1 hour 30 minutes).

  

• Timezone settings (v1.6+): Open the gear icon in the header to add any IANA timezone, remove ones you do not need, and drag-and-drop to reorder. The configured list drives the on-page popup, all three converter tabs, history entries, and the ISO fallback-timezone picker.

• Analytics opt-out (v1.7+): Settings includes an Analytics toggle. Only anonymous event names and a random install ID are ever sent — never your conversion values, selected text, or page content. See the privacy policy for the full list.

• First-install welcome page (v1.8+): A one-time onboarding tab opens on a fresh install (or first update from an older version) with browser-specific pin-to-toolbar instructions and a quick tour of the popup features. Shown only once per install.

• Smart validation: All numeric fields enforce min/max ranges, show per-field error highlighting, and default to zero on blur for time fields (date fields require a value).

• History: Last 10 conversions with quick copy buttons and a clear button. Each entry expands to show per-timezone rows.

• Dark Mode: Supports dark mode in both the extension menu and the popup. A polished segmented theme picker appears in both the header and the Settings page.

  

• Timezone display: The extension popup header shows the current IANA timezone and UTC offset.

• Feedback (v1.5+): Optional footer with a 5-star flow — lower ratings can open your Google Form, higher ratings the Chrome or Firefox store review page (URLs wired at build time). The footer is pinned to the bottom of the popup; you can dismiss it locally until reinstall.

Quick start

npm install
npm run build          # one-shot build (default: Chrome/Edge manifest)

Browser-specific builds

The extension uses a single manifest.json. The build script patches it for the target browser:

npm run build              # build JS (manifest unchanged)
npm run build:chrome       # build JS + set manifest for Chrome/Edge
npm run build:firefox      # build JS + set manifest for Firefox

npm run watch              # watch mode (manifest unchanged)
npm run watch:chrome       # watch mode + set manifest for Chrome/Edge
npm run watch:firefox      # watch mode + set manifest for Firefox (restores on exit)

Load in browser (developer mode)

Chrome / Edge

1. Run npm run build or npm run build:chrome
2. Open chrome://extensions, enable Developer mode
3. Click Load unpacked and select the extension/ folder

Firefox

1. Run npm run build:firefox
2. Open about:debugging#/runtime/this-firefox
3. Click Load Temporary Add-on and select extension/manifest.json

Packaging for store submission

npm run pack:chrome    # --> dist/chrome.zip
npm run pack:firefox   # --> dist/firefox.zip (manifest patched automatically)
npm run pack           # build both zips

Pack commands always produce a clean zip for each browser regardless of the current manifest state.

Project structure

src/
  shared/            # Shared utilities (formatting, parsing, clipboard, theme, timezones, analytics)
  popup/main.js      # Extension popup entry point
  content/main.js    # Content script entry point
  background/main.js # Extension background service worker (analytics egress)
  demo/main.js       # GitHub Pages demo entry point
extension/           # Extension package (HTML, CSS, manifest + built JS)
docs/                # GitHub Pages website (HTML, CSS + built demo.js)
scripts/build.mjs    # Build, watch, and packaging script

Source code lives in src/. The build step bundles each entry point into self-contained IIFE files using esbuild.

Development

See Developer.md for the full development workflow.

Links

• Live demo
• GitHub