{"id":19257549,"url":"https://github.com/ericvera/firestore-index-gen","last_synced_at":"2025-07-20T14:34:48.928Z","repository":{"id":241158978,"uuid":"804497114","full_name":"ericvera/firestore-index-gen","owner":"ericvera","description":"CLI to generate Firebase Firestore index file from emulator","archived":false,"fork":false,"pushed_at":"2024-06-03T09:25:25.000Z","size":1095,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-06T14:42:57.607Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericvera.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-22T17:43:23.000Z","updated_at":"2024-06-14T00:30:09.900Z","dependencies_parsed_at":"2024-05-22T18:53:08.484Z","dependency_job_id":"5d85850b-a430-44d3-95f7-467159d48665","html_url":"https://github.com/ericvera/firestore-index-gen","commit_stats":null,"previous_names":["ericvera/firestore-index-gen"],"tags_count":12,"template":false,"template_full_name":"ericvera/ts-lib-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericvera%2Ffirestore-index-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericvera%2Ffirestore-index-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericvera%2Ffirestore-index-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericvera%2Ffirestore-index-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericvera","download_url":"https://codeload.github.com/ericvera/firestore-index-gen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245176390,"owners_count":20572940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T19:10:37.448Z","updated_at":"2025-03-23T22:21:24.595Z","avatar_url":"https://github.com/ericvera.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# firestore-index-gen\n\n**CLI that generates a Firestore Index file from queries executed during a Firestore emulator session.**\n\n[![github license](https://img.shields.io/github/license/ericvera/firestore-index-gen.svg?style=flat-square)](https://github.com/ericvera/firestore-index-gen/blob/master/LICENSE)\n[![npm version](https://img.shields.io/npm/v/firestore-index-gen.svg?style=flat-square)](https://npmjs.org/package/firestore-index-gen)\n\n\u003e WARNING: The following CLI is built on undocumented functionality that can break without any advance notice so read below to understand what you are getting into.\n\n## Problem\n\nSome Firebase Firestore queries require indexes to be defined before they can be used, but there is no easy way to figure out what those indexes should look like ahead of time.\n\nFirestore's current solution is to fail any queries that require an index and to log a link that automatically creates said index.\n\nThe current solution has some drawbacks:\n\n- no easy way to generate the index entries prior to deploying to Firebase\n- requires indexes to be deployed one-by-one\n- easy to deploy queries without the index\n\nThere is an [issue on Github](https://github.com/firebase/firebase-tools/issues/2027), opened March 2020, to add support for indexes to the emulator. The issue is still open and unresolved.\n\n## \"Undocumented Solution\"\n\nWithin that issue there is [a comment by one of the contributors](https://github.com/firebase/firebase-tools/issues/2027#issuecomment-1533866300) that mentions an undocumented feature of the emulator that generates a report that includes a list of indexes that would have been required in order to execute the queries executed during a Firestore emulator session.\n\nURL of the report:\n`http://127.0.0.1:8080/emulator/v1/projects/{projectId}:indexUsage?database=projects/{projectId}/databases/(default)`\n\nThe author of the comment also makes the following notes:\n\n    Note that the emulator doesn't know about your application's indexes, it simply attempts to create these from a set of theoretically optimal indexes. If your indexes don't match exactly it's still possible that all of your queries are covered by other indexes and will not fail in production.\n\n    Edit: The queries need to be executed to be stored at runtime and it must be a query that isn't automatically indexed (like a single-field query with no ordering). See https://firebase.google.com/docs/firestore/query-data/indexing for more info.\n\n    Disclaimer: this is unlaunched and the functionality might change in backward-incompatible ways.\n\n## Limitations\n\n- Fields with vector configurations are not currently supported by this tool. Contributions to add support for vector fields are welcome!\n\n## Possible solution for generating the indexes with `firestore-index-gen`\n\n\u003e This assumes that **all** of your queries are executed during your testing.\n\nGenerate the index by using a command like `firebase --project=firestore-indexes emulators:exec --only auth,firestore 'yarn test /path/to/tests \u0026\u0026 fig --projectId firestore-indexes --overwrite'`\n\n\u003e Ensure that the projectId matched the ID used when initializing Firebase in your tests.\n\n`firebase --project=firestore-indexes emulators:exec --only auth,firestore \u003ccommand\u003e` will launch the auth and firestore emulators and execute the provided command.\n\n`yarn test /path/to/tests` should execute all tests that execute queries against Firestore. It is possible to abstract your queries so that they all live in a sub-directory (e.g. `/util/queries/`) to reduce the execution time.\n\n## Possible solution for checking the indexes during CI with `firestore-index-gen`\n\nRun a command like `firebase --project=firestore-indexes emulators:exec --only auth,firestore 'yarn test /path/to/tests \u0026\u0026 fig --projectId firestore-indexes --check'`\n\nThis works just like the command above, except that instead of overwriting the content of `firestore.indexes.json` it compares the indexes from the emulator report and generates a diff. Also, the exit code is set to `1` (or fail) which would block your CI if there are differences.\n\n## CLI\n\n### Install\n\nTo install globally (can also be added as a dev dependency to your project):\n\n`npm install --global firestore-index-gen`\n\n### Usage\n\n```console\nUsage:\n  fig --projectId \u003cprojectId\u003e [--overwrite | --check]\n\nOptions:\n  --help         Print this help message\n  --projectId    The Firebase project ID used with the emulator\n  --overwrite    Overwrite firestore.indexes.json with the new indexes\n  --check        Check if firestore.indexes.json is up to date with the new indexes\n```\n\n### `check`\n\nUsing `fig --projectId \u003cprojectId\u003e --check` within your project, the CLI will printout a diff between the report and your current `firestore.indexes.json` and exit with `1`. If there are no differences the CLI will just print a success message and exit with `0`. This can be used as part of your CI to ensure no code makes it to production without the proper indexes.\n\n### `overwrite`\n\nUsing `fig --projectId \u003cprojectId\u003e --overwrite` will overwrite your current `firestore.indexes.json` with the indexes reported by the emulator.\n\nv.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericvera%2Ffirestore-index-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericvera%2Ffirestore-index-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericvera%2Ffirestore-index-gen/lists"}