Firefly can teach you how—it's the friendly starter kit for designers and front-end devs who want to ship their own projects 🔥💪🚢

Firefly is a learner-focused modern web-app Javascript boilerplate and development guide based on Create React App and Firebase

Start building

or view source on Github

Making websites is hard.

Sure, writing HTML is pretty easy—but letting users log in, securely submit forms, and search your data is way harder. Most people who try just give up. I almost did.

Luckily, I found some tools that make things simpler. After months of combing through documentation (and plenty of mistakes), I made an empty "starter project" to speed up my own work. That's Firefly.

Philosophy

Firefly does away with a lot of the stuff that teams of professional engineers use to build large, high-volume, scalable applications. Instead, it's designed to help people without backend experience learn and build simple sites quickly.

It embraces modern javascript syntax, the NPM ecosystem, single-page front-end applications, serverless backends, schemaless databases, and 3rd-party APIs for hard things like authentication and search—all to keep the codebase small and easier to "reason about". Firebase has no server to monitor, no database instance to host, no REST API to build, no containers, no password salts, no migrations, and no real need to learn HTTP or SQL.

That said, we never go bleeding edge: all Firefly dependencies are used by large tech companies in production, are hugely popular in the community, and will likely be supported for years to come.

How it works

Firefly isn't a framework or library—it's just a boilerplate that you can copy when starting a new project.

When you first copy Firefly and start it up, you'll see an empty list of "posts" (imagine blog posts, or wiki pages). Users can read individual posts or search for posts. Once they log in, they can like posts or create and edit their own posts. You can play with a live Firefly demo at demo.getfirefly.org to see how it works.

To make the project your own, simply find-and-replace all the instaces of "Firefly" and "posts" to match your own project and data.

Let's take a closer look at the different parts of Firefly:

Views

Most of Firefly is built with React. React can feel weird at first—it looks funny, and it doesn't use normal HTML and CSS. Stick with it though—using components will feel like a revelation soon. Get started by reading the excellent official React guide.

Presentation views

The main UI of a firebase app is a bunch of simple React components in the /views folder. These are usually stateless, presentational components written in the simple functional React style. Think of them like templates in MVC--their job is basically just to show HTML.

Styles

Firefly uses styled-components to add style. These are React components written with CSS, and they live in the /styles folder. Think of them as a replacement for SASS or LESS files.

Routing

The router is the part of the app that shows different React components based on the browser URL. React has no built-in router, so we use the popular React Router. All our app's routes live in the Routes.js file.

Data

Instead of a datastore like Redux, in Firefly you directly query the using Firebase

The database

Firefly uses the NoSQL Firebase Firestore database for saving data. Firestore organizes your data into "collections" (kind of like SQL tables) which have "documents" (kind of like rows, or big blobs of JSON). You write to the Firebase database directly from the user's web browser (no server required). Before you go much further, you should read the Firebase Firestore Database Guide.

Firestore queries use javascript Promises to make async requests and error handling very simple. If you're not familiar with promises, learn a bit about how promises work.

Data providers

So how do you get your data into your views? Firefly comes with a bunch of "provider" react components in the /data folder to do just that--their responsibility is to listen for data from the database and pass it down to the views using the render prop pattern.

Many other React apps use something like Redux to keep their UI up-to-date when data changes, but many developers agree that Redux is overkill for a lot of simple apps, so Firefly just uses render methods and Firebase subscriptions.

Securing your data

Because any browser can write data directly into your database, you need some Firebase security rules to keep hackers from deleting data or viewing private stuff. Firefly comes with a default set of rules for posts that you can use can copy. This video does a great job explaining how these rules work.

Authentication

Firefly uses Firebase Authentication for logging users in.

Actions

OK, so now you know how Firefly shows UI with data from the database. But how do you make the app change when the user clicks something?

The answer in Firefly is "actions"—plain old javascript functions that live in the "actions" folder. When the user wants to add a post, for example, the "add post" view will call the "add post" action, which takes care of sending the new post to the database. When the database gets the new post, the data providers will automatically send it to the views so everything's always up-to-date.

Other stuff

Firefly uses Create React App to take care of transpiling, bundling, linting, and running tests. You don't have to write or manage any configuration for this to work, just run npm start.

The deployment scripts use Firebase hosting to host your app when you're ready to go live. Firebase hosting comes with HTTPS for free, and it's the same price as Google Cloud Platform object storage (cheap), and works well with the other Firebase services like backend functions and your database.

Getting Started

Quick start

  1. Clone the repo and install the packages with git clone https://github.com/sampl/firefly && cd firefly && npm install
  2. Remove `.example` from the names of your environment files with mv .firebaserc.example .firebaserc && mv .env.dev.example .env.dev && mv .env.stage.example .env.stage && mv .env.live.example .env.live
  3. Create firebase projects in the Firebase console and add keys to .firebaserc and the .env files
  4. For each project, enable Google auth, enable Firestore beta, and upgrade to the Blaze plan
  5. Start development with npm start and deploy with npm run live

Before you begin

You'll need git to use Firefly. If you don't already know how to use git, you can learn on Codecademy.

Download and install Node JS if you haven't already.

Run npm install -g firebase-tools to install the Firebase command line tools. After it installs, run firebase login. You only need to do this once per computer.

Creating your app

Get the code

Firefly is a boilerplate, so to start a new Firefly project, we just make a copy of Firefly.

  1. In your terminal, cd to the folder where you want your project to live
  2. Clone this repo by running git clone https://github.com/sampl/firefly
  3. Move "into" the folder you just created with cd firefly (you can also safely rename the firefly folder to the name of your project)
  4. Run npm install to install all the javascript packages Firefly needs

Connect to the database

Firefly projects only have one codebase, but use three Firebase projects. Each project has its own URL and its own separate copy of the database. This lets you develop and stage your app without affecting the live version.

  1. Go to the Firebase console and sign in with your Google account
  2. Create three new projects, and name them something like MyProject Dev, MyProject Stage, and MyProject LIVE

Now let's connect our databases to our app by adding their "keys" to our app's environment ("env") files. You should generally keep connection keys like this secret, so first we'll rename our environment files to keep them from getting committed into git (the new filenames are listed in .gitignore).

  1. First, rename .firebaserc.example to .firebaserc and replace the blank space next to "development" with the projectId from the Firebase website.
  2. Rename .env.dev.example to .env.dev, and do the same thing for the stage and live files. Replace the blank spaces in that file with the codes from the Firebase website too.
  3. Now back on the Firebase website, click "Add Firebase to your web app" for each new project
  4. You'll see a block of code with info like "project id" and "API key"—add these values to your firebaserc and your dev, stage and live env files.

Set up your Firebase projects

Before you can add any posts, you'll have to allow sign-in with Google. Firebase makes this very easy.

  1. Back in the Firebase console, click on "Authentication" in the sidebar on the left
  2. Click "Set up sign-in method"
  3. Click "Google", toggle the "Enable" switch, and hit "Save"

The Firebase database we're using, Firestore, is still in beta. You'll also have to enable Firestore for each of your projects on the Firebase website.

  1. In the Firebase console, click on "Database" in the sidebar on the left
  2. Under "Cloud Firestore Beta", click "Get Started"
  3. Choose "Start in test mode" and hit "Enable"

Firebase Cloud Functions only work if your project is on a paid plan, so upgrade your Firebase project to "Blaze". This should still be free to use (unless you get a lot of traffic).

This isn't necessary to start Firefly, but you'll eventually need to Create a Service Account before you run the scripts in the Firefly "scripts" folder.

Other services

Firefly comes with a search powered by Algolia. To enable search, create an account, configure your functions credentials. See index.js for full instructions.

There's also a simple Stripe integration for creating subscriptions and charging users. If you're not asking users for money, you can get rid of the files with "subscription" in the name. If you are, add your Stripe keys to the .env files and your Firebase functions config.

Firefly also comes with Google Analytics for tracking page views and Sentry for monitoring errors. To use them, just create an account and project on each site, then add your tracking codes to your .env files.

As you work

Develop

Start your app with npm start. You should see a basic web app in your browser! 😎

Try logging in, then make sure you can create, like, edit, and delete posts.

Now go back to your text editor and try editing some files. When you save, the changes should automatically appear in the browser.

Now is probably a good time to CTRL-F for all the instances of "Firefly" in the codebase and rename them to the name of your project. You should also probably do this for "post", too.

Deploy

Firefly is insecure by default. Before going live, secure your app by writing rules in database.rules.json

You can deploy your project to your test stage URL by running npm run stage.

When it's time to go live, run npm run live!

Next Steps

That's it!

Remember that learning this stuff is always hard—for everyone. Take small bites and keep at it. Eventually you'll build something amazing.

🎉 🎉 🎉




Did I miss something? Was something confusing? I'd love to hear from you; submit an issue or pull request.