generator-react-firebase v2.1.0-alpha

generator-react-firebase

Yeoman generator for starting projects using React and Firebase (Redux optional)

Installation

Install Yeoman and generator-react-firebase using npm (we assume you have pre-installed node.js):

npm install -g yo generator-react-firebase

Getting Started

1. Create a project folder and enter it: mkdir myProject && cd myProject
2. Generate project: yo react-firebase (project will be named after current folder)
3. Start application by running npm start

Project will default to being named with the name of the folder that it is generated within (in this case myProject)

Whats Next

1. Checkout and understand src/config.js. This was generated for you for your local development environment, but is is ignored from git tracking (within .gitignore). You can have different settings within this file based on environment or if multiple developers are running the same code.
2. Tryout the Sub Generators
3. Tryout Firestore (you can generate a new project with yes as the answer to Do you want to use Firestore). Things work mostly the same, but it runs through redux-firestore.

Features

• firebase-functions v1 (including support within function sub-generator)
• React v16.3
• Material-UI v1 application styling including Navbar
• Full Authentication (through Email, Google or Github)
• Login/Signup Pages with input validation
• Route protection (only view certain pages when logged in)
• Account Page
• Automatic Build/Deploy config for multiple CI Providers including:
  • Gitlab (uses pipelines)
  • Travis

Uses

• react - Rendering + Components
• react-router - Routing (including async route loading)
• material-ui - Google Material Styling React Components (with option to opt out of Version 1)
• eslint - Linting (also implements prettier)
• webpack-dashboard - Improve CLI experience for Webpack

When opting into redux

• redux - Client Side state optional
• react-redux-firebase - Easily Persist results of Firebase queries to redux state
• redux-auth-wrapper - Easily create HOCs for route/component protection based on auth state
• redux-form - Form input validation + state
• redux-form-material-ui - Material UI components that work nicely with redux-form

Generated Project

Project outputted from generator has a README explaining the full structure and details specific to settings you choose. The following scripts are included:

View the example application README for more details.

Production

Build code before deployment by running npm run build. There are multiple options below for types of deployment, if you are unsure, checkout the Firebase section.

Deployment

Firebase

