FAQ

Setup & Installation

The launch script says Node.js is not installed

Download and install Node.js 18 or newer from nodejs.org. After installing, double-click the launch script again. On macOS, the script can install Node.js through Homebrew automatically if Homebrew is available.

The wizard won’t start

Open a terminal and type node --version to confirm Node.js 18+ is installed. The launch script handles dependencies automatically on first run. If something went wrong during that step, try running npm install manually in the Beacon folder, then try the launch script again.

The live preview is blank

Give it a few seconds. The preview server takes a moment to start up the first time. If it stays blank, check the terminal window for error messages.

Can I run the wizard without the launch scripts?

Yes. Open a terminal, navigate to the Beacon folder, and run:

npm install    # first time only
node setup/server.cjs

Then open http://localhost:3000 in your browser.

Content & Feeds

My feed cards aren’t showing content

Double-check the username, URL, or ID for each feed. The most common sticking points:

• YouTube requires a Channel ID (starts with UC), not a channel name or URL. Find yours at youtube.com/account_advanced.
• Substack feed URLs should end in /feed.
• Some feeds take a moment to load on the first request.

How often do feeds update?

Feed cards (YouTube, Substack, Medium, Podcast, Etsy, RSS) fetch fresh content every time someone visits your page. Publish something new and it appears on your Beacon within minutes. No rebuilding needed.

How often do tiles update?

It depends on the tile.

Live tiles fetch fresh data every time someone loads your page: Now Playing, Now Reading (Goodreads source), Letterboxd, GitHub, Chess.com, and Weather. Now Playing refreshes every 30 seconds while a visitor is on the page. The others update on each page load. Countdown updates in real time. No rebuilding needed when something on the source service changes.

Snapshot tiles capture data once and bake it into your built site: Now Reading (Hardcover source) and Steam. They don’t update on their own — re-open the wizard and click Refresh snapshot when you want fresh data, then rebuild and redeploy. See Tiles for details.

I don’t use Last.fm. Can Now Playing still work with Spotify, Tidal, or Apple Music?

Yes, through Last.fm. Both Spotify and Tidal officially support Last.fm scrobbling, so connect your accounts once and pick Last.fm as the source on the Now Playing tile. For Spotify, the connection lives in your Last.fm account settings under Applications → Spotify Scrobbling. For Tidal, it’s inside the Tidal app on desktop, web, or iOS (Tidal doesn’t offer scrobbling on Android).

Apple Music doesn’t ship native Last.fm support, but third-party scrobbler apps for macOS and iOS are easy to find. Pick one, connect it to your Last.fm account, and Apple Music listens will scrobble too.

Why isn’t my Now Reading or Steam tile updating?

Those tiles use snapshot mode, which captures your current book or game data when you click Refresh snapshot in the wizard and bakes it into your built site. They won’t update as you read or play.

To refresh: open the wizard, find the tile, click Refresh snapshot, then build and redeploy. The wizard shows a status line under each tile telling you when the snapshot was last captured.

One of my tiles is showing a profile link instead of live data — what happened?

That’s the fallback state. When a service-backed tile can’t fetch live data (revoked API key, expired token, outage, rate limit), it gracefully turns into a link to your profile on that service rather than showing an empty card. See Tiles → When a service is unavailable for the full behavior.

If you’re seeing it on your own site, re-run the wizard’s Verify step — it’ll surface authentication failures and re-cache fresh profile photos. Tiles also attempt one automatic recovery 90 seconds after falling back, so a brief outage may resolve itself if the visitor stays on the page.

Can I mix links and feeds in any order?

Yes. They all live in one list. Drag them into whatever order makes sense. Put a sponsored link between two feed cards, group all your feeds together, whatever works for your page.

Themes & Design

Can I use a font not in the dropdown?

Yes. The font picker has a custom input field. Type any Google Fonts name and it loads immediately. The preview updates so you can confirm it looks right.

What do the accent colors do?

Each tile and content card has its own accent color, picked from your palette: Brand, Hover, Accent, or Avatar. The accent controls that card’s visual styling: border glow, icon color, and labels. Varying accent colors across cards creates visual interest without looking random.

Can I use a photo or gradient as my background?

Yes. Under Brand Style → Background style, pick Gradient for a two-stop linear gradient (with optional gentle motion or grain texture), or Photo to upload a hero image. In photo mode, your hero and cards automatically get a frosted-glass treatment so text stays readable against the image. JPG, PNG, and WebP all work. See Brand Style for the full breakdown.

My cards look wrong against my background photo

