@butlerlogic/firebase-api
v1.0.11
Published
A boilerplate structure for building an HTTP API using Firebase functions.
Downloads
34
Readme
firebase-api
A boilerplate structure for building an HTTP API using Firebase functions.
Usage
tldr; (but you really should read below - this does ALOT)
npm i @butlerlogic/firebase-api -S
npm run init
Installation Instructions
Navigate to the functions directory in your Firebase project and run npm i @butlerlogic/firebase-api -S
. This will install the module and add it to the package.json
file. It will also create a new npm script in the package.json
file, called init
.
Next, you can initialize the project with a new boilerplate API. Make sure you understand what will be produced (detailed below). Once you're comfortable, run npm run init
.
The init
command performs the following actions:
Creates a new index.js
file
The index file is very simple, with very little code. However; it is inceredibly powerful. The code in the file will scan the directory it is in (including any top level directories within the root) looking for files that do not begin with a _
or .
. It attempts to load/export each of these files as a firebase function.
This approach allows developers to organize code into directories however desired.
Creates api/routess.js
file
This file contains an express configuration, including an example endpoint that will run.
You'll also notice a Common API module is preconfigured and applied. This provides rudimentary API endpoints, such as /ping
, /version
, and /info
. It also applies an open CORS policy to make development easy, which you'll most likely want to modify before moving to production if you want strict CORS enforcement (fine to leave as is for most API's).
The common API provides a number of rapid prototyping methods that can be used in development and production. It's strongly advised you read about what is possible (mostly because it's really easy).
Creates .firebase_credentials.json
if no credential file can be found.
Running some Firebase functions locally does not require the use of credentials, but you'll need them if you want to connect to the production FireStore database or other features while you're working locally. This file should only be loaded when running the emulator locally and it should never be commited to git or any part of Firebase. This module will automatically load the credentials file for you when running the emulator and skip it in when deployed (because the hosted version automatically loads your credentials). This file is referenced in the env.json
file (see below). If you have a different credential file, make sure to modify the env.json
file to reflect the appropriate path.
Creates env.json
file
This module leverages localenvironment to simplify environment management. By default, this will load an environment variable this module understands/respects when running Firebase functions in the local emulator.
Creates npm commands:
Several commands are created automatically, using the @butlerlogic/firebase CLI utility:
npm run setup
: Parses the API code for all references tofunctions.config()
and reverse engineers an appropriate.runtimeconfig.json
from the code. You will need to fill in the appropriate values. This append.runtimeconfig.json
if it already exists. This is most useful when trying to find out which environment variables are used within the code base, or when starting work on an existing project.npm run configure
: This will configure the environment variables on the Firebase server using the values found in the.runtimeconfig.json
file.npm run configure:debug
: Same as above, but it will print the configuration command to the screen in plaintext. THIS MAY EXPOSE SENSISTIVE CONTENT, so don't use this on a CI server or other remote environment. Only use it when working on your local workstation.npm run deploy
: This runs the configure function, then the firebase deploy command (functions only).
Adds required dependencies:
Firebase requires certain dependencies to exist in order to run functions locally. These are automatically added to the package.json
file if they do not already exist.
Runs npm install
Since new dependencies are added, a final npm installation is executed to assure all necessary dependencies exist.
With an initialized project, you can immediately start experimenting with the API by modifying the api/routes.js
file and running npm start
to launch the local Firebase function emulator.