WAIT — Slowing — last commit 9mo ago

• Last commit 9mo ago
• 14 active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 9mo ago
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

WatermelonDB is a reactive SQLite-backed database framework for React and React Native apps that solves the performance cliff when scaling to thousands of records. Rather than loading all data into JavaScript memory, it lazily queries SQLite on a native thread and automatically re-renders UI components when underlying data changes—ensuring instant app launches and smooth performance even with tens of thousands of records. Monorepo structure with source in root src/ directory (JS/TS core), native bridges in separate language folders (src/objc/, src/java/, src/cpp/), docs-website/ as standalone Docusaurus 3.7.0 site, and examples/ for runnable samples. Models are declarative (schema definitions), queries are observable (RxJS integration optional), and adapters abstract SQLite across platforms (iOS native, Android JNI, web, Node.js).

React and React Native developers building complex data-heavy applications (e.g., project management tools like Nozbe itself, CRM apps, task managers) who need both offline-first sync capability and the ability to scale from hundreds to tens of thousands of records without JavaScript memory explosion.

Highly mature and production-ready. Powers Nozbe (in production since 2017) and many commercial apps listed in the README. Extensive CI/CD via GitHub Actions (.github/workflows/ci.yml), comprehensive changelog (CHANGELOG.md, CHANGELOG-Unreleased.md), TypeScript/Flow typing throughout, and active maintenance with docs-website built on Docusaurus 3.7.0. Clear SECURITY.md and CONTRIBUTING.md indicate strong governance.

Low risk for mature projects, moderate risk for bleeding-edge features. Dependencies are well-managed (core is native/JS only, docs use standard Docusaurus stack), but the codebase is complex with Objective-C (215k lines), C++ (75k), Java (36k) for native bridging—iOS/Android native changes require corresponding expertise. Breaking changes are documented in CHANGELOG; the sync protocol and schema migrations have stability guarantees given production usage.

Active development on multiplatform support and sync stability. CHANGELOG-Unreleased.md tracks upcoming features. Recent work spans native adapter improvements (Objective-C++, Java native interfaces), TypeScript migration (noted in file list), and docs-website expansion. GitHub Stale Issues workflow (.github/stale.yml) suggests active issue triage.

Clone and install: git clone https://github.com/Nozbe/WatermelonDB.git && cd WatermelonDB && npm install (Node 18+ required per Gemfile/package.json). For docs-website: cd docs-website && npm install && npm start runs local Docusaurus dev server on http://localhost:3000.

Daily commands: Dev: npm install && npm run dev (inferred—check root package.json). Docs: cd docs-website && npm start. Build library: npm run build. Tests: npm test (CI runs via .github/workflows/ci.yml). Each platform (iOS, Android, web) has specific build steps in respective doc files.

• README.md — Entry point explaining WatermelonDB's reactive, async-first database design for React/React Native with offline-first sync capabilities—essential for understanding the project's core mission.
• docs-website/docs/docs/Setup.md — Primary onboarding document covering installation and database initialization—every contributor must understand the setup flow before working on core features.
• docs-website/docs/docs/Schema.md — Defines the data modeling abstraction and table schema declarations—foundational for understanding how data is structured throughout the codebase.
• docs-website/docs/docs/Model.md — Documents the Model class and CRUD operations—critical for understanding the ORM-like abstraction layer that all database operations depend on.
• docs-website/docs/docs/Query.md — Covers the query DSL and observation API—essential for understanding how reactive queries work and how data flows to React components.
• docs-website/docs/docs/Sync/Intro.md — Introduces the offline-first sync architecture—key differentiator of WatermelonDB and critical for understanding the distributed data consistency model.
• docs-website/docs/docs/Implementation/Architecture.md — High-level architectural overview explaining layers, adapters, and design decisions—necessary for anyone contributing to core infrastructure.

• Documentation Site (Docusaurus) (React, Docusaurus, MDX, Markdown) — Serves comprehensive guides covering setup, schema definition, CRUD operations, queries, sync architecture, and advanced features
  • Failure mode: Build fails if markdown syntax is invalid or referenced files are missing; site becomes inaccessible if deployment fails
• Setup & Installation Guide (Markdown documentation) — Provides step-by-step instructions for integrating WatermelonDB into React and React Native projects

