LinkedRecords is a Backend-as-a-Service you can connect to directly from your single-page application - no backend code required. Authorization is built into the data model, and real-time collaboration (CRDT/OT) works out of the box.

• Documentation: linkedrecords.com · Getting Started Guide
• SDKs on npm: @linkedrecords/browser (core SDK) · @linkedrecords/react (React hooks)
• License: MIT

Run the backend locally with Docker (includes PostgreSQL and a mock OIDC provider with one-click test accounts):

curl -fsSLO https://raw.githubusercontent.com/wolfoo2931/linkedrecords/main/docker-compose.yml
docker compose up

The server is then available at http://localhost:6543. Connect to it from your app:

npm install @linkedrecords/browser

import LinkedRecords from '@linkedrecords/browser';

const lr = new LinkedRecords(new URL('http://localhost:6543'), {
  client_id: 'linkedrecords-dev',
  redirect_uri: window.location.origin + '/callback',
});

// To check if the user is authenticated:
// const isAuth = await lr.isAuthenticated();

// To start the login flow (e.g., on a button click):
// lr.login();

// Create a record only you can access - share it later by creating facts
const todo = await lr.Record.createKeyValue(
  { title: 'Buy groceries', done: false },
  [['$it', 'isA', 'Todo']],
);

Using React? The Getting Started Guide builds a complete collaborative todo app with @linkedrecords/react hooks.

You can think of LinkedRecords as a bucket where anyone can sign up and insert data. As long as you don't share this data with other users or groups, only you can access what you've written into it.

In theory, any user could use the LinkedRecords API directly to write and retrieve data. However, this would be inconvenient - just as you wouldn't expect your users to write SQL queries, you wouldn't expect them to interact with the LinkedRecords API. A LinkedRecords app is a specialized frontend that hides the API and provides a convenient user interface for accomplishing their tasks.

In the traditional SQL world, inconvenience isn't the only reason you don't let users access the database directly - authorization concerns are an even stronger reason. With LinkedRecords, this is no longer an issue: authorization is built directly into the API. This requires a small mindset shift: Instead of defining universal authorization rules in the backend for all records, the user who inserts a data record specifies who can read it.

For the LinkedRecords API, simplicity, flexibility, and a decoupled architecture are the main qualities we strive to achieve.

• Simplicity: The API should not have many endpoints or methods; instead, it consists of a few fundamental building blocks.
• Flexibility: The few available endpoints can be composed to support a variety of use cases. The baked in authorization model should allow to implement different authorization use cases (RBAC, ...).
• Decoupled: LinkedRecords should be decoupled from the single-page applications which use it as data storage

Think of it as SQL you can call directly from your React app without worrying about permissions; it is easier to read than SQL and provides live updates.

LinkedRecords is configured via environment variables. See tables below, or the full configuration reference with examples for every deployment mode.

The environment variables in this section are all optional if the configuration described in the section "Public Client Mode" are provided.

If LinkedRecords runs in confidential client mode, then a session token will be stored in an HttpOnly cookie. From a security standpoint this is considered the suggested method. However, this is not possible if the LinkedRecord server and the frontend do not share the same domain. Across different domains the cookie becomes a third-party cookie, so this mode cannot be used.

In case the single-page application is hosted on a different domain than the LinkedRecords server, the single-page application has to store the access token in the browser. In this scenario the following environment variables need to be configured.

If S3 is configured it will be used to store blob record values. If it is not configured they will be stored in the PostgreSQL database. It is recommended to configure S3.

Redis is only needed when running multiple LinkedRecords instances behind a load balancer, so real-time updates reach clients connected to other instances.

Contributions are welcome - see CONTRIBUTING.md for details.

Prerequisites: Node.js v24 and a PostgreSQL database (configured via the PG* environment variables, see CONTRIBUTING.md; alternatively set USE_PGLITE=true to use an embedded database).

npm install
npm start              # Build and run the server on port 6543
npm test               # Run unit/component tests
npm run wdio           # Run end-to-end tests
npm run lint           # ESLint

The documentation website lives in docs/:

cd docs && npm install && npm run dev

The chart below shows the performance of core operations as the database grows. This is automatically updated after each merge to main.

The load test simulates a realistic document management scenario. Each createDocument operation creates a blueprint of 8 records (7 KeyValueRecords + 1 LongTextRecord) including the document content, collaborator/reader groups, comments, references, and configuration. The fetchDocuments operation lists all documents for a user, while fetchDocument retrieves a single document with all its associated records.

The test simulates a multi-tenant environment with three users:

• User 1 continuously creates documents (in the current test configuration 5,000 iterations).
• User 2 is the "user under test" who creates one document for every 10 documents User 1 creates, up to 300 documents. At 300 documents, the creation of documents for this user stops.
• User 3 creates documents occasionally (every 1,000 iterations)

The x-axis shows the total number of documents in the database (owned by all users combined). The y-axis shows the response time in milliseconds.

What's being measured: