Firebase is back at Google I/O on May 10! Register now

API Reference

Stay organized with collections Save and categorize content based on your preferences.

Below contains an overview of the specifications for the Bundle Builder API, including TypeScript definitions & detailed descriptions.

BundleDocument Interface

The specification for a single document within the configured collection:

type BundleDocument = {
  // A list of document IDs to serve in the bundle.
  docs?: Array<string>;
  // A map containing individual named queries and their definitions.
  queries?: Map<string, QueryDefinition[]>;
  // A map of parameters and their definitions, which can be provided to a query definition.
  params?: Map<string, ParamDefinition>;
  // Specifies how long to keep the bundle in the client's cache, in seconds. If not defined, client-side cache is disabled.
  clientCache?: string;
  // Only used in combination with Firebase Hosting. Specifies how long to keep the bundle in Firebase Hosting CDN cache, in seconds.
  serverCache: string;
  // Specifies how long (in seconds) to keep the bundle in a Cloud Storage bucket, in seconds. If not defined, Cloud Storage bucket is not accessed.
  fileCache?: string;
  // If a 'File Cache' is specified, bundles created before this timestamp will not be file cached.
  notBefore?: Timestamp;
};

ParamDefinition Interface

The specification of a single parameter defined in a BundleDocument.

type ParamDefinition = {
  // Whether this parameter is required. If not provided as a query string, an error will be thrown.
  required: boolean;
  // The type of value which will be parsed, defaults to 'string'.
  type?:
    | "string"
    | "integer"
    | "float"
    | "boolean"
    | "string-array"
    | "integer-array"
    | "float-array";
};

For example, given the follow parameter:

params: {
  name: {
    required: true,
    type: 'string',
  }
}

When making a request to the bundle HTTP endpoint, the parameter can be provided via a query parameter, e.g. ?name=david. The parameter can be used within a QueryDefinition (see below) value ($name) to dynamically create bundles.

QueryDefinition Interface

A query definition is used to create named queries on the bundle. Each object within the queries map will create a new named query, using the object key as the name. Each query must specify a collection, and optionally a list of query conditions to perform.

type QueryDefinition = {
  // The collection to perform the query on.
  collection: string;
  // An optional list of conditions to perform on the specified collection.
  conditions?: QueryCondition[];
};

The conditions parameter can contain an array of QueryCondition interfaces. Each item in the array must only include a single condition.

type QueryCondition = {
  // Performs a `where` filter on the collection on a given FieldPath, operator and value.
  where?: [
    string,
    (
      | "<"
      | "<="
      | "=="
      | ">="
      | ">"
      | "!="
      | "array-contains"
      | "in"
      | "not-in"
      | "array-contains-any"
    ),
    any
  ];
  orderBy?: [string, ("asc" | "desc")?];
  limit?: number;
  limitToLast?: number;
  offset?: number;
  startAt?: string;
  startAfter?: string;
  endAt?: string;
  endBefore?: string;
};

For example, to create a query named "products" on a products collection with a where and limit condition, the data structure output should match the following:

queries: {
  products: {
    collection: 'products',
    conditions: [
      { where: ['type', '==', 'featured'] },
      { limit: 10 },
    ],
  }
}

When providing array values to in, not-in, or array-contains-any filters, you must provide a comma separated value as the value as nested array values are not supported in Firestore. For example:

{ where: ['category', 'in', 'womens,shorts'] }, // ['womens', 'shorts']

Any number value will be parsed as a number, however if a string number value is required it should be wrapped in parentheses:

{ where: ['price', 'in', '1,2.5'] }, // [1, 2.5]
{ where: ['price', 'in', '"1","2.5"'] }, // ['1', '2.5']

Conditions can also be used alongside parameters. For example, if a parameter type is defined (see above), this can be provided to a condition value to provide dynamic data bundles via the $ syntax:

// ?type=featured


    conditions: [
      { where: ['type', '==', '$type'] },