Add a new documentation page to the guides

1. Create a new markdown file in the appropriate subdirectory under docs-website/docs/docs/ (e.g., docs-website/docs/docs/Advanced/ for advanced topics) (docs-website/docs/docs/Advanced/NewFeature.md)
2. Add the new page entry to the sidebar navigation in docs-website/sidebars.js to expose it in the documentation menu (docs-website/sidebars.js)
3. Run 'yarn start' in the docs-website directory to preview the page locally before deployment (docs-website/package.json)

Update the changelog and version

1. Document breaking changes and new features in docs-website/docs/docs/CHANGELOG.md (docs-website/docs/docs/CHANGELOG.md)
2. Add unreleased changes to CHANGELOG-Unreleased.md at the repository root (CHANGELOG-Unreleased.md)
3. Update version number in docs-website/package.json when preparing a release (docs-website/package.json)

Add a new implementation detail document

1. Create a new markdown file under docs-website/docs/docs/Implementation/ to document internal architecture decisions (docs-website/docs/docs/Implementation/NewComponent.md)
2. Reference the new document from docs-website/docs/docs/Implementation/Architecture.md to maintain discoverability (docs-website/docs/docs/Implementation/Architecture.md)
3. Update docs-website/sidebars.js to add the new page to the Implementation section (docs-website/sidebars.js)

Expand sync documentation with backend/troubleshooting guides

1. Add troubleshooting steps to docs-website/docs/docs/Sync/Troubleshoot.md or backend implementation details to Sync/Backend.md (docs-website/docs/docs/Sync/Troubleshoot.md)
2. Link to FAQ at docs-website/docs/docs/Sync/FAQ.md for common sync-related issues (docs-website/docs/docs/Sync/FAQ.md)
3. Reference new sections from the main Sync/Intro.md page to create a cohesive sync documentation journey (docs-website/docs/docs/Sync/Intro.md)

• Docusaurus 3.7.0 — Static site generation for comprehensive, searchable documentation with MDX support for interactive examples and strong React ecosystem integration
• React 18.2.0 & React DOM — Documentation site needs interactive components and aligns with WatermelonDB's target audience of React/React Native developers
• MDX (React Components in Markdown) — Enables embedding live code examples and interactive components directly in documentation pages for better learning
• Babel & ESLint — Transpilation and linting ensure code quality and compatibility across the monorepo's JavaScript/TypeScript codebase

• Documentation-heavy repository with minimal code artifacts in the visible file list

  • Why: WatermelonDB is a mature library; the main value is in comprehensive documentation and examples rather than exposing raw source code
  • Consequence: Developers must refer to external GitHub source or npm package to inspect the actual implementation; this repo functions as a documentation and configuration hub

• Monorepo structure with separate docs-website package and root configuration

  • Why: Allows documentation to be versioned and deployed independently from the core library while maintaining a single source of truth
  • Consequence: Slightly more complex build setup but cleaner separation of concerns and easier CI/CD workflows

• Docusaurus as the primary documentation tool rather than custom static site

  • Why: Reduces maintenance burden, provides built-in versioning, search, and plugin ecosystem out of the box
  • Consequence: Relies on Docusaurus release cycles; major version upgrades (e.g., v2 to v3) require migration effort

• Does not include the compiled WatermelonDB source code—this is the documentation and example repository only
• Does not implement a real-time streaming database engine (WatermelonDB is reactive but not real-time in the WebSocket sense)
• Does not provide built-in user authentication or access control—syncing with custom backend required
• Does not support distributed consensus or multi-master replication—single-writer (backend) architecture

Native development: iOS changes require Xcode and CocoaPods; Android changes require Java/NDK. Sync protocol: Custom offline-first sync requires compatible backend; docs-website/docs/ must be read carefully. SQLite adapters: Each platform (iOS, Android, web, Node) has a different SQLite binding—not all features are equivalent (e.g., web uses sql.js, Node uses better-sqlite3). TypeScript migration: Codebase is mixed Flow and TS; check .flowconfig and tsconfig if present. Performance gotchas: Observers on large result sets can be memory-intensive; schema migrations must be idempotent.

