{"id":16650,"library":"mindoodb","title":"MindooDB: End-to-End Encrypted Offline-First Database","description":"MindooDB is an end-to-end encrypted, offline-first sync database designed for collaborative applications. It uniquely ensures that encryption keys never leave client devices, meaning servers only ever process and store ciphertext, providing a robust security model against server compromises and data breaches. Built on Automerge CRDTs, it offers real-time collaboration with automatic conflict resolution, tamperproof history, and fine-grained access control through named encryption keys. It functions by syncing content-addressed encrypted blobs, supporting peer-to-peer, client-server, or hybrid synchronization. The package is currently in alpha (`v0.0.17`), indicating active development but with APIs subject to change and it is not yet recommended for production use. Release cadence is irregular during this early development phase. Its key differentiator is the client-side encryption, allowing data control to remain solely with the end-users.","status":"active","version":"0.0.17","language":"javascript","source_language":"en","source_url":"https://github.com/klehmann/mindoodb","tags":["javascript","database","e2e-encryption","offline-first","sync","crdt","automerge","react-native","expo","typescript"],"install":[{"cmd":"npm install mindoodb","lang":"bash","label":"npm"},{"cmd":"yarn add mindoodb","lang":"bash","label":"yarn"},{"cmd":"pnpm add mindoodb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides standard Web Crypto API compatibility for Expo and React Native environments.","package":"expo-standard-web-crypto","optional":true},{"reason":"Provides cryptographic primitives for Node.js environments.","package":"node-forge","optional":true},{"reason":"Core CRDT (Automerge) library specifically optimized for React Native.","package":"react-native-automerge-generated","optional":true},{"reason":"Enhances cryptographic performance in React Native environments.","package":"react-native-quick-crypto","optional":true},{"reason":"Provides low-level cryptographic primitives.","package":"tweetnacl","optional":true}],"imports":[{"note":"This is the primary import for Node.js environments. Ensure your project is configured for ESM. For web browsers, use the '/browser' subpath.","wrong":"const MindooDB = require('mindoodb');","symbol":"MindooDB","correct":"import { MindooDB } from 'mindoodb';"},{"note":"Use this specific import for web browser environments. Attempting to use the default 'mindoodb' import in a browser might result in compatibility issues or larger bundle sizes due to Node.js-specific dependencies.","wrong":"import { MindooDB } from 'mindoodb';","symbol":"MindooDB (Web)","correct":"import { MindooDB } from 'mindoodb/browser';"},{"note":"This type represents a document stored within MindooDB. Using `import type` explicitly indicates it's a type import, which can improve tree-shaking for bundlers.","wrong":"import { MindooDocument } from 'mindoodb';","symbol":"MindooDocument","correct":"import { type MindooDocument } from 'mindoodb';"}],"quickstart":{"code":"import { MindooDB, type MindooDocument } from 'mindoodb';\n\nasync function initializeAndUseMindooDB() {\n  // IMPORTANT: For production, manage user passwords securely and do NOT hardcode.\n  // This password is used to derive encryption keys for the user's data.\n  const userPassword = process.env.MINDOODB_PASSWORD ?? 'secure-dev-password-123';\n  const userId = 'my-unique-user-id'; // A unique identifier for the current user\n\n  console.log('Initializing MindooDB...');\n\n  // Instantiate MindooDB. In a real application, you'd configure a persistent\n  // storage adapter (e.g., IndexedDB for web) and potentially a sync service.\n  const db = new MindooDB({\n    userId: userId,\n    password: userPassword,\n  });\n\n  await db.init();\n  console.log(`MindooDB initialized for user: ${userId}`);\n\n  // 1. Create a new end-to-end encrypted document\n  console.log('Creating a new document...');\n  const newDocument: MindooDocument = await db.createDocument({\n    type: 'secret-note',\n    title: 'Top Secret Plan',\n    content: 'Phase 1: Encrypt everything. Phase 2: Distribute. Phase 3: Profit.',\n    tags: ['secret', 'plan', 'e2e']\n  });\n  console.log(`Document created with ID: ${newDocument.id}`);\n  console.log('Initial document content (decrypted client-side):', newDocument.content);\n\n\n  // 2. Update the document\n  console.log('Updating the document...');\n  await newDocument.update(currentDoc => {\n    currentDoc.content = 'Phase 1: Encrypt everything. Phase 2: Securely distribute. Phase 3: Achieve peace.';\n    return currentDoc;\n  });\n  console.log('Document updated.');\n\n  // 3. Retrieve and verify the document\n  console.log('Retrieving the document...');\n  const retrievedDocument = await db.getDocument<MindooDocument>(newDocument.id);\n  if (retrievedDocument) {\n    console.log(`Retrieved document ID: ${retrievedDocument.id}`);\n    console.log('Retrieved document title:', retrievedDocument.title);\n    console.log('Retrieved document content (decrypted client-side):', retrievedDocument.content);\n    console.log('This data was never exposed in plaintext to any server.');\n  } else {\n    console.error('Failed to retrieve document.');\n  }\n\n  // In a real scenario, you would connect to a sync server to exchange\n  // encrypted changes with other clients, e.g., await db.sync();\n}\n\ninitializeAndUseMindooDB().catch(console.error);","lang":"typescript","description":"This quickstart initializes MindooDB, creates a new end-to-end encrypted document, updates it, and then retrieves and decrypts the content, demonstrating basic client-side data operations without exposing plaintext to a server."},"warnings":[{"fix":"Review the latest documentation and changelog with each update. Be prepared for breaking API changes and plan for refactoring.","message":"MindooDB is currently in 'Alpha software' status (v0.0.17). This means APIs are highly unstable and may change significantly without notice between minor or even patch versions. It is not recommended for production use where stability is critical.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"Avoid using in applications with high-stakes security requirements until a stable version is released and audited. Exercise caution and consider a security review before any critical deployment.","message":"While MindooDB offers end-to-end encryption, its alpha status means the cryptographic implementations and overall security posture are still under development and unvetted. It should not be assumed production-ready or fully secure until it reaches a stable release and undergoes independent security audits.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always check the `peerDependencies` in the `package.json` and follow the environment-specific installation guides (e.g., 'React Native setup guide' mentioned in the README) to ensure all necessary native modules and polyfills are properly linked.","message":"MindooDB relies on several peer dependencies, particularly for React Native environments (e.g., `react-native-automerge-generated`, `react-native-quick-crypto`, `expo-standard-web-crypto`). Failure to install these correctly can lead to runtime errors or missing functionality in specific environments.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For Node.js, ensure you import from the main package: `import { MindooDB } from 'mindoodb';`. For web browsers, explicitly import from `mindoodb/browser`.","cause":"Attempting to use the browser-specific build of MindooDB (e.g., `mindoodb/browser`) in a Node.js environment, which lacks browser globals like `navigator`.","error":"ReferenceError: navigator is not defined"},{"fix":"Ensure `npm install react-native-automerge-generated` (and other relevant peer deps like `react-native-quick-crypto`) has been run, and follow any platform-specific linking instructions for React Native.","cause":"A required peer dependency, specifically `react-native-automerge-generated` for React Native environments, is not installed or correctly linked.","error":"Error: Cannot find module 'react-native-automerge-generated'"},{"fix":"For Node.js, ensure you are on a recent version (>=15.0.0) or provide a suitable polyfill. For Expo/React Native, verify that `expo-standard-web-crypto` is installed and correctly configured as per its documentation.","cause":"The runtime environment (e.g., older Node.js versions, certain browser contexts, or improperly configured Expo/React Native) lacks a global `crypto.subtle` API, which is essential for MindooDB's cryptographic operations.","error":"TypeError: WebCrypto is not defined"}],"ecosystem":"npm"}