1. Login to Firebase (or Signup if you don't have an account) and create a new project
2. Install cli: npm i -g firebase-tools
3. Choose to go to a either the CI section(suggested) or the Manual section

CI

If opting into Travis-CI, config is included within travis.yml that uses firebase-ci to simplify the CI deployment process. All that is required is providing authentication with Firebase:

1. Select yes to question Would to include config for Travis CI? when generating
2. Select Firebase under deploy options
3. Login: firebase login:ci to generate an authentication token (will be used to give Travis-CI rights to deploy on your behalf)
4. Set FIREBASE_TOKEN environment variable within Travis-CI environment
5. Run a build on Travis-CI
6. To deploy to different Firebase instances for different branches (i.e. prod), change ci settings within .firebaserc

Settings for each environment can be provided through the .firebaserc file.

For more options on CI settings checkout the firebase-ci docs

Manual

1. Run firebase:login
2. Initialize project with firebase init then answer:

• What file should be used for Database Rules? -> database.rules.json
• What do you want to use as your public directory? -> build
• Configure as a single-page app (rewrite all urls to /index.html)? -> Yes
• What Firebase project do you want to associate as default? -> your Firebase project name

1. Build Project: npm run build
2. Confirm Firebase config by running locally: firebase serve (make sure you run npm run build first)
3. Deploy to firebase: firebase deploy

AWS S3

Selecting AWS S3 from the deploy options when running the generator adds deploy configs in .travis.yml.

1. Select yes to question Would to include config for Travis CI? when generating
2. Select AWS under deploy options
3. Get your AWS Key and Secret from the AWS Console Credentials page
4. Set the following environment vars within the Travis-CI repo settings page:

• AWS_KEY - Your AWS key
• AWS_SECRET - Your AWS secret
• S3_BUCKET - Your S3 Bucket

Heroku

Selecting Heroku from the deploy options when running the generator adds a Procfile. If you choose yes when offered travis, as deploy configs will be included in .travis.yml for out of the box deployment.

1. Select yes to question Would to include config for Travis CI? when generating
2. Select Heroku under deploy options
3. Enable Repo on Travis-CI Account
4. Get API Key from Heroku Dashboard
5. Create a new App (this name will be used in travis env var)
6. Set the following environment vars within the Travis-CI repo settings page:

• HEROKU_KEY - Your Heroku API key
• HEROKU_APP - Your Heroku App name

Sub generators

Sub generators are included to help speed up the application building process. You can run a sub-generator by calling yo react-firebase:<name of sub-generator> <param1>.

Example: To call the component sub-generator with "SomeThing" as the first parameter write: yo react-firebase:component SomeThing

Path Argument

Another argument can be passed to sub generators (unless otherwise noted) to provide the base path in which you would like to run the generator (starts from src). For example: yo react-firebase:component Car routes/Project runs the component generator within the Project route folder meaning that the component will be added to routes/Project/components instead of the top level src/components folder.

Function

Generates a Cloud Function allowing the user to specify trigger type (from HTTPS, Firestore, RTDB, Auth, or Storage)

A component is best for things that will be reused in multiple places. Our example

command

yo react-firebase:function uppercaser

result

/functions
--/uppercaser
----index.js

For firebase-functions <v1.0.0:

/functions/uppercaser/index.js:

import * as functions from 'firebase-functions'
import * as admin from 'firebase-admin'
import { to } from 'utils/async'


/**
 * @param  {functions.Event} event - Function event
 * @return {Promise}
 */
async function uppercaserEvent(event) {
  const eventData = event.data.val()
  const params = event.params
  const ref = admin.database().ref('responses')
  const [writeErr, response] = await to(ref.push(eventData))
  if (writeErr) {
    console.error('Error writing response:', writeErr.message || writeErr)
    throw writeErr
  }
  return response
}

/**
 * @name uppercaser
 * Cloud Function triggered by Real Time Database Event
 * @type {functions.CloudFunction}
 */
export default functions.database
  .ref('/users/{userId}')
  .onUpdate(uppercaserEvent)

For firebase-functions >=v1.0.0:

/functions/uppercaser/index.js:

import * as functions from 'firebase-functions'
import * as admin from 'firebase-admin'
import { to } from 'utils/async'

/**
 * @param  {functions.Event} event - Function event
 * @return {Promise}
 */
async function uppercaserEvent(change, context) {
  // const { params, auth, timestamp } = context
  // const { before, after } = change
  const ref = admin.database().ref('responses')
  const [writeErr, response] = await to(ref.push({ hello: 'world' }))
  if (writeErr) {
    console.error('Error writing response:', writeErr.message || writeErr)
    throw writeErr
  }
  return response
}

/**
 * @name uppercaser
 * Cloud Function triggered by Real Time Database Event
 * @type {functions.CloudFunction}
 */
export default functions.database
  .ref('/users/{userId}')
  .onUpdate(uppercaserEvent)

Note: This sub-generator does not support the Path Argument (functions are already placed within a folder matching their name).

Component

Generates a React component along with an option matching style file (either Javascript or SCSS) and places it within /components.

A component is best for things that will be reused in multiple places. Our example

command

yo react-firebase:component Car

result

/app
--/components
----/Car
------index.js
------Car.enhancer.js // optional
------Car.styles.js // optional (Localized MUI Styling)
------Car.js
------Car.scss // option (SCSS File)

/app/components/Car.js:

import React from 'react'
import PropTypes from 'prop-types'
import classes from './Car.scss'

export const Car = ({ car }) => (
  <div className={classes.container}>
    <span>Car Component</span>
    <pre>{JSON.stringify(car, null, 2)}</pre>
  </div>
)

export default Car

NOTE: Option to use Javascript file for styles is only offered if @material-ui/core is included in package.json

Form

Generates a Redux Form wrapped React component along with a matching scss file and places it within /components.

command

yo react-firebase:form Car

or

yo react-firebase:form CarForm

result

/app
--/components
----/CarForm
------index.js
------CarForm.enhancer.js
------CarForm.js
------CarForm.scss

/app/components/CarForm.js:

import React from 'react'
import PropTypes from 'prop-types'
import classes from './Car.scss'

export const CarForm = ({ car }) => (
  <div className={classes.container}>
    <span>CarForm Component</span>
    <pre>{JSON.stringify(car, null, 2)}</pre>
  </div>
)

export default CarForm

Enhancer

Generates an enhancer for a react component. Also includes an index file that wraps the component in the enhancer.

command

yo react-firebase:enhancer Project

result

/app
--/components
----/Project
------index.js
------Project.enhancer.js

Route

Generates a React component along with a matching component (which has an scss file, an enhancer, and its own index file).

command

yo react-firebase:route Project

result

/app
--/routes
----/Project
------index.js
------components
--------ProjectPage
----------index.js
----------Project.enhancer.js // optional
----------Project.js
----------Project.scss

Module

Generates a React component along with a matching component (which has an scss file, an enhancer, and its own index file).

command

yo react-firebase:module notification

result

/app
--/modules
----/notification
------components
------actions.js
------actionTypes.js
------index.js
------reducer.js

Note: This sub-generator does not support the Path Argument (functions are already placed within a folder matching their name).

Examples

Complete examples of generator output available in Examples

• react-firebase-redux example - redux and Firebase Real Time Database
• redux-firestore - redux and Firestore
• react-firebase example - Firebase Real Time Database

For full projects built out using this as a starting place, check the next section.

Projects Started Using This

• fireadmin.io - Application for Managing Firebase Applications. Includes support for multiple environments and data migrations.
• devshare.io - Codesharing site based on Firebase's Firepad and Realtime Database
• react-redux-firebase material example - Shows usage of react-redux-firebase with material-ui
• react-redux-firebase firestore example - Shows usage of react-redux-firebase with firestore

open an issue or reach out over gitter if you would like your project to be included

FAQ

1. Why node 8 instead of a newer version? Cloud Functions runtime was still on 8, which is why that is what is used for the suggested build version as well as the version used when building within CI.

2. Why enhancers over containers? - For many reasons, here are just a few:

• separates concerns to have action/business logic move to enhancers (easier for future modularization + optimization)
• components remain "dumb" by only receiving props which makes them more portable
• smaller files which are easier to parse
• functional components can be helpful (along with other tools) when attempting to optimize things

1. Where are the settings for changing how my project deploys through Continious integration?

   Within .firebaserc under the ci section. These settings are loaded by firebase-ci

2. How do override react-redux-firebase and redux-firestore configuration based on environment? Like adding logging only to staging?

   Add the following to .firebaserc under the branch associated with the environment you wish to change:

   "reduxFirebase": {
     "userProfile": "users",
     "enableLogging": false,
     "updateProfileOnLogin": false
   }

   Should look end up looking similar to the following:

   "master": {
     "env": "staging",
     "firebase": {
       "apiKey": "${STAGE_FIREBASE_API_KEY}",
       "authDomain": "some-project.firebaseapp.com",
       "databaseURL": "https://some-project.firebaseio.com",
       "projectId": "some-project",
       "storageBucket": "some-project.appspot.com"
     },
     "reduxFirebase": {
       "enableLogging": true
     }
   }

In the future

• Option to include tests when using sub-generators
• Airbnb linting option (currently only standard)
• Option to use simple file structure instead of fractal pattern
• Open to ideas

License

MIT © Prescott Prue