• Lazy loading / On-demand querying — Core WatermelonDB feature—data is not loaded until explicitly queried, keeping app startup instant regardless of total database size
• Observable streams (RxJS) — WatermelonDB queries return Observables; understanding subscriptions and stream operators is essential for reactive component updates
• SQLite WAL (Write-Ahead Logging) — Underlying SQLite uses WAL mode for concurrency; understanding this explains why WatermelonDB can query on background threads safely
• Native bridge / JNI (Java Native Interface) / JSI (JavaScript Interface) — WatermelonDB queries run on native threads via JNI/JSI, not JavaScript—critical for understanding performance guarantees and debugging slowness
• Offline-first sync protocol — WatermelonDB implements custom sync semantics (not REST); understanding pushes, pulls, and conflict resolution is required for backend integration
• Schema migrations — WatermelonDB requires explicit migration definitions for any database schema change; migrations must be idempotent and versioned
• Relation and foreign keys in SQL — WatermelonDB models declare relations (hasMany, belongsTo); understanding SQL joins and foreign key constraints is essential for query design

• realm/realm-js — Alternative mobile-first reactive database (Realm) for React Native with similar lazy-loading and sync goals but different architecture (object store vs SQL)
• firebase/firebase-js-sdk — Cloud-hosted real-time database alternative (Firebase) offering automatic sync and offline support but less control over schema and queries
• getsentry/sentry — Not direct competitor but recommended observability/error tracking companion for WatermelonDB production apps
• Nozbe/nozbe — Official Nozbe Teams app that powers WatermelonDB in production, demonstrating real-world usage patterns and best practices
• redux/redux — Complementary state management; WatermelonDB can be used alongside Redux for non-database app state, or as a replacement for the 'persistence layer' part of Redux middleware

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow for docs-website Docusaurus builds

The .github/workflows directory exists but there's no dedicated workflow for the docs-website Docusaurus project (v3.7.0). Given that docs are critical for developer onboarding in an open-source DB project, adding automated builds, link validation, and deployment checks would prevent broken documentation from reaching users. This is especially important since the docs cover complex features like Migrations, Sync, and Architecture.

