For AI agents: the complete documentation index is available at https://silt-db.dev/llms.txt, the full documentation bundle is available at https://silt-db.dev/llms-full.txt, and this page is available as Markdown at https://silt-db.dev/contributing/development.md.

    Development

    Silt is an npm workspace monorepo. Runtime source is plain JavaScript with handwritten TypeScript declarations. There is no library transpilation step. Use Node.js 24 or newer for development.

    git clone https://github.com/startupjs/silt-db.git
cd silt-db
npm ci
npm run typecheck
npm test
npm run test:sharedb

    Start with AGENTS.md and the architecture overview. CLAUDE.md imports the same agent guidance so there is one maintained set of instructions.

    Find the right module

    AreaLocation
    SQL generation, JSON semantics, operator supportpackages/compiler/src/
    Collections, cursors, transactions, connection ownershippackages/sqlite/src/
    Node, better-sqlite3, and Expo executionpackages/sqlite/src/drivers/
    ShareDB snapshots, operation history, and live query dependenciespackages/sharedb/src/
    Optional PCRE2 extensionpackages/native/
    Regression suites and captured MongoDB reference inputstest/
    Executable examplesexamples/
    Actual Teamplay and Expo applicationsintegration/
    This public Rspress sitedocs/, rspress.config.ts, theme/
    Historical investigations, benchmark data, and verification logsinternal/

    The repository uses main. Library releases are deliberate maintainer actions; pushes update CI and the documentation site.

    Change an operator

    First reproduce the intended JSON behavior on the chosen MongoDB server. Add a regression that distinguishes the old and new behavior, then update the compiler and its public declarations where needed. Selection, filtering, expressions, grouping, and joins must remain inside SQLite. A JavaScript evaluator or a JavaScript SQLite function is not a fallback path.

    Index optimization must preserve the exact SQL predicate after narrowing candidate rows. If an index cannot safely represent a value or path, keep the correct SQL scan. Explicit rejection is preferable to silently accepting unsupported MongoDB semantics.

    Update the relevant compatibility, pipeline, expression, or update reference with the regression. Use the testing guide to choose the affected suites.

    Change a driver or transaction

    Preserve borrowed-connection ownership, serialized operations, rollback, and the lifetime of transaction handles. Keep Node imports out of portable, Expo, compiler, and shared entrypoints. Changing a .js export also requires checking its declaration and the conditional exports map.

    Driver tests use multiple handles and real persistence. Run the relevant Node driver tests first. An Expo bundle proves import compatibility; actual browser or device execution is a separate check.

    Work on documentation

    npm run docs:dev
npm run docs:typecheck
npm run docs:build
npm run docs:preview

    Open the URL printed by Rspress. The site is served from /, matching the custom domain https://silt-db.dev, so local development and production use the same page and asset paths.

    docs/_nav.json defines the top navigation. Each section's _meta.json defines its learning order. Put common tasks in guide/, API and capability detail in reference/, and integrations or engine-specific detail in advanced/. Keep internal working notes and raw logs outside docs/.

    Use relative Markdown links for pages inside the site. Link to repository source with complete GitHub URLs. npm run docs:build checks local page links and heading anchors, generates static HTML, and emits llms.txt, llms-full.txt, and Markdown copies for agents. Check the production preview when changing navigation, the base path, or the theme.

    Before submitting a change

    Run the focused regressions, typecheck for API changes, and the documentation build for documentation changes. Use broader integration tests when the changed behavior crosses those boundaries. Record what actually ran and any skipped environments; a captured reference or an iOS bundle is not a live server or native device result.

    See testing for commands and release preparation for packaging and deployment.