{"id":16206944,"url":"https://github.com/luc-mo/firebase-handler","last_synced_at":"2025-04-07T20:13:02.028Z","repository":{"id":215545756,"uuid":"697514808","full_name":"luc-mo/firebase-handler","owner":"luc-mo","description":"Firestore, Realtime Database and Storage wrapper","archived":false,"fork":false,"pushed_at":"2023-10-04T05:33:27.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T15:01:37.602Z","etag":null,"topics":["firebase","firebase-admin","firestore","nodejs","realtime-database","storage","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@snowdrive/firebase-handler","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luc-mo.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}},"created_at":"2023-09-27T22:22:56.000Z","updated_at":"2023-10-03T08:03:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"684e4220-6b00-4f33-9eb5-cb45fad4763b","html_url":"https://github.com/luc-mo/firebase-handler","commit_stats":{"total_commits":46,"total_committers":1,"mean_commits":46.0,"dds":0.0,"last_synced_commit":"b006d5e86c5d6dcebf186fe2e8e546130411738b"},"previous_names":["luc-mo/firebase-handler"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-mo%2Ffirebase-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-mo%2Ffirebase-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-mo%2Ffirebase-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-mo%2Ffirebase-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luc-mo","download_url":"https://codeload.github.com/luc-mo/firebase-handler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721900,"owners_count":20985084,"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":["firebase","firebase-admin","firestore","nodejs","realtime-database","storage","typescript"],"created_at":"2024-10-10T10:09:16.131Z","updated_at":"2025-04-07T20:13:01.998Z","avatar_url":"https://github.com/luc-mo.png","language":"TypeScript","readme":"# Firebase Handler\nA wrapper for Firestore, Realtime Database, and Storage services provided by the firebase-admin library.\nIt's designed to handle singleton instances of those Firebase services, simplifying the access to them.\n\n[![license](https://img.shields.io/github/license/luc-mo/firebase-handler?color=blue)](https://github.com/luc-mo/firebase-handler/blob/HEAD/LICENSE)\n[![npm latest package](https://img.shields.io/npm/v/@snowdrive/firebase-handler/latest?color=blue)](https://www.npmjs.com/package/@snowdrive/firebase-handler)\n[![npm downloads](https://img.shields.io/npm/dm/@snowdrive/firebase-handler)](https://www.npmjs.com/package/@snowdrive/firebase-handler)\n\n\n## Table of Contents\n* [Features](#features)\n* [Installation](#installation)\n  - [Configuration](#configuration)\n  - [Logger](#logger)\n  - [Initialization](#initialization)\n* [Usage](#usage)\n  - [Firestore](#firestore)\n  - [Realtime Database](#realtime-database)\n  - [Storage](#storage)\n  - [Disconnect](#disconnect)\n* [Development](#development)\n  - [Scripts](#scripts)\n* [Dependencies](#dependencies)\n* [Repository](#repository)\n* [License](#license)\n\n\n## Features\n- Singleton instance handlers for Firestore, Realtime Database, and Storage.\n- Built-in disconnect method for easy cleanup.\n- Fully TypeScript support.\n\n\n## Installation\n```bash\nnpm install @snowdrive/firebase-handler\nyarn add @snowdrive/firebase-handler\npnpm add @snowdrive/firebase-handler\n```\n\n\n## Usage\nMake sure to initialize the library with the required dependencies.\n\n\n### Configuration\nFirebase app credentials can be configurated in three ways:\n- Using `applicationDefault` function from the firebase-admin library.\n- Using a service account object or a path to a JSON file.\n- Using a refresh token.\n\nNote: By default, if you don't provide any credentials, the library will try to connect to the services using the `applicationDefault` option.\n\n#### Service account and refresh token\n```ts\nconst credentialConfig = {\n  serviceAccount: {\n    projectId: \"\u003cPROJECT_ID\u003e\",\n    clientEmail: \"foo@\u003cPROJECT_ID\u003e.iam.gserviceaccount.com\",\n    privateKey: \"-----BEGIN PRIVATE KEY-----\u003cKEY\u003e-----END PRIVATE KEY-----\\n\"\n  },\n  // or\n  refreshToken: \"\u003cREFRESH_TOKEN\u003e\"  \n}\n\nconst config = {\n  firebase: {\n    credential: credentialConfig\n  }\n}\n```\n\nYou can also provide the path to a JSON file containing the service account or the refresh token configuration.To read more about the Firebase App initialization, check the [official documentation](https://firebase.google.com/docs/admin/setup#initialize-sdk).\n\nNote: If you try to use both configuration properties, the service account object will be prioritized.\n\n#### Database and Storage\nTo configurate the Realtime Database and Storage Bucket, you can use the `databaseURL` and `storageBucket` properties respectively.\n\n```ts\nconst config = {\n  firebase: {\n    credential: { /* Previous configuration */ },\n    databaseURL: 'https://\u003cDATABASE_NAME\u003e.firebaseio.com',\n    storageBucket: '\u003cPROJECT_ID\u003e.appspot.com',\n  }\n}\n```\nNote: Both are optional, but you won't be able to use the services that require them.\n\n#### Additional settings\nYou can also provide the Firestore settings, which are optional, including the top-level configuration property. Also, you can use the \"handlers\" configuration to use our recommended settings for the services.\n```ts\nconst config = {\n  firestore: {\n    // All compatible firestore settings provided by the firebase-admin library.\n  },\n  handlers: {\n    useFirestoreRecommendedSettings: true, // Enable recommended settings for Firestore.\n  }\n}\n```\n\nThe Firestore recommended settings enable `ignoreUndefinedProperties` property.\n\n\n### Logger\nSet up your logger (here's a basic example):\n\n```ts\nconst logger = {\n  info: (message, data) =\u003e { console.log(message, data) },\n  error: (message, data) =\u003e { console.error(message, data) }\n}\n```\n\n\n### Usage\nUsing the provided configurations:\n\n```ts\nimport * as admin from 'firebase-admin'\nimport { FirebaseHandler } from '@snowdrive/firebase-handler'\n\nconst dependencies = {\n  admin: admin,\n  config: config,\n  logger: logger\n}\n\nconst firebaseHandler = new FirebaseHandler(dependencies)\n```\n\n#### Firestore Database\n```ts\nconst firestore = firebaseHandler.getFirestoreInstance()\n```\n\n#### Realtime Database\n```ts\nconst realtimeDb = firebaseHandler.getRealtimeInstance()\n```\nNote: Ensure your configuration includes `databaseURL`.\n\n#### Storage Bucket\n```ts\nconst storage = firebaseHandler.getStorageInstance()\n```\nNote: Ensure your configuration includes `storageBucket`.\n\n#### Disconnect\nTo disconnect from all services:\n```ts\nfirebaseHandler.disconnect()\n```\n\n\n## Development\n\n### Scripts\n- **build**: Compiles the TypeScript code.\n- **test**: Runs tests.\n- **test:watch**: Runs tests in watch mode.\n- **lint** \u0026 **format**: For checking and formatting code respectively.\n\n## Dependencies\n- [Firebase Admin SDK](https://www.npmjs.com/package/firebase-admin)\n- [Biome toolchain](https://www.npmjs.com/package/@biomejs/biome)\n- [Tsup bundler](https://www.npmjs.com/package/tsup)\n- [TypeScript language](https://www.npmjs.com/package/typescript)\n- [Vitest testing framework](https://www.npmjs.com/package/vitest)\n- [Environment variables loader](https://www.npmjs.com/package/dotenv)\n- [Cross-platform environment variables setter](https://www.npmjs.com/package/cross-env)\n\n\n## Repository\nExplore the source code, report issues, or contribute to the development of this project at our [GitHub Repository](https://github.com/luc-mo/firebase-handler).\nYour feedback and contributions are highly appreciated!\n\n\n## License\nThis project is licensed under the GPL-3.0-or-later. See the [LICENSE](https://github.com/luc-mo/firebase-handler/blob/HEAD/LICENSE) file in the repository for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluc-mo%2Ffirebase-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluc-mo%2Ffirebase-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluc-mo%2Ffirebase-handler/lists"}