{"id":13683609,"url":"https://github.com/dalenguyen/firestore-backup-restore","last_synced_at":"2025-04-14T05:19:26.053Z","repository":{"id":39592980,"uuid":"131999758","full_name":"dalenguyen/firestore-backup-restore","owner":"dalenguyen","description":"NPM package for backup and restore Firebase Firestore","archived":false,"fork":false,"pushed_at":"2025-02-15T04:06:41.000Z","size":729,"stargazers_count":493,"open_issues_count":12,"forks_count":84,"subscribers_count":7,"default_branch":"dev","last_synced_at":"2025-04-14T05:19:14.250Z","etag":null,"topics":["backup","firebase","firestore","firestore-database","firestore-helper","hacktoberfest","npm-package","restore"],"latest_commit_sha":null,"homepage":"https://firebaseopensource.com/projects/dalenguyen/firestore-backup-restore/","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/dalenguyen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":"dalenguyen","patreon":null,"open_collective":null,"ko_fi":"dalenguyen","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-05-03T13:32:42.000Z","updated_at":"2025-03-28T18:44:51.000Z","dependencies_parsed_at":"2025-03-16T23:45:21.772Z","dependency_job_id":null,"html_url":"https://github.com/dalenguyen/firestore-backup-restore","commit_stats":{"total_commits":130,"total_committers":28,"mean_commits":4.642857142857143,"dds":0.5307692307692308,"last_synced_commit":"a3f57eca17c6fb47f025d45103f5069c3d249e50"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalenguyen%2Ffirestore-backup-restore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalenguyen%2Ffirestore-backup-restore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalenguyen%2Ffirestore-backup-restore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalenguyen%2Ffirestore-backup-restore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalenguyen","download_url":"https://codeload.github.com/dalenguyen/firestore-backup-restore/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824745,"owners_count":21167354,"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":["backup","firebase","firestore","firestore-database","firestore-helper","hacktoberfest","npm-package","restore"],"created_at":"2024-08-02T13:02:18.253Z","updated_at":"2025-04-14T05:19:26.031Z","avatar_url":"https://github.com/dalenguyen.png","language":"TypeScript","funding_links":["https://github.com/sponsors/dalenguyen","https://ko-fi.com/dalenguyen"],"categories":["TypeScript"],"sub_categories":[],"readme":"# firestore-export-import\n\n[![GitHub version](https://badge.fury.io/gh/dalenguyen%2Ffirestore-backup-restore.svg)](https://badge.fury.io/gh/dalenguyen%2Ffirestore-backup-restore)\n[![Build Status](https://travis-ci.org/dalenguyen/firestore-backup-restore.svg?branch=master)](https://travis-ci.org/dalenguyen/firestore-backup-restore)\n\nNPM package for backup and restore Firebase Firestore\n\nYou can export and import data from firestore with sub collection.\n\n## Installation\n\nInstall using [**npm**](https://www.npmjs.com/).\n\n```sh\nnpm install firestore-export-import\nOR\nyarn add firestore-export-import\n```\n\n## Get Google Cloud Account Credentials from Firebase\n\nYou can **Generate New Private Key** from Project Settings from [Firebase Console](https://console.firebase.google.com).\n\nAfter that you need to copy the **databaseURL** for initiating the App.\n\n## Usage\n\nYou have to import this package in a JavaScript file and work from there.\n\n## Initialize Firebase App\n\nYou have initialize the Firebase App in order to use Firestore service. It doesn't matter if you initialize it by using this plugin method or the offical way.\n\n```javascript\nconst { initializeFirebaseApp } = require('firestore-export-import')\n\nconst serviceAccount = require('./serviceAccountKey.json')\n\n// If you want to pass settings for firestore, you can add to the options parameters\nconst options = {\n  firestore: {\n    host: 'localhost:8080',\n    ssl: false,\n  },\n}\n\n// Initiate Firebase App\n// appName is optional, you can omit it.\nconst appName = '[DEFAULT]'\nconst firestore = initializeFirebaseApp(serviceAccount, appName, options)\n\n// the appName \u0026 options are OPTIONAL\n// you can initialize the app without them\n// const firestore = initializeFirebaseApp(serviceAccount)\n```\n\n### Export data from firestore\n\nYou can export collection and sub collection from your data. The sub collection is optional.\n\nExport options - OPTIONAL\n\n```javascript\n// Export options\nconst options = {\n  docsFromEachCollection: 10, // limit number of documents when exporting\n  refs: ['refKey', 'deep.level.key'], // reference Path\n}\n```\n\n```javascript\n// In your index.js\n\nconst { backup } = require('firestore-export-import')\n\n// Start exporting your data\nbackup(firestore, 'collection-name', options).then((data) =\u003e\n  console.log(JSON.stringify(data))\n)\n```\n\n### Export data from document\n\nBackup a document with sub collections\n\n```javascript\n// you can pass options as a third option - optional\nbackupFromDoc(firestore, 'collection-name', 'document-id').then((data) =\u003e\n  console.log(JSON.stringify(data))\n)\n```\n\nSub collections will be added under **'subCollection'** object.\n\n### Get all collections data\n\nThis is a suggestion from [jcummings2](https://github.com/jcummings2) and [leningsv](https://github.com/Leningsv)\n\nThe ['collectionName1', 'collectionName2'] is OPTIONAL, you can remove this parameter to get all of the current collections in your firestore.\n\nThe result is an object of collection's data.\n\n```javascript\nconst { backups } = require('firestore-export-import')\n\nbackups(firestore, ['collectionName1', 'collectionName2']) // Array of collection's name is OPTIONAL\n  .then((collections) =\u003e {\n    // You can do whatever you want with collections\n    console.log(JSON.stringify(collections))\n  })\n```\n\n### Export data with query\n\nYou are can back update based on query criteria. In this example, I am backing up all data from `users` collection, where name equals `Dale Nguyen`.\n\n```javascript\nconst queryByName = (collectionRef) =\u003e\n  collectionRef.where('name', '==', 'Dale Nguyen').get()\n\nconst users = await backup(firestore, 'users', {\n  queryCollection: queryByName,\n})\n```\n\n### Import data to firestore (Predefined Document Id)\n\nThis code will help you to import data from a JSON file to firestore. You have two options:\n\n- Restore from a JSON file from your local machine\n- Restore from a JSON from a HTTP request\n\nThis will return a Promise\u003c{status: boolean, message: string}\u003e\n\nRemember that, this action doesn't remove the collection. It will override or add new data to the collection. If you want to remove the current collection, you should do it from firebase console or using [firebase firestore:delete](https://firebase.google.com/docs/cli)\n\n```sh\nfirebase firestore:delete [options] \u003c\u003cpath\u003e\u003e\n```\n\n### Import / Restore Options\n\nThis is the options for the restore function. All of them are optional.\n\n```javascript\nexport interface IImportOptions {\n  dates?: string[]\n  autoParseDates?: boolean\n  geos?: string[]\n  autoParseGeos?: boolean\n  refs?: string[]\n  showLogs?: boolean\n}\n```\n\n#### For local JSON\n\nUsually the date, location \u0026 reference are not converted correctly when you backup the Firestore database. In order to import correctly, you have to pass to parameters for the options:\n\n```javascript\n// Import options\nconst options = {\n  dates: ['date1', 'date1.date2', 'date1.date2.date3'],\n  geos: ['location', 'locations'],\n  refs: ['refKey'],\n}\n```\n\nIf you don't want to specify `dates`, you can use another parameter in order to transform fields to date automatically.\n\n```javascript\n// Import options with auto parse date\nconst options = {\n  autoParseDates: true // use this one in stead of dates: [...]\n  geos: ['location', 'locations'],\n  refs: ['refKey'],\n};\n```\n\nAfter that, the data will be converted based on their types.\n\n```javascript\n// In your index.js\nconst { initializeFirebaseApp, restore } = require('firestore-export-import')\nconst serviceAccount = require('./serviceAccountKey.json')\n\n// Initiate Firebase App\n// appName is optional, you can omit it.\nconst appName = '[DEFAULT]'\nconst firestore = initializeFirebaseApp(serviceAccount, databaseURL, appName)\n\n// Start importing your data\n// The array of date, location and reference fields are optional\nrestore(firestore, 'your-file-path.json', {\n  dates: ['date1', 'date1.date2', 'date1.date2.date3'],\n  geos: ['location', 'locations'],\n  refs: ['refKey', 'arrayRef'],\n})\n```\n\n#### For HTTP Request\n\n```javascript\nimport request from 'request-promise';\n...\nconst backupData = await request('JSON-URL');\nconst status = await restore(firestore, JSON.parse(backupData), {\n  dates: ['date'],\n  geos: ['location']\n});\n```\n\nThe JSON is formatted as below. The collection name is **test**. **first-key** and **second-key** are document ids.\n\n```json\n{\n  \"test\": {\n    \"first-key\": {\n      \"website\": \"dalenguyen.me\",\n      \"date\": {\n        \"_seconds\": 1534046400,\n        \"_nanoseconds\": 0\n      },\n      \"schedule\": {\n        \"time\": {\n          \"_seconds\": 1534046400,\n          \"_nanoseconds\": 0\n        }\n      },\n      \"three\": {\n        \"level\": {\n          \"time\": {\n            \"_seconds\": 1534046400,\n            \"_nanoseconds\": 0\n          }\n        }\n      },\n      \"custom\": {\n        \"lastName\": \"Nguyen\",\n        \"firstName\": \"Dale\"\n      },\n      \"location\": {\n        \"_latitude\": 49.290683,\n        \"_longitude\": -123.133956\n      },\n      \"locationNested\": {\n        \"geopoint\": {\n          \"_latitude\": 49.290683,\n          \"_longitude\": -123.133956\n        }\n      },\n      \"locations\": [\n        {\n          \"_latitude\": 50.290683,\n          \"_longitude\": -123.133956\n        },\n        {\n          \"_latitude\": 51.290683,\n          \"_longitude\": -123.133956\n        }\n      ],\n      \"email\": \"dungnq@itbox4vn.com\",\n      \"secondRef\": \"test/second-key\",\n      \"arrayRef\": [\"test/second-key\", \"test/second-key\"],\n      \"nestedRef\": {\n        \"secondRef\": \"test/second-key\"\n      },\n      \"subCollection\": {\n        \"test/first-key/details\": {\n          \"33J2A10u5902CXagoBP6\": {\n            \"dogId\": \"2\",\n            \"dogName\": \"hello\"\n          },\n          \"MSZTWEP7Lewx0Qr1Mu5s\": {\n            \"dogName\": \"lala\",\n            \"dogId\": \"2\"\n          }\n        },\n        \"test/first-key/contacts\": {\n          \"33J2A10u5902CXagoBP6\": {\n            \"contactId\": \"1\",\n            \"name\": \"Dale Nguyen\"\n          },\n          \"MSZTWEP7Lewx0Qr1Mu5s\": {\n            \"contactId\": \"2\",\n            \"name\": \"Yen Nguyen\"\n          }\n        }\n      }\n    },\n    \"second-key\": {\n      \"website\": \"google.com\",\n      \"date\": {\n        \"_seconds\": 1534262435,\n        \"_nanoseconds\": 0\n      },\n      \"custom\": {\n        \"lastName\": \"Potter\",\n        \"firstName\": \"Harry\"\n      },\n      \"location\": {\n        \"_latitude\": 49.290683,\n        \"_longitude\": -123.133956\n      },\n      \"email\": \"test@dalenguyen.me\"\n    }\n  }\n}\n```\n\n### Import data to firestore (auto generate document id)\n\nIt works the same way as above. However the structure of JSON file is different. It's an array of documents.\n\n```json\n// import-array-to-firestore.json\n{\n  \"test\": [\n    {\n      \"name\": \"Dale Nguyen\",\n      \"email\": \"dale@dalenguyen.me\",\n      \"subCollection\": {\n        \"details\": [\n          {\n            \"dogId\": \"2\",\n            \"dogName\": \"hello\"\n          },\n          {\n            \"dogName\": \"lala\",\n            \"dogId\": \"2\"\n          }\n        ]\n      }\n    },\n    {\n      \"name\": \"Yen Nguyen\",\n      \"email\": \"yenchan@gmail.com\"\n    },\n    {\n      \"name\": \"Harry Potter\",\n      \"email\": \"harry@potter.me\"\n    }\n  ]\n}\n```\n\n## Contributions\n\nThis project is based on [firestore-import-export](https://github.com/dalenguyen/firestore-import-export), feel free to report bugs and make feature requests in the [Issue Tracker](https://github.com/dalenguyen/firestore-backup-restore/issues), fork and create pull requests!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalenguyen%2Ffirestore-backup-restore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalenguyen%2Ffirestore-backup-restore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalenguyen%2Ffirestore-backup-restore/lists"}