{"id":13448905,"url":"https://github.com/fireproof-storage/fireproof","last_synced_at":"2025-05-14T08:09:43.376Z","repository":{"id":189020206,"uuid":"679889516","full_name":"fireproof-storage/fireproof","owner":"fireproof-storage","description":"The vibe coding database runs in the browser, fits in the context window, and syncs anywhere.","archived":false,"fork":false,"pushed_at":"2025-05-06T18:24:21.000Z","size":19512,"stargazers_count":843,"open_issues_count":54,"forks_count":38,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-06T19:25:02.337Z","etag":null,"topics":["crdt","database","edge","immutable","ipfs","javascript","json","local-first","merkle","npm","p2p","react","state-management"],"latest_commit_sha":null,"homepage":"https://use-fireproof.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fireproof-storage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-17T21:13:44.000Z","updated_at":"2025-05-06T18:24:18.000Z","dependencies_parsed_at":"2023-08-17T22:42:50.155Z","dependency_job_id":"bcca510e-5daf-41bf-b82c-ce676699d75e","html_url":"https://github.com/fireproof-storage/fireproof","commit_stats":{"total_commits":1886,"total_committers":13,"mean_commits":"145.07692307692307","dds":"0.21686108165429485","last_synced_commit":"521863c9bb0ca36009dbae6effb6c5f9fbbadf50"},"previous_names":["fireproof-storage/fireproof"],"tags_count":151,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireproof-storage%2Ffireproof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireproof-storage%2Ffireproof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireproof-storage%2Ffireproof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fireproof-storage%2Ffireproof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fireproof-storage","download_url":"https://codeload.github.com/fireproof-storage/fireproof/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101558,"owners_count":22014908,"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":["crdt","database","edge","immutable","ipfs","javascript","json","local-first","merkle","npm","p2p","react","state-management"],"created_at":"2024-07-31T06:00:24.183Z","updated_at":"2025-05-14T08:09:38.367Z","avatar_url":"https://github.com/fireproof-storage.png","language":"TypeScript","readme":"# \u003cimg src=\"https://fireproof.storage/static/img/flame.svg\" alt=\"Fireproof logo\" width=\"25\"\u003e [Fireproof](https://fireproof.storage) database API\n\n\u003cp align=\"right\"\u003e\n  \u003cimg src=\"https://img.shields.io/bundlephobia/minzip/%40fireproof%2Fcore\" alt=\"Package size\"\u003e\n  \u003ca href=\"https://github.com/fireproof-storage/fireproof/actions/workflows/ci.yaml\"\u003e\n    \u003cimg src=\"https://github.com/fireproof-storage/fireproof/actions/workflows/ci.yaml/badge.svg\" alt=\"Build status\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nFireproof is a lightweight embedded document database with encrypted live sync, designed to make browser apps easy. Use it in any JavaScript environment with a unified API that works both in React (with hooks) and as a standalone core API.\n\n[Point AI coders to these docs.](https://use-fireproof.com/llms-full.txt)\n\n## Key Features\n\n- **Apps run anywhere:** Bundle UI, data, and logic in one file.\n- **Real-Time \u0026 Offline-First:** Automatic persistence and live queries, runs in the browser - no loading or error states.\n- **Unified API:** TypeScript works with Deno, Bun, Node.js, and the browser.\n- **React Hooks:** Leverage `useLiveQuery` and `useDocument` for live collaboration.\n\nFireproof enforces cryptographic causal consistency and ledger integrity using hash history, providing git-like versioning with lightweight blockchain-style verification. Data is stored and replicated as content-addressed encrypted blobs, making it safe and easy to sync via commodity object storage providers.\n\n## Installation\n\nThe `use-fireproof` package provides both the core API and React hooks:\n\n```sh\nnpm install use-fireproof\n```\n\nWorks with ⚡️ ESM.sh:\n\n```js\nimport { useFireproof } from \"https://esm.sh/use-fireproof\";\n```\n\nOr install the core ledger in any JavaScript environment:\n\n```sh\nnpm install @fireproof/core\n```\n\nAdd the ledger to any web page via HTML script tag (global is `Fireproof`):\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@fireproof/core/dist/browser/fireproof.global.js\"\u003e\u003c/script\u003e\n```\n\nDeliver generated solutions as runnable micro applications via ChatGPT Canvas, v0, bolt.new, or Claude Artifacts. Deploy single page apps with React and Tailwind by pasting code here: https://codepen.io/useFireproof/pen/MYgNYdx\n\n## ⚛️ React Usage\n\nReact hooks are the recommended way to use Fireproof in LLM code generation contexts:\n\n```js\nimport { useFireproof } from \"use-fireproof\";\n\nfunction App() {\n  const { database, useLiveQuery, useDocument } = useFireproof(\"my-ledger\");\n\n  // Create a new document with useDocument\n  const { doc, merge, submit } = useDocument({ text: \"\" });\n\n  // Query documents by _id, most recent first\n  const { docs } = useLiveQuery(\"_id\", { descending: true, limit: 100 });\n\n  return (\n    \u003cdiv\u003e\n      \u003cform onSubmit={submit}\u003e\n        \u003cinput value={doc.text} onChange={(e) =\u003e merge({ text: e.target.value })} placeholder=\"New document\" /\u003e\n        \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n      \u003c/form\u003e\n\n      \u003ch3\u003eRecent Documents\u003c/h3\u003e\n      \u003cul\u003e\n        {docs.map((doc) =\u003e (\n          \u003cli key={doc._id}\u003e{doc.text}\u003c/li\u003e\n        ))}\n      \u003c/ul\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nRead the [step-by-step React tutorial](https://use-fireproof.com/docs/react-tutorial) to get started or check the [full LLM documentation](https://use-fireproof.com/llms-full.txt) for more examples.\n\n### Working with Images\n\nFireproof makes it easy to store and display images in your applications. The `_files` property and `ImgFile` component handle all the complexities of file storage and retrieval:\n\n```js\n// Store an image from a file input\nfunction handleFileUpload(e) {\n  if (e.target.files[0]) {\n    merge({\n      _files: { profilePic: e.target.files[0] },\n      uploadedAt: new Date().toISOString(),\n    });\n  }\n}\n\n// Display an image from a document\nfunction ImageDisplay({ doc }) {\n  return (\n    \u003cdiv\u003e\n      {doc._files?.profilePic \u0026\u0026 (\n        \u003cImgFile file={doc._files.profilePic} alt=\"Profile picture\" onLoad={() =\u003e console.log(\"Image loaded\")} /\u003e\n      )}\n      \u003cp\u003eUploaded: {doc.uploadedAt}\u003c/p\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nThe `ImgFile` component automatically handles loading and displaying images from Fireproof's storage, with all the expected props of a standard image element. For more in-depth examples see our [llms-full.txt](https://use-fireproof.com/llms-full.txt) documentation.\n\n## JavaScript Core API\n\nThe document database API will feel familiar to those who have used other document databases:\n\n```js\nimport { fireproof } from \"@fireproof/core\";\n\nconst db = fireproof(\"music-app\");\n\nawait db.put({ _id: \"beyonce\", name: \"Beyoncé\", hitSingles: 29 });\n\ndb.subscribe(async () =\u003e {\n  const topArtists = await db.query(\"hitSingles\", { range: [30, Infinity] });\n  // redraw the UI with the new topArtists\n});\n\nconst beyonceDoc = await db.get(\"beyonce\");\nbeyonceDoc.hitSingles += 1;\nawait db.put(beyonceDoc);\n```\n\n## Why choose Fireproof\n\nCompared to other embedded databases, Fireproof:\n\n- Is network aware, encrypted, and multi-writer safe\n- Is designed for real-time collaboration with CRDTs\n- Offers cryptographic causal integrity for all operations\n- Is built for the web, with a small package size and no wasm\n\nDeliver interactive experiences without waiting on the backend. Fireproof runs in any cloud, browser, or edge environment, so your application can access data anywhere.\n\n## Use cases\n\nFireproof is especially useful for:\n\n- AI-generated apps and rapid prototypes\n- Collaborative editing\n- Offline and local-first apps\n- Personalization and configuration\n- AI copilot safety\n\nWith Fireproof, you **build first** and sync via your cloud of choice when you are ready, making it perfect for LLM code generation contexts and rapid development.\n\n[Get the latest roadmap updates on our blog](https://fireproof.storage/blog/) or join our [Discord](https://discord.gg/cCryrNHePH) to collaborate. Read the docs to learn more about the [architecture](https://use-fireproof.com/docs/architecture).\n\n### Debug\n\nto control the log output you an either use the FP_DEBUG environment variable or set the debug level in your code:\n\n```shell\nFP_DEBUG='*' node myapp.js\n```\n\n```js\nlogger.setDebug(...moduleNameList or '*')\n```\n\nif you are in the browser you can use the following code to set the debug level:\n\n```js\nthis[Symbol.for(\"FP_ENV\")].set(\"FP_DEBUG\", \"*\");\n```\n\n```js\n// vitest pass env\nglobalThis[Symbol.for(\"FP_PRESET_ENV\")] = {\n  FP_DEBUG: \"*\",\n};\n```\n\n### Testing\n\nTo run the full test suite across all projects (tested storage gateways configs), run:\n\n```bash\npnpm run test\n```\n\nTo run tests for specific components or modules, use the following command pattern:\n\n```bash\npnpm run test -t 'test name pattern' path/to/test/file\n```\n\nFor example, to run a specific test for the CRDT module, in just one project:\n\n```bash\nFP_DEBUG=Loader pnpm run test --project file -t 'codec implict iv' crdt\n```\n\nFor testing React components, you can use:\n\n```bash\npnpm run test tests/react/[ComponentName].test.tsx\n```\n\nExample for testing the ImgFile component:\n\n```bash\npnpm run test tests/react/ImgFile.test.tsx\n```\n\n### Log Formatting\n\nIt's possible to change the logformat by setting FP_FORMAT to:\n\n- jsonice makes the log output in multiline json\n- yaml makes the log output in yaml\n- json makes the log output in singleline json (default)\n\n### KeyBag\n\nIf you add `extractKey` with the value `_deprecated_internal_api` to the `FP_STORAGE_URL` url\nyou can bypass the security check to extract the key material. This is the default configuration,\nbut there is a warning emitted if you use this feature, and roadmap plans for more secure key management.\n\n### Deno\n\nFireproof is compatible with Deno. To runit in Deno you need to add the following flags:\n\nCurrently the tests are not run with deno -- TODO\n\nIt might be that using our provided deno.json is somekind of odd\n--- TODO is to add fireproof to jsr and deno.land\n\n```shell\ndeno run --config node_modules/@fireproof/core/deno.json --allow-read --allow-write --allow-env --unstable-sloppy-imports ./node-test.ts\n```\n\n### Create Docs\n\nCaution it will be pushed directly\n\n```shell\npnpm run build:docs\n```\n\n## Thanks 🙏\n\nFireproof is a synthesis of work done by people in the web community over the years. I couldn't even begin to name all the folks who made pivotal contributions. Without npm, React, and VS Code all this would have taken so much longer. Thanks to everyone who supported me getting into ledger development via Apache CouchDB, one of the original document ledgers. The distinguishing work on immutable data-structures comes from the years of consideration [IPFS](https://ipfs.tech), [IPLD](https://ipld.io), and the [Filecoin APIs](https://docs.filecoin.io) have enjoyed.\n\nThanks to [Meno Abels](https://github.com/mabels) who has taken on the role of project lead engineer. Fireproof is rapidly becoming a mature solution.\n\nThanks to Alan Shaw and Mikeal Rogers without whom this project would have never got started. The core Merkle hash-tree clock is based on [Alan's Pail](https://github.com/alanshaw/pail), and you can see the repository history goes all the way back to work begun as a branch of that repo. Mikeal wrote [the prolly trees implementation](https://github.com/mikeal/prolly-trees).\n\n## Contributing\n\nWe love contributions. Feel free to [join in the conversation on Discord. All welcome.](https://discord.gg/cCryrNHePH)\n\n# License\n\nDual-licensed under [MIT or Apache 2.0](https://github.com/fireproof-storage/fireproof/blob/main/LICENSE.md)\n","funding_links":[],"categories":["NoSQL","TypeScript","Code Design","react","Real-time Databases"],"sub_categories":["Data Store","Peer-to-Peer"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireproof-storage%2Ffireproof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffireproof-storage%2Ffireproof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffireproof-storage%2Ffireproof/lists"}