Beacon picks a card tint direction automatically based on overall page brightness, but photos aren’t always uniformly bright or dark — so the auto-pick can occasionally feel off against a specific image. Open Brand Style → Card style and switch Card background from Auto to Dark or Light to force the direction.

I picked a light theme but the wizard looks wrong

The wizard’s chrome and your site’s theme are independent. The live preview on the right shows your actual site with whatever theme you chose in Brand Style. If you selected a light preset like Warm Earth or Minimal, your site will have a light background in the preview and when deployed.

The wizard chrome itself can be Light, Dark, or System (matches your OS). The toggle is in the bottom of the left menu — three small icons (sun, moon, monitor). If you’re designing a light-themed site, switching the wizard to Light mode keeps the chrome from competing with your preview.

The verification says my text contrast is too low

Your text color and background color are too similar, which means visitors won’t be able to read your page comfortably. Go to Brand Style and pick colors with more contrast. Dark text on a light background (or light text on a dark background) is the simplest fix.

Building & Deploying

The build failed

Check the output in the wizard for specific error messages. The usual causes:

• Required fields are missing for tiles or feeds you’ve added
• Run verification first to catch issues before building
• Try running npm install again to make sure dependencies are current

Can I preview the built site on my computer?

The live preview in the wizard (right side of the screen) shows exactly how your site will look once hosted. That’s the best way to preview.

Opening the dist/ folder directly in a browser won’t display styles correctly because the files use absolute paths. If you really want to preview the built output locally, run npx serve dist in a terminal.

Where do I upload the dist/ folder?

Any static hosting provider. The fastest option is Netlify Drop: drag your dist/ folder onto the page and you’re live. See the Hosting guide for all options.

How do I update my site after making changes?

Reopen the wizard (double-click the launch script), make your changes, click Build, and re-upload the dist/ folder to your host. On Netlify, drag the new folder to replace the old deployment. On git-based hosts, push and it redeploys automatically.

Do I need to keep the Beacon files after deploying?

Yes. Keep the entire Beacon folder on your computer. It contains your configuration and the wizard. You’ll need it any time you want to make changes and rebuild.

How do I move my Beacon to a new computer?

Use Backup & Restore. Export a .zip from the old computer, install Beacon fresh on the new one, and import the .zip in the new wizard. Your full configuration, photos, and credentials come with you.

Working in the Wizard

What do the small chips next to each section title mean?

Live status. Each section header carries a chip on the right that summarizes what you’ve configured there: “5 social links”, “Tracking enabled”, “Public”, “All defaults”, “No tiles yet”, and so on. They update as you make changes. They’re scannable at a glance — if a section’s chip says what you’d expect, you don’t need to scroll to it.

I clicked Remove by accident — can I get my [photo / tile / link] back?

For your avatar photo, yes. After you click Remove, a “Photo removed” overlay sits over the avatar slot for five seconds with an Undo button. Click it within that window and your photo comes back. After five seconds it’s gone for good and you’ll need to re-upload.

For tiles, social links, and content items, the trash icon doesn’t delete immediately — it turns the row into a confirmation prompt with Remove and Keep buttons. Default focus is on Keep, so pressing Enter accidentally won’t delete anything. Pressing Escape also cancels. You only commit to deletion when you actually click Remove.

Do I need to save my changes?

No. The wizard saves automatically on every keystroke and click. You’ll see a small “Saving…” → “Saved” indicator in the corner. There’s no manual save button and no draft mode.

Can I switch the wizard to light mode?

Yes. Three small icons in the bottom of the left menu (sun, moon, monitor) toggle between Light, Dark, and System. The choice persists per browser. This is independent of your site’s theme — the toggle only affects the wizard interface.

Privacy & Data

Does Beacon track my visitors?

No. There are no analytics, tracking scripts, or third-party data collection baked into your site. Beacon generates static HTML served directly to visitors. The only external requests come from content feeds that visitors’ browsers fetch (YouTube, Substack, etc.) and Google Fonts.

Where is my data stored?

On your computer, in the Beacon project folder. Nothing is sent to a server, cloud service, or database. You own everything.

Can I remove the “Build your own Beacon” footer link?

Yes. Go to Code in the wizard and uncheck the footer link toggle. It disappears on the next build.

Pricing & License

Is Beacon really a one-time purchase?

Yes. You pay once and own it. No subscription, no account, no login, no recurring fee. The product runs entirely on your computer.

Can I use Beacon for a client project?

Each purchase covers one site. If you’re building Beacon sites for multiple clients, each site needs its own license.

Do I get updates?

The product you download is complete and works indefinitely as-is. If future updates are released, existing customers get access.

Still Stuck?

If something isn’t covered here, reach out directly and I’ll help you sort it out.