@meldkit/angular

Angular bindings for the MeldKit SDK: end-to-end encrypted real-time collaboration, as signals.

npm install @meldkit/angular yjs

Angular 20, 21 and 22. Standalone, signal-based, and zoneless-ready — nothing here depends on change detection noticing a mutation.

Connect

import { bootstrapApplication } from '@angular/platform-browser';
import { provideMeldKit } from '@meldkit/angular';

bootstrapApplication(App, {
  providers: [
    provideMeldKit({
      room: 'doc-1',
      roomKey: 'a3f1…', // never sent to MeldKit
      auth: '/api/meldkit/token',
    }),
  ],
});

auth points at your own endpoint. It is POSTed { room } and answers { token }, minted server-side with your project's secret key — a secret key can't be in a browser. The room fetches a token before it connects, and again before every reconnect, so a session outlives the short-lived token it started with.

Whatever injector you add provideMeldKit() to owns the connection: put it on a route and the socket closes when the route does.

Pass a function when the connection depends on something reactive. It runs in an injection context, and re-running it only re-opens the socket if what the transport is built from actually changed:

provideMeldKit(() => ({
  room: inject(DocumentStore).current().id,
  roomKey: KEY,
  auth: '/api/meldkit/token',
}));

There is an element form too, for when the room arrives as an input:

<meldkit-room room="doc-1" [roomKey]="key" auth="/api/meldkit/token">
  <app-board />
</meldkit-room>

Everything inside it — projected content included — injects the same room.

Read and write

import { Component } from '@angular/core';
import { injectMeldKit, injectSyncedList } from '@meldkit/angular';

@Component({
  selector: 'app-todos',
  template: `
    @for (entry of todos.entries(); track entry[0]) {
      <label>
        <input
          type="checkbox"
          [checked]="entry[1].done"
          (change)="todos.update(entry[0], { done: !entry[1].done })"
        />
        {{ entry[1].text }}
      </label>
    }
  `,
})
export class Todos {
  readonly meldkit = injectMeldKit();
  readonly todos = injectSyncedList<Todo>('todos');
}

| Helper | What it gives you | | ------------------------ | ------------------------------------------------------------------ | | injectMeldKit() | the room: status(), error(), readOnly(), doc(), client() | | injectSyncedMap(name) | a shared record — entries(), get, set, update, remove | | injectSyncedList(name) | the same, ordered, plus push, insert, move | | injectSharedText(name) | a shared text field — see below | | injectOthers() | everyone else's presence, each with clientId folded in | | injectMyPresence() | your own presence, and a merging setter |

They read the connection from DI, so like every inject() in Angular they belong in a field initializer or a constructor. entries() is a signal: put it straight in a template and Angular does the rest.

update(id, patch) merges per field, so two people editing different fields of the same item both win. set(id, value) replaces the whole entry. Use injectSyncedList whenever order is visible — an ordered CRDT is what stops two concurrent inserts from landing in different orders on different screens.

Presence

readonly me = injectMyPresence<Presence>();

onPointerMove(event: PointerEvent) {
  this.me.update({ pointer: { x: event.offsetX, y: event.offsetY } });
}

update merges; awareness itself only replaces wholesale, which is the helper every app was writing by hand. Set initialPresence in your options and it is published on connect and after every reconnect — awareness state is ephemeral, so a client that announces itself once vanishes from everyone else's screen after the first dropped connection and never comes back.

Shared text

<textarea meldkitText="body"></textarea>

That is the whole binding: no [value], no (input), no ngModel. Two people typing in the same paragraph merge character by character, each local edit goes back as the smallest change that explains it, and a remote edit moves your caret with the text instead of dropping it at the end.

Don't also bind [value] or ngModel to the same element — two owners of one value is exactly the fight that loses keystrokes.

For an element the directive can't sit on, injectSharedText(name) gives you text(), replace() and a bind(element) that does the same job.

Typing your shapes once

Augment one interface and every helper is typed:

// meldkit.config.ts — imported once, anywhere in your app
declare module '@meldkit/angular' {
  interface MeldKitTypes {
    Presence: Presence;
    Collections: { todos: Todo };
  }
}

Then injectMyPresence() is your presence and injectSyncedList('todos') is a list of Todo, with the collection name checked against the map — a typo is a compile error instead of an empty list. Entirely optional; explicit type arguments keep working either way.

Ready-made UI

@meldkit/angular-ui has the presence bar, the connection indicator, remote carets and live cursors, against the same presence shape.

Errors

error() is a MeldKitError with a code. Two worth handling explicitly:

• key-error — the socket is healthy and the document is unreadable. This is a wrong room key, and it is the one failure a status dot alone will not tell you about.
• config — your token endpoint answered 501, which is what it should do before it has a secret key. A first-run problem, not an auth failure; <meldkit-setup-notice> renders the four steps out of it.