Evolu is a local-first platform and TypeScript library.
For detailed information and usage examples, please visit evolu.dev.
The Evolu community is on GitHub Discussions, where you can ask questions and voice ideas.
To chat with other community members, you can join the Evolu Discord.
Evolu monorepo uses the latest Node.js LTS release and
pnpm. With nvm, install the Node.js version selected by
.nvmrc:
nvm installInstall Corepack independently of Node.js and enable the pnpm version pinned in
package.json:
npm install --global --min-release-age=1 corepack@latest
corepack enable pnpmInstall dependencies:
pnpm installThe playgrounds in apps/web, the examples, and the integration, bundle and
E2E tests load packages/sqlite-wasm/wasm/sqlite3.wasm. It is never committed,
so download it:
pnpm sqlite-wasm:downloadIt takes the wasm from the published @evolu/sqlite-wasm and writes it only if
its sha256 is the pinned one. The playgrounds and tests fail when the file is
missing or is not the pinned wasm. The examples don't check it, because they are
templates to copy.
When no release holds the pinned wasm yet, the download says so. Then build it
with an emsdk that
has Emscripten 6.0.3 installed and activated, as the
@evolu/sqlite-wasm README
describes:
EMSDK=/path/to/emsdk node packages/sqlite-wasm/scripts/build-wasm.mtsInstall Playwright browsers for local test and verify runs:
pnpm playwright:installRun the browser install step again after Playwright updates or if the browser cache was removed.
The tests of packages/sqlite-core, which pnpm test runs, need
clang with its llvm-profdata and llvm-cov, make,
unzip and zip, on Linux also OpenSSL's development headers and clang's shared
AddressSanitizer runtime, and network access the first time, to fetch the
pinned SQLite source and expo-sqlite releases. Those of packages/react-native
also need Ruby and CMake, and pnpm check:packages, which packs that package
with the C it vendors, needs what
packages/react-native/scripts/vendor-native.mts lists for vendoring.
Build scripts
pnpm build- Build packages (required once after clone/pull for IDE types)pnpm build:docs- Build doc (required once after clone/pull)pnpm build:web- Build docs and web
Web build notes
- On macOS Tahoe, you may need to raise Launch Services limits too (shell
ulimit -nis not enough):sudo launchctl limit maxfiles 262144 262144
Start dev
pnpm dev- Start relay and web serverspnpm relay- Start relay server only (for mobile development)pnpm ios- Run iOS example (startrelayfirst)pnpm android- Run Android example (startrelayfirst)
Examples
Note: Examples use the local packages. To try them with the published packages, run
pnpm examples:toggle-depsand choose production; choose development to switch back.
pnpm examples:react-nextjs:dev- Dev server for React Next.js examplepnpm examples:react-vite-pwa:dev- Dev server for React Vite PWA examplepnpm examples:svelte-vite-pwa:dev- Dev server for Svelte Vite PWA examplepnpm examples:vue-vite-pwa:dev- Dev server for Vue Vite PWA examplepnpm examples:build- Build all examples
Linting
pnpm lint- Run all linterspnpm lint:oxlint- Lint code with Oxlintpnpm lint:sherif- Lint monorepo structure with Sherif
Formatting
pnpm format- Write Prettier formatting changespnpm format:check- Check Prettier formatting without writing changes
Testing
pnpm playwright:install- Install browsers required by Playwright-based Vitest projectspnpm test- Run all unit, integration, bundle, and documentation-example testspnpm test:node "<test-file-or-glob>"- Run selected native Node tests with coveragepnpm test:unit- Run all unit tests with test-file durations and coveragepnpm test:integration- Run Node.js and browser integration testspnpm test:integration:nodejs- Run Node.js integration tests without source coveragepnpm test:integration:browsers- Run browser integrations in Chromium with coverage and in Firefox and WebKit for compatibilitypnpm test:bundle- Run production bundle and tree-shaking testspnpm test:bundle:update- Rebuild common and regenerate bundle-size snapshotspnpm test:jsdoc- Compile and run documentation examplespnpm test:sqlite-wasm- Run the@evolu/sqlite-wasmunit and Node.js integration tests, failing below 100% line, branch or function coveragepnpm test:sqlite-core- Run the tests of Evolu's own SQLite core, with its C tests under AddressSanitizer and UndefinedBehaviorSanitizer, once with hardware and once with software crypto, failing below 100% line, branch or function coverage of its TypeScript and of the C its host compilespnpm test:react-native-sqlite- Run@evolu/react-native's Node.js tests, among them its binding conformance suite on the core's Node-API mirror of the binding, also under AddressSanitizer and UndefinedBehaviorSanitizer, failing below 100% line, branch or function coverage of its scripts,src/sqlite, the shared driver, and the core'snode/binding.candnode/module.cpnpm test:react-native-hermes- Run, on macOS, the conformance suite and the Hermes tests on the JSI adapter under the Hermes React Native pins, with AddressSanitizer and UndefinedBehaviorSanitizer and then ThreadSanitizer, failing below 100% line, branch or function coverage of the adapterpnpm check:sqlite-wasm- Check that the generated@evolu/sqlite-wasmC API and constants match their pins and metadata
Unit, integration, and bundle test suites randomize execution order and print a seed that reproduces the same ordering. See Randomized test order for the rationale and replay commands.
See the testing convention for test placement, runner, and assertion guidance.
Verify
pnpm verify- Run all checks (build, lint, test) locally; CI runs them on pull requests and pushes to main
main must always be ready to run publicly on evolu.dev. After checks pass,
the Release workflow automatically deploys the
website built from current main, using workspace packages and the pinned
SQLite wasm built by CI. The web build does not install Evolu packages from npm.
- Small, ready website fixes can go directly to
main: commit, push, CI, deploy. - Keep unfinished changes in feature branches. Open a PR and merge when the whole change is ready to run publicly, including any affected playgrounds.
- Published package changes need a changeset (
pnpm changeset). Complete the npm release separately after merging; it may follow the web deployment.
Web deployment and npm publication are independent. The playgrounds and API reference can therefore include changes before those changes are available on npm. This delay is intentional and keeps website fixes independent of package releases.