HNPWA API

Deploy a CDN cached Hacker News API to your own Firebase Hosting Domain. All in two lines of code 😎

Heavily inspired/guided by cheeaun's node-hnapi.

Install

npm i hnpwa-api

Basic usage

Import and use in your functions/index.js file:

const hnapi = require('hnpwa-api');
exports.api = hnapi.trigger({
   useCors: false, // defaults to false
   useCompression: true, // defaults to true
   browserCacheExpiry: 300, // in seconds (5 min is the default)
   cdnCacheExpiry: 600, // in seconds (10 min is the default)
   staleWhileRevalidate: 120, // Allow CDN to serve stale data 120 seconds after cdnCacheExpiry
   firebaseAppName: 'hnpwa-api', // defaults to hnpwa-api
   offline: false, // Serves offline data if data is downloaded (See Global Module guide)
   routerPath: 'api', // provide a serving path ex: mysite.com/api/news.json
});

Why?

Two reasons: latency and same domain.

Latency

This API is designed for Firebase Hosting which is backed by a global CDN. Responses are cached in edges around the globe which results in low latency.

Latency test: CDN cached vs. in memory cache

Same domain

With HTTP/2 you reuse one connection per domain. This package allows you to easily deploy your own HNAPI on your own domain for one nice TCP connection.

Setup Tutorial

1. Install the Firebase CLI:

npm i -g firebase-tools

2. Initialize Cloud Functions for Firebase

firebase init functions

3. Install hnpwa-api

Inside of the functions folder, install hnpwa-api:

cd functions
npm i hnpwa-api --save # not needed on npm 5 but you get what im sayin

4. Add HNAPI endpoint

Open functions/index.js, and configure your HNAPI.

const hnapi = require('hnpwa-api');
exports.api = hnapi.trigger({
   useCors: false, // defaults to false
   useCompression: true, // defaults to true
   browserCacheExpiry: 300, // in seconds (5 min is the default)
   cdnCacheExpiry: 600, // in seconds (10 min is the default)
   staleWhileRevalidate: 120, // Allow CDN to serve stale data 120 seconds after cdnCacheExpiry
   firebaseAppName: 'hnpwa-api', // defaults to hnpwa-api
   offline: false, // Serves offline data if data is downloaded (See Global Module guide)
   routerPath: 'api', // provide a serving path ex: mysite.com/api/news.json
});

5. Initialize Firebase Hosting

firebase init hosting

6. Create a redirect for the API function

Open firebase.json and create a redirect to call out to the HNAPI:

{
  "hosting": {
    "public": "public",
    "rewrites": [{
       "source": "**",
       "function": "api"
    }]
  }
}

7. Deploy!

firebase deploy

That's all there is to it. Feel free to file an issue if you find a bug.

Global Module use

The hnpwa-api module can either be downloaded as a global module or used from the node_modules/.bin/hnpwa-api directory.

Serving offline

The global module provides the ability to save data locally for offline serving. If you're developing on a bus, airplane, or someother place without a connection you'll need this.

# 1) Save to node_modules/hnpwa-api/offline (~10mb)
node_modules/.bin/hnpwa-api --save
# 2) Now serve offline
node_modules/.bin/hnpwa-api --serve --offline

Non-Firebase setup

Not using Cloud Functions or Firebase Hosting as your backend? No problem. This library still has you covered.

const hnapi = require('hnpwa-api');
// does not include any middleware like the trigger() call above
const expressApp = hnapi.app(); // optionally provide a firebase app name
expressApp.listen(3000, () => console.log('Listening all on my own!'));

This returns an express app instance with the expected HN API endpoints. No middleware is attached unlike the trigger(config) method.

Why do I need a Firebase App Name if I'm not using Firebase Hosting?

You may not use Firebase as your backend, but Hacker News does. The base HN API is backed by the Firebase Database. This library uses the Firebase Node SDK to retrieve data and coalesce it into a single UI friendly response.

Contribute!?

git clone https://github.com/davideast/hnpwa-api/
npm i
npm run build # single build of the project
npm run watch # typescript (tsc) watcher
npm run serve # local node debug server
npm run pack # local tarball for test installations

leonsenft/hnpwa-api