Skip to main content

Hacker News Pro​

Welcome to Hacker News Pro, a browser extension designed for developers to create their own unique, fully-customized Hacker News interfaces using Handlebars and CSS. The built-in code editor makes theme creation a breeze and changes may be seen in real-time. Explore a collection of premade themes that may be cloned and edited to get up and running quickly.

Available for chrome logo Chrome and firefox logo Firefox​

Watch the demo video on youtube logo YouTube​

Table of contents​

  1. Installation
  2. Getting started
  3. Theming
  4. Template reference
  5. Local development
  6. Creating and publishing versions

Installation​

Start by heading over to the Hacker News Pro page on either the Chrome web store or Firefox add-ons and install the extension. Once installed, be sure to pin it to your toolbar so you can start using the browser popup.

Getting started​

At this point, you should have installed the extension and pinned it to your toolbar. Click the Hacker News Pro icon to open the browser popup. You should see the Themes page along with a list of premade themes. Now, head over to the Hacker News homepage: https://news.ycombinator.com.

Notice anything different? What you're seeing is the result of the selected theme in the Hacker News Pro browser popup. Open the popup again and click through the different premade theme options. You'll notice the layout and styling change in real-time as you select a different theme.

Do some exploring in other areas of the popup and once you're ready, check out the Theming section below to start making your own.

Theming​

Theming lies at the core of Hacker News Pro, enabling you to write a personalized Hacker News experience by defining your own HTML and CSS. Themes are made up of three fundamental elements: Views, Components, and Styles.

For your very first theme, we recommend cloning a premade theme while learning your way around. Click the Clone button beside any premade theme and a copy will be made and added to your Custom themes list. Click the Edit button beside the new theme to enter the theme editor and review the next sections to learn about the different configurations.

Views​

Views correspond to specific Hacker News page types and fall into three categories:

  • Lists: Pages that display various types of items, such as stories or jobs. For example, the homepage or https://news.ycombinator.com/newcomments.
  • Items: Pages that show detailed information about a single item, like the comments page for a story. Items can belong to one of four types: story, comment, job, or poll.
  • Other: Any page that doesn't fit the List or Item category. For instance, the comment reply or submission pages.

Components​

Themes often require the use of templates across multiple views. Components, defined using Handlebars' Partials syntax, come in handy here. Give a component a name, like "Header," which can then be injected into other templates using {{> header}}. Refer to the Handlebars partials guide for more details.

Styles​

A well-rounded theme encompasses its unique style. When crafting your theme, several methods are available for defining styles:

  • Custom CSS: Write your own custom CSS to tailor the theme to your liking.
  • Bootstrap: Hacker News Pro ships with Bootstrap which makes it easy to add personalized styles without needing to write extensive custom CSS.
  • Material Icons: Add a special touch to your theme using Google's Material icons.

Template reference​

See the full reference documentation here or read below for a high-level overview.

Context​

Templates in Hacker News Pro are written using Handlebars. As you navigate Hacker News pages, the extension works quietly in the background, scraping page contents and transforming them into an object internally known as the page's "context." You can explore the comprehensive types reference for the context object here.

When you're just starting, consider enabling "Developer mode" on the extension's Options page. This mode prints the context object to the console each time Hacker News Pro re-renders the page, helping you quickly grasp what's available to your templates without frequent trips to the documentation.

Handlebars helpers​

In addition to the context object, a number of Handlebars helpers are available to your templates. Check out our documentation for more details.

Web components​

Refer to the web components documentation to get more information about custom elements such as <hnp-interaction>.

Local development​

Requirements​

Install​

This project uses Yarn workspaces to manage dependencies. The various packages can be found in the packages directory and they all have their own package.json. When dependencies are installed, a node_modules directory gets created at the project root. If you need to add a dependency to a particular package, use the workspace command like so: yarn workspace @hnp/content add lodash.

Installing is as easy as running the following commands:

$ git clone https://github.com/dan-lovelace/hacker-news-pro.git
$ cd hacker-news-pro
$ yarn

Build​

Once a build is complete, its assets can be located in the dist directory at the project root. Keep this in mind when adding the unpacked version to your browser for testing. The following build commands are available:

CommandDescription
yarn startCreates a Manifest v3 build and starts file watchers on all packages+
yarn build 2Creates a build using Manifest v2
yarn build 3Creates a build using Manifest v3

[+] If you'd instead like to develop using v2, you'll need to copy the contents of assets/manifest-v2.json into packages/content/public/manifest.json and run a clean build. Be sure to remove the $schema property after doing so.

Add unpacked extension​

After starting or building, the extension's distribution is located in the dist directory at the root of the project. Add the unpacked assets to your browser of choice using the guides below. For now, Manifest v3 builds are only supported by Chrome.

Chrome: https://developer.chrome.com/docs/extensions/mv3/getstarted/#unpacked

Firefox: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension#installing

Tips​

Clearing storage​

It can be helpful when making code changes to delete all storage items and start from scratch. To do that, inspect the background script in the browser's extension UI and run the following command in the console:

chrome.storage.local.get((result) => {
  Object.keys(result).forEach((key) => chrome.storage.local.remove(key));
});

⚠️ This will delete any custom themes you've created so be sure to back them up first!

Creating and publishing versions​

To create and package a new version for publishing:

  1. Increment the version in package.json - Use Semantic Versioning standards.
  2. Run yarn package <manifest version> - Target either Manifest version 2 or 3 (i.e. yarn package 3).
  3. Inspect the output zip file in the versions directory to make sure everything looks right and that the file size has not ballooned unexpectedly.

Log in to either the Chrome Web Store (Manifest v3) or Firefox Addon Hub (Manifest v2), upload the new version and submit for review.

When complete, create a new release in GitHub with a tag that matches the new version (i.e. v0.0.1). Highlight changes under a "What's new" heading as seen in previous releases and include any bug fixes separately.