• [ ] Create .github/workflows/docs.yml with steps to: install Node >=18, build docs-website with 'npm run build'
• [ ] Add link validation step using docusaurus or broken-link-checker for docs-website/docs output
• [ ] Add spellcheck/linting for Markdown files in docs-website/docs/docs/* directories
• [ ] Configure workflow to fail if build fails, preventing merged PRs that break docs

Add missing documentation for WatermelonDB.podspec and iOS/React Native setup

WatermelonDB.podspec exists at root level (indicating native iOS support) but there's no corresponding documentation file in docs-website/docs/docs/ for iOS-specific setup, CocoaPods integration, or React Native native module linking. This gap makes it difficult for iOS developers to get started despite the framework explicitly supporting React Native.

• [ ] Create docs-website/docs/docs/GettingStarted/iOS-Setup.md documenting WatermelonDB.podspec usage
• [ ] Document linking native WatermelonDB module for React Native iOS projects (pod install, build phases)
• [ ] Add troubleshooting section for common iOS build issues (Xcode linking, Swift compatibility)
• [ ] Link this new doc from docs-website/docs/docs/GettingStarted/index.md or equivalent

Implement test coverage for database adapter implementations referenced in Architecture.md

docs-website/docs/docs/Implementation/DatabaseAdapters.md exists, suggesting multiple database adapters are supported, but the file structure doesn't show corresponding integration or adapter tests. Given that adapters are critical for supporting different platforms (React, React Native, different backends), adding adapter-specific test suites with clear patterns would help contributors add new adapters safely.

• [ ] Create tests/adapters/ directory structure (if not present) mirroring src/adapters layout
• [ ] Add unit tests for each adapter in docs-website/docs/docs/Implementation/DatabaseAdapters.md (e.g., SQLite, etc.)
• [ ] Document adapter interface contract with test examples so new contributors know what to test when adding adapters
• [ ] Update CONTRIBUTING.md with 'Adding a New Adapter' section referencing adapter test patterns

• Add TypeScript types to any remaining Flow-typed modules in src/—check .flowconfig for coverage gaps and convert a file at a time, starting with src/react/ (commonly used, high impact).
• Expand docs-website/docs with a beginner's guide to setting up offline sync with a Node.js backend; current docs assume some backend knowledge, and a worked example would reduce setup friction.
• Add missing test files for native adapter abstraction layer (likely src/adapter/*.js)—check CI output in .github/workflows/ci.yml to see which files lack coverage, then write Jest tests for adapter interface contract.

The WatermelonDB documentation website has a generally acceptable security posture with minor concerns. The primary risks relate to dependency management practices rather than active vulnerabilities. The use of modern frameworks (Docusaurus 3.7.0, React 18.2.0) is positive, but lack of pinned versions and explicit security scanning in the CI/CD pipeline are areas for improvement. The project maintains responsible disclosure practices as outlined in SECURITY.md. Recommendations focus on implementing stricter dependency version pinning, automated security audits in CI/CD, and explicit SRI validation for any externally-loaded resources.

• Medium · Outdated Docusaurus and Dependencies — docs-website/package.json. The docs-website package.json uses Docusaurus 3.7.0 with React 18.2.0. While these are relatively recent, the caret (^) version specification for @mdx-js/react (^3.0.0), clsx (^1.2.1), and prism-react-renderer (^2.1.0) allows automatic minor/patch updates that could introduce breaking changes or security issues without explicit testing. Fix: Use exact versions (remove ^ and ~) for all dependencies, or implement automated dependency scanning with tools like Dependabot. Regularly audit dependencies using 'npm audit' and keep Node.js at or above version 18.0 as specified.
• Low · Missing npm Audit Configuration — .github/workflows/ci.yml (referenced but not provided). The package.json does not include npm audit scripts or security audit configurations. No lock file vulnerability scanning is explicitly defined in the CI/CD pipeline configuration visible in the repository. Fix: Add 'npm audit' and 'npm audit fix' scripts to the build pipeline. Consider adding audit-level configurations to package.json to fail builds on high/critical vulnerabilities.
• Low · Permissive Node.js Version Requirement — docs-website/package.json. The engines field specifies 'node': '>=18.0', which is permissive and allows any version above 18.0. Older minor versions may contain security patches not yet deployed in newer majors. Fix: Specify a more restrictive Node.js version range, e.g., '>=18.16.0 <21.0.0', to ensure patches are applied. Use .nvmrc file to lock to a specific LTS version for development.
• Low · No Subresource Integrity (SRI) Configuration — docs-website/docusaurus.config.js (not provided, but inferred). The Docusaurus configuration does not show explicit SRI hash validation for CDN-loaded resources. If scripts or stylesheets are served from CDNs, they could be vulnerable to compromise. Fix: Review docusaurus.config.js and ensure all CDN resources include SRI hash attributes. Use webpack and bundler security best practices to validate all loaded resources.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Nozbe/WatermelonDB shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Nozbe/WatermelonDB repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Nozbe/WatermelonDB.

What it runs against: a local clone of Nozbe/WatermelonDB — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Nozbe/WatermelonDB | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 303 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Nozbe/WatermelonDB. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Nozbe/WatermelonDB.git
#   cd WatermelonDB
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Nozbe/WatermelonDB and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Nozbe/WatermelonDB(\\.git)?\\b" \\
  && ok "origin remote is Nozbe/WatermelonDB" \\
  || miss "origin remote is not Nozbe/WatermelonDB (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs-website/docs/docs/Setup.md" \\
  && ok "docs-website/docs/docs/Setup.md" \\
  || miss "missing critical file: docs-website/docs/docs/Setup.md"
test -f "docs-website/docs/docs/Schema.md" \\
  && ok "docs-website/docs/docs/Schema.md" \\
  || miss "missing critical file: docs-website/docs/docs/Schema.md"
test -f "docs-website/docs/docs/Model.md" \\
  && ok "docs-website/docs/docs/Model.md" \\
  || miss "missing critical file: docs-website/docs/docs/Model.md"
test -f "docs-website/docs/docs/Query.md" \\
  && ok "docs-website/docs/docs/Query.md" \\
  || miss "missing critical file: docs-website/docs/docs/Query.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 303 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~273d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Nozbe/WatermelonDB"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.