Introduction
Foundry uses the configuration file - foundry.yaml - to load your Cloud Functions, how you want to trigger them, and to what production data you want to have access.
The configuration file describes 4 main things:
Run $ foundry init to generate a default foundry.yaml configuration file
The configuration file must always be placed next to the Firebase Cloud Function's package.json file. You can run $ foundry init to generate a basic configuration file. Make sure to call this command from a directory where your package.json for your Firebase Cloud Functions is placed.
The configuration file must always be placed next to the Firebase Cloud Function's package.json file
To learn more about different parts of the configuration file please read:
Here's an example of the full config file with all possible options:
# [OPTIONAL]
# An array of glob patterns for files that should be ignored. The path is relative
# to the config file's path.
# If the array is changed, the CLI must be restarted for it to take the effect.
ignore:
# Skip all node_modules directories
- "**/node_modules"
# Skip the whole .git directory
- .git
# Skip all temp files ending with number
- "**/*.*[0-9]"
# Skip all hidden files
- "**/.*"
# Skip Vim's temp files
- "**/*~"
# [OPTIONAL]
# A path to a service account for your Firebase project.
# See https://github.com/FoundryApp/foundry-cli#field-serviceAcc
# for more info on how to obtain your service account.
serviceAcc: path/to/service/account.json
# [OPTIONAL]
# An array describing emulated Firebase Auth users in your cloud environment
users:
# You can describe your emulated Auth users either directly
- id: user-id-1
# The 'data' field takes a JSON string
data: '{"email": ""}'
# Or you can copy your production users from Firebase Auth by using 'getFromProd'
# (WARNING: service account is required!):
# If the value is a number, Foundry takes first N users from Firebase Auth
- getFromProd: 2
# If the value is an array, Foundry expects that the array's elements
# are real IDs of your Firebase Auth users
- getFromProd: [id-of-a-user-in-production, another-id]
# You can use both the direct and 'getFromProd' approach simultaneously
# The final Firebase Auth users will be a merge of these
# [OPTIONAL]
# An array describing emulated Firestore in your cloud environment
firestore:
# You can describe your emulated Firestore either directly
- collection: workspaces
docs:
- id: ws-id-1
data: '{"userId": "user-id-1"}'
- id: ws-id-2
data: '{"userId": "user-id-2"}'
# Or you can copy data from your production Firestore by using 'getFromProd'
# (WARNING: service account is required!):
# If the value is a number, Foundry takes first N documents from the
# specified collection (here 'workspaces')
- getFromProd: 2
# If the value is an array, Foundry expects that the array's elements
# are real IDs of documents in the specified collection (here documents
# in the 'workspaces' collection)
- getFromProd: [workspace-id-1, workspace-id-2]
# You can use both the direct and 'getFromProd' approach simultaneously
# The final documents will be a merge of these
# To create a nested collection:
- collection: collection/doc-id/subcollection
docs:
- id: doc-in-subcollection
data: '{}'
# [OPTIONAL]
# An array describing emulated RealtimeDB in your cloud environment
realtimeDB:
# You can describe your emulated RealtimeDb either directly
- ref: workspace-invites/workspace-1
children:
- child: user-1
data: '{"status":"accepted"}'
- child: user-2
data: '{"status":"pending"}'
# Or you can copy data from your production RealtimeDB by using 'getFromProd'
# (WARNING: service account is required!):
# If the value is an array, Foundry expects that the array's elements
# are real keys of children on the specified reference path (here children
# on the reference path 'workspace-invites/workspace-1')
- getFromProd: [user-3, user-4]
- ref: workspace-invites/workspace-2
children:
# If the value is 'all' Foundry takes all children from the reference path
# (here 'workspace-invites/workspace-2') in your production RealtimeDB
- getFromProd: all
# You can use both the direct and 'getFromProd' approach simultaneously
# The emulated RealtimeDB will be a merge of these
# [REQUIRED]
# An array describing your Firebase functions that should be evaluated by Foundry.
# All described functions must be exported in the function's root file.
# In this array, you describe how Foundry should load and trigger each function in every run.
functions:
# Foundry currently supports the following types of Firebase Functions:
# - https
# - httpsCallable
# - auth
# - firestore
# - realtimeDB
# Each function has at least 2 fields:
# 'name' - the same name under which a function is exported from your function's root file
# 'type' - one of the following: https, httpsCallable, auth, firestore, realtimeDB
# -----------------------
# Type: https
# A 'https' functions is the equivalent of
# https://firebase.google.com/docs/functions/http-events
- name: myHttpsFunction
type: https
# The request method is 'post' by default
# but you can change it to 'get', 'delete', 'options', or 'put'
method: get
# You can add segments and URL queries to the request route
route: /login/new?key=val
# The payload field can either be a JSON string
payload: '{"field":"value"}'
# or you can reference a document from your production Firestore
payload:
doc:
getFromProd:
collection: path/to/collection
id: doc-id
# or you can reference a document from the emulated Firestore
payload:
doc:
collection: path/to/collection
id: doc-id
# -----------------------
# Type: httpsCallable
# A 'httpsCallable' is the equivalent of
# https://firebase.google.com/docs/functions/callable
- name: myHttpsCallableFunction
type: httpsCallable
# Since 'httpsCallable' function is meant to be called
# from inside your app by your users, it expects a
# field 'asUser'
# With this field you specify as what user should this
# function be triggered
asUser:
# A user with this ID must be present in the emulated Firebase Auth users
id: user-id
# The 'payload' field is the same as in the 'https' function
payload: '{}'
# -----------------------
# Type: auth
# An 'auth' function is the equivalent of
# https://firebase.google.com/docs/functions/auth-events
# Based on the 'trigger' field, there are 2 sub-types of
# an 'auth' function: onCreate, onDelete
- name: myAuthOnCreateFunction
type: auth
trigger: onCreate
# NOTE: If you leave out the field 'createUser' the function will be loaded
# but won't automatically trigger on each run.
# The 'createUser' field specifies a new user record
# that will trigger this auth function.
# Keep in mind that this user will actually be created
# in the emulated Firebase Auth users!
createUser:
id: new-user-id
data: '{"email": ""}'
# You can also reference a Firebase auth user from your
# production by using the 'getFromProd' field.
# This user will be copied to the emulated Firebase auth users
# and will trigger this auth function:
createUser:
getFromProd:
id: user-id-in-production
- name: myAuthOnDeleteFunction
type: auth
trigger: onDelete
# NOTE: If you leave out the field 'deleteUser' the function will be loaded
# but won't automatically trigger on each run.
# This auth function will be triggered by deleting
# a user with the specified ID from your emulated
# Firebase Auth users.
# Keep in mind that this user will actually be deleted
# from the emulated Firebase Auth users!
deleteUser:
# A user with this ID must be present in the emulated Firebase Auth users
id: existing-user-id
# -----------------------
# Type: firestore
# A 'firestore' function is the equivalent of
# https://firebase.google.com/docs/functions/firestore-events
# Based on the 'trigger' field, there are 4 sub-types of
# a 'firestore' function: onCreate, onDelete, onUpdate, onWrite
- name: myFirestoreOnCreateFunction
type: firestore
trigger: onCreate
# NOTE: If you leave out the field 'createDoc' the function will be loaded
# but won't automatically trigger on each run.
# The 'createDoc' field creates a new specified document
# that will trigger this firestore function.
# Keep in mind that this document will actually be
# create in the emulated Firestore!
createDoc:
collection: path/to/collection
id: new-doc-id
data: '{}'
# You can also reference a document from your production
# Firestore database.
# This document will be copied to the emulated Firestore
# database and will trigger this function.
createDoc:
getFromProd:
collection: path/to/collection
id: existing-doc-id
- name: myFirestoreOnDeleteFunction
type: firestore
trigger: onDelete
# NOTE: If you leave out the field 'deleteDoc' the function will be loaded
# but won't automatically trigger on each run.
# The 'deleteDoc' field deletes a specified document from
# the emulated Firestore database. The deletion will
# trigger this firestore function.
# Keep in mind that this document will actually be
# deleted from the emulated Firestore database. So it must
# exist first!
deleteDoc:
# A document inside this collection must exist in the
# emulated Firestore database
collection: path/to/collection
id: existing-doc-id
- name: myFirestoreOnUpdateFunction
type: firestore
trigger: onUpdate
# NOTE: If you leave out the field 'updateDoc' the function will be loaded
# but won't automatically trigger on each run.
# The 'updateDoc' field updates a specified document
# from the emulated Firestore database with a new
# data. The update will trigger this firestore function.
# Keep in mind that this document will actually be
# updated in the emulated Firestore database. So it must
# exist first!
updateDoc:
collection: path/to/collection
id: existing-doc-id
# A JSON string specifying new document's data
data: '{}'
- name: myFirestoreOnWriteFunction
type: firestore
trigger: onWrite
# NOTE: If you omit the following fields the function will be loaded
# but won't automatically trigger on each run.
# Use one of 'createDoc', 'updateDoc', or 'deleteDoc'
createDoc:
# The same syntax as you would use with an onCreate function.
...
updateDoc:
# The same syntax as you would use with an onUpdate function
...
deleteDoc:
# The same syntax as you would use with an onDelete function
...
# -----------------------
# Type: realtimeDB
# A 'realtimeDB' function is the equivalent of
# https://firebase.google.com/docs/functions/database-events
# Based on the 'trigger' field, there are 4 sub-types of
# a 'realtimeDB' function: onCreate, onDelete, onUpdate, onWrite
- name: myRealtimeDBOnCreateFunction
type: realtimeDB
trigger: onCreate
# NOTE: If you leave out the field 'createRef' the function will be loaded
# but won't automatically trigger on each run.
# The 'createRef' field creates a new specified reference
# that will trigger this realtimeDB function.
# Keep in mind that this reference will actually be
# create in the emulated RealtimeDB!
createRef:
ref: path/to/reference
data: '{}'
# You can also use a reference from your production
# RealtimeDB.
# This reference will be copied to the emulated RealtimeDB
# and will trigger this function.
createRef:
getFromProd:
ref: path/to/reference
- name: myRealtimeDBOnDeleteFunction
type: realtimeDB
trigger: onDelete
# NOTE: If you leave out the field 'deleteRef' the function will be loaded
# but won't automatically trigger on each run.
# The 'deleteRef' field deletes a specified reference from
# the emulated RealtimeDB. The deletion will
# trigger this realtimeDB function.
# Keep in mind that this reference will actually be
# deleted from the emulated RealtimeDB. So it must
# exist first!
deleteRef:
# A reference on this path must exist in the
# emulated RealtimeDB
ref: path/to/reference
- name: myRealtimeDBOnUpdateFunction
type: realtimeDB
trigger: onUpdate
# NOTE: If you leave out the field 'updateRef' the function will be loaded
# but won't automatically trigger on each run.
# The 'updateRef' field updates a specified reference
# from the emulated RealtimeDB with a new
# data. The update will trigger this realtimeDB function.
# Keep in mind that this reference will actually be
# updated in the emulated RealtimeDB. So it must
# exist first!
updateRef:
ref: path/to/reference
# A JSON string specifying new document's data
data: '{}'
- name: myRealtimeDBOnWriteFunction
type: realtimeDB
trigger: onWrite
# NOTE: If you omit the following fields the function will be loaded
# but won't automatically trigger on each run.
# Use one of 'createRef', 'updateRef', or 'deleteRef'
createRef:
# The same syntax as you would use with an onCreate function.
...
updateRef:
# The same syntax as you would use with an onUpdate function
...
deleteRef:
# The same syntax as you would use with an onDelete function
...
Getting Started - Previous
Using Foundry in your project
Next - Configuration file
Defining Cloud Functions
Last updated 3 months ago