lofipod is a TypeScript library for building apps that work offline first and
sync user-owned data to a SOLID Pod in the background.
It is aimed at developers who want local-first UX, background sync, and
portable data. Applications read and write local state first, while lofipod
stores canonical remote data as interoperable RDF resources in the user's Pod.
A SOLID Pod is a user-controlled web data store. RDF is the standard data format used for the canonical remote representation.
The intended first run is local only.
Start with the framework-agnostic core package, define one entity, create an engine, and perform local CRUD without setting up Pod sync first. After that, use the in-repo demo to prove the same local-first flow through a small CLI.
The shortest path is:
- Read docs/QUICKSTART.md for the minimal local API.
- Run the local todo demo workflow from demo/README.md.
- Verify that workflow with
npm run test:demo. - Add browser or Node persistence when needed.
- Attach Pod sync later when you want remote durability and replication.
Many apps need fast local reads, offline writes, and a UI that keeps working without a network connection.
At the same time, some apps also need data portability and open storage rather than keeping everything in an app-specific backend.
lofipod is for that combination. It keeps the application local-first while
syncing canonical remote data to interoperable RDF resources in a user's Pod.
lofipod is for developers building apps such as:
- notes and journals
- task and planning tools
- personal knowledge tools
- privacy-sensitive productivity apps
It is most useful when you want:
- local-first behaviour by default
- normal reads and writes to stay local
- background sync rather than manual sync as the main flow
- user-owned data stored in an open format
- a small framework-agnostic core rather than a full app framework
- Define your entity types in TypeScript.
- Define how each entity maps to RDF.
- Save and read entities through a local-first API.
- Keep application queries and lists local.
- Sync canonical RDF resources and replication data to the user's Pod in the background.
- Recover compatible data from existing canonical Pod resources when needed.
- not a realtime collaborative editor
- not a general-purpose RDF database
- not a general sync engine for arbitrary graphs
- not a general-purpose schema evolution system
- not a UI framework
- not a system that expects Pod-side querying for normal application reads
lofipod is early, but it is no longer only a design repo.
The project currently includes:
- a core public API for defining entities and vocabularies
- typed RDF terms and helper exports for entity mapping
- environment-specific entrypoints for browser and Node adapters
- canonical graph projection and rehydration
- mocked sync coverage for canonical Pod files and replication logs
- explicit bootstrap import from canonical Pod resources on first attach
- focused Community Solid Server integration tests
- a small CLI demo app that acts as an end-to-end regression harness
Expect the API to keep evolving while the core model is being proven.
npm install lofipodCurrent entrypoints:
lofipod: framework-agnostic corelofipod/browser: browser-specific adapters such as IndexedDBlofipod/node: Node-specific adapters such as SQLite and the Solid adapter
The root lofipod entrypoint is intentionally environment-neutral. Do not
expect createIndexedDbStorage(...), createSqliteStorage(...), or
createSolidPodAdapter(...) to come from the root package.
Node.js 24+ is the current supported runtime target for development and CI.
The smallest useful flow is:
- define a vocabulary
- define one entity type and its RDF mapping
- create an engine
- save and read entities locally
- run the in-repo local demo if you want a concrete first proof of value
- attach Pod sync when you want remote durability and replication
See docs/QUICKSTART.md for a small end-to-end example using
defineVocabulary(...), defineEntity<T>(...), and createEngine(...).
For the repo's explicit first proof of value, use one local data directory and run:
npm run demo -- task add --data-dir /tmp/lofipod-demo --id task-1 --title "Write docs" --due 2026-04
npm run demo -- task get task-1 --data-dir /tmp/lofipod-demo
npm run demo -- task list --data-dir /tmp/lofipod-demo
npm run demo -- task done task-1 --data-dir /tmp/lofipod-demo
npm run demo -- task get task-1 --data-dir /tmp/lofipod-demo
npm run demo -- task delete task-1 --data-dir /tmp/lofipod-demo
npm run demo -- task list --data-dir /tmp/lofipod-demoEach command reopens the same SQLite-backed local store, so this sequence is
the restart-safe local-first proof path. npm run test:demo exercises the
same workflow automatically. The demo commands, scope notes, and file mapping
are documented in demo/README.md.
- docs/QUICKSTART.md: first-use example
- docs/API.md: current public API direction
- docs/ADR.md: accepted architectural decisions
- docs/TESTING.md: testing approach, commands, and coverage guardrails
- docs/PLANS.md: delivery slices
- docs/WIP.md: current implementation state and open questions
- demo/README.md: exact local demo commands, app layout, and ontology seed
There are good browser storage tools and good Solid authentication and Pod client tools, but there is still a gap between them.
Most local-first libraries do not target SOLID Pods as a durable backing store, and most Solid tooling does not provide a local-first sync engine with an application-facing developer experience.
lofipod is an attempt to cover that missing middle ground without becoming a
large framework.
Common commands:
npm test: fast unit and mocked-sync suitenpm run test:coverage: source coverage report with enforced thresholdsnpm run test:demo: CLI demo regression harness for the documented local-first proof pathnpm run test:pod: focused Community Solid Server integration suitenpm run verify: format, lint, types, and the default fast suite
See docs/TESTING.md for the intended test layering and current coverage expectations.