README

Humblebee backend

This is our backend boilerplate, made for serverless backends. It uses Serverless Framework and also has a CRUD API baseplate for Google Cloud Functions.

Commands

yarn deploy:ssr: Deploy SSR build to server (assumes Google Cloud Platform/Firebase Hosting)
yarn build:ssr: Output a build optimized for server-side rendering (read below for implementation details)
yarn deploy:serverless: Deploy with Serverless — yarn deploy:ssr: Deploy SSR site with Google Cloud Functions

Stack

Babel 7
ESLint
Prettier
Serverless Framework

Server-side rendering

We can create fairly flat, universal web apps with the boilerplate. There are a few considerations and changes that need to be accounted for when building for SSR, since the boilerplate assumes client-side rendering (CSR) in a PWA format.

Note: It is recommended, for ease of development and reduction of headaches, that an early call is made on whether the application should be SSR or CSR.

The SSR implementation uses a streaming type of implementation which is very fast, but has certain issues with modules that are run in a ”standard” way, like React Helmet’s staticRender() that is done after the render.

Considerations and changes for SSR

Webpack configuration

Aliasing React to preact or preact-compat will currently break an SSR implementation. Make sure to un-alias in webpack.common.js when building for SSR.

Unistore

If you are aliasing/unaliasing React, make sure that any instances of Unistore and its components reference a React-specific package, rather than Preact versions.

Route splitting and react-loadable

This needs to be disabled for SSR. A solution may be to use react-universal instead.

Uploading and hosting

Our implementation assumes Google Cloud Functions and Firebase Hosting. This should be easily transferable to other vendors. Or just use the Serverless framework.

If you go with Google, make sure to setup your Google account to access the right stuff.

Page content and headers

When using SSR, and especially when we are using a cloud function, we need to send the page content and headers down. The functions/index.js file includes template sections for headers, beginning and end of what is normally the index.html file.

React Helmet and page headers/title

It is recommended to do title and header handling in the server.js file instead of in React Helmet. Since react-helmet affects window it will break SSR.

Remove React Helmet from the project or at least deactivate it
Use the Express section of server.js to set data based on the route, for example

app.get('**', (req, res) => {
    const url = req.params[0].toLowerCase();
    let title = '';

    if (url === '/career') {
        title = 'Humblebee – Career';
    }

    if (url === '/ourapproach') {
        title = 'Humblebee – Our Approach';
    } else {
        title = 'Humblebee';
    }

    renderApplication(title, res);
});

Gotchas and things that probably won’t work right now

In SSR, our custom path rewriting code may or may not work perfectly. If you see unexpected 404s or similar, see if any path rewriting is messing up stuff.
Don’t use window or document since these don’t work in a server-side environment
As above, React Helmet won’t work without hassling with it – for now, use the server.js file to set headers instead, and spare yourself from fighting with Helmet
Paths don’t work out-of-the-box when building the server-side bundle
When deploying to a server, in practical terms only the server.js file gets uploaded. You need to host all other files elsewhere

Serverless

Creating a keyfile

From https://serverless.com/framework/docs/providers/google/guide/credentials/

Get credentials

You need to create credentials Serverless can use to create resources in your Project.

Go to the Google Cloud API Manager and select "Credentials" on the left.
Click on "Create credentials" and select "Service account key".
Select "New service account" in the "Service account" dropdown.
Enter a name for your "Service account name" (e.g. "serverless-framework").
Select "Project" --> "Owner" as the "Role".
The "Key type" should be "JSON".
Click on "Create" to create your private key.
That's your so called keyfile which should be downloaded on your machine.
Save the keyfile somewhere secure. We recommend making a folder in your root folder and putting it there. Like this, ~/.gcloud/keyfile.json. You can change the file name from keyfile to anything. Remember the path you saved it to.

@humblebee/humblebee-backend

Usage no npm install needed!