Firebase + Express + PRPL Server = ❤️

Firebase + Express + PRPL Server.md

Note: this gist has some bugs that still need to be fixed.

In the meantime, take a look at this issue to know what this bugs are and how to fix them

Firebase + Express + PRPL Server

Simple step-by-step guide

1. Head over the Firebase Console and create your project

2. Install Firebase Command Line Tools:

   $ npm i -g firebase-tools

3. Log into your Firebase account from the CLI by running:

   $ firebase login

   If you can't access a local web browser for some reason, you can add the --no-localhost flag to the command above to have a link to open anywhere you want instead

4. Create a folder for your project, cd into it and then run:

   $ firebase init

   Firebase should ask you what features you want to use for this folder, check Functions and Hosting, then go on with the setup

5. Your directory structure should now look like this:

   $ ls -a
   ./             ../            .firebaserc    firebase.json  functions/     public/

6. Now we will be adding our own Express configuration to have more flexibility and add PRPL Server to our Firebase project. cd into the functions/ directory and run:

   $ npm i express

7. Open up index.js and replace its content with:

   const functions = require('firebase-functions');
   const express = require('express');
   
   const app = express();
   
   app.get('*', (req, res) => {
     res.send('Hello from Express + Firebase!');
   });
   
   exports.app = functions.https.onRequest(app);

   We are basically creating an Express app that responds with Hello from Express + Firebase! to any request. The important thing to notice here is the last line:

   exports.app = functions.https.onRequest(app);

   This line is telling to Firebase: "When there is a request to the app function, let our Express app handle that request"

8. This is not yet sufficient to make everything work correctly, as we didn't tell to our hosting that it should call the app function when it receives a request yet.

   Open up the firebase.json file in the base directory of your project and add (or edit if it already exists) the rewrites field inside the hosting field of the JSON, telling him to rewrite everything to our app function. My firebase.json looks like this at this point:

   {
     "hosting": {
       "public": "public",
       "ignore": [
         "firebase.json",
         "**/.*",
         "**/node_modules/**"
       ],
       "rewrites": [
         {
           "source": "**",
           "function": "app"
         }
       ]
     }
   }

9. Check out if everything works as expected by running:

   $ firebase serve --only functions,hosting

   This command will start a local server that emulates Firebase hosting and functions

   Open up something like localhost:5000/random-page and check if the server answers correctly, then try to open up simply localhost:5000. You will notice that opening the index will return a Firebase page. That's because our firebase.json is telling Firebase to use the public directory to serve static content. You can either remove the public property from your firebase.json to avoid this behavior, or change its value to a different directory (e.g. static). We are going to use the public directory as the base directory for our built PRPL project.

10. Now let's setup the PRPL Server. I'm going to use PWA Starter Kit as an example, since it is PRPL-ready.

    Clone/download the PWA Starter Kit repo and copy all of its content into the root of your Firebase project:

    $ cd ..
    $ git clone https://github.com/Polymer/pwa-starter-kit
    $ cd pwa-starter-kit
    $ rm -rf .git* server
    $ cp -R . ../<your project dir>
    $ cd ../<your project dir> 

11. Open gulpfile.js and find and replace all occurrencies of server/build with public

12. Run npm i in the root directory of your project and then run npm run build:prpl-server.

    You will need the Polymer CLI to run the command above. Install it by running npm i -g polymer-cli

13. You should now have a public/ directory in your root project directory, containing three different versions of the PWA (ES5, ES6 and ESM) and a polymer.json config, that can be used to configure PRPL Server

14. Install the prpl-server package by running the following command in your functions directory:

    $ npm i prpl-server

15. Now we only need to setup PRPL Server with Express, so let's add some new logic to our functions/index.js. Require prpl-server and ../public/polymer.json, and edit the app.get(*... to make it handled by PRPL Server. The final version of index.js should look like this:

    const functions = require('firebase-functions');
    const express = require('express');
    const prplServer = require('prpl-server');
    const prplConfig = require('../public/polymer.json');
    
    const app = express();
    
    app.get('*', prplServer.makeHandler('../public', prplConfig));
    
    exports.app = functions.https.onRequest(app);

16. firebase serve and open up localhost:5000 again. You should now see the PWA Starter Kit correctly served by PRPL Server, through Express, using Firebase!

17. If you want to deploy your project, you might want to ignore some non-needed files by adding them to the appropriate section in your firebase.json file. When you are done with your configuration, just run:

    $ firebase deploy --only functions,hosting

18. Done! You now have your awesome ultra modern PWA running on Firebase!