Migrating from Collaboration Kit to Signals

Topics become objects you own. Collaboration Kit resolves a topic from a string identifier, and any two connections that pass the same string share data. Shared signals have no such registry: two users share state when they hold a reference to the same signal instance. Replacing topics therefore means introducing an application-scoped object that maps identifiers to signal instances. See Replace Topics with a Signal Registry.

Connections become bindings. Collaboration Kit activates a TopicConnection when a component is attached and deactivates it on detach. Signals do the same thing implicitly: Signal.effect() and every bind*() method are active only while their owner component is attached. There’s nothing left to open or close.

Subscribers become effects. Instead of registering a MapSubscriber or ListSubscriber and reacting to change events, you read signal values inside an effect or a binding, and the framework re-runs it when a value changes.

The engine disappears. There’s no CollaborationEngine singleton, no service init listener, and no ConnectionContext. Signal writes are thread-safe and dispatch UI updates themselves, so background threads write to a signal directly instead of going through a SystemConnectionContext.

Clustering and session serialization support for shared signals are being built next. Both are specified together in platform#8703, because they’re the same problem: a shared signal’s state currently can’t leave the node it was created on. Until that lands, an application that needs either should stay on Collaboration Kit, which supports both.

That limitation is the one thing that can stop a migration outright, and it shows up as two symptoms.

platform#8703 covers the cluster event log for the first and the serialization strategy for the second. Adding a reaction there is worth doing if you need it.

Don’t try to work around it by writing every change through a shared database and polling it back: that reproduces neither the latency nor the transactional guarantees, and it gives up the reason to use signals in the first place.

Everything else in Collaboration Kit can be migrated. What You Have to Build Yourself covers the parts that cost real work, and the smaller API-level differences worth knowing before starting.

Cross-user updates only reach the browser immediately if server push is enabled. Both products need it, but only one of them arranges it: Collaboration Kit turns push on by itself. When a topic connection activates in a UI that has neither push nor polling, it sets PushMode.AUTOMATIC and logs a warning. Signals never touch the push configuration.

An application that relied on that default has no @Push annotation anywhere, and migrating removes the thing that was compensating. The result is easy to miss in testing: everything still works for the user making a change, and other users see it only the next time they interact with the page. Add @Push before migrating, while Collaboration Kit is still there to make the two behave the same.

To confirm which case you’re in, look for the Collaboration Kit warning in the server log at startup, or set setAutomaticallyActivatePush(false) and check that real-time updates still arrive.

Collaboration Kit and signals can run side by side in the same application, and even in the same view: they’re independent libraries with no shared state. Collaboration Kit still builds against the Flow version this guide targets, so the incremental path is available rather than theoretical. Migrating one view, or one feature within a view, at a time is safe. A practical order is chat first (self-contained), then avatars, then forms, and the low-level topic API last.

Collaboration Kit’s expiration timeout drops topic data after a quiet period. The registry needs to do this explicitly, otherwise every document ever opened stays in memory for the lifetime of the application.

Count the views currently using a state and discard it when the count reaches zero. Expose the two halves as a symmetric pair:

Tie the pair to the lifetime of the view with whenAttached(). The handler runs on every attach, and the Registration it returns runs on the matching detach:

Written by hand with a detach listener alone, this is a mistake that’s easy to make and hard to see. A view that’s detached and attached again — navigating back to a retained view, a component moved between layouts, a dialog reopened — then releases more times than it retains. The count reaches zero while the view is still open, the state is dropped, and the next user to open the same document gets a fresh DocumentState and silently stops sharing anything with them. A @PreserveOnRefresh view surviving a reload gets the opposite: it is re-attached without an intervening detach, so a hand-written pair retains twice and never releases. whenAttached() handles both, clearing any live cleanup before running the handler again.

PresenceManager writes the local user into the topic with EntryScope.CONNECTION, so the entry vanishes when the connection deactivates. Signals need the two halves written explicitly, on attach and on detach:

insertLast() returns an InsertOperation whose signal() is available immediately, before the insert is confirmed. That signal is the handle used to remove the entry later, in the same way a ListKey is in Collaboration Kit.

The cleanup covers more than it looks like it does. Flow sends an unload beacon when the page is hidden, closes the UI on the server, and detaching the UI runs the cleanup for the whole component tree — so closing a browser tab removes the entry within about a second, the same as Collaboration Kit.

AvatarGroup binds directly to a list signal. Map each collaborator entry to an AvatarGroupItem:

The outer map() turns the list of entry signals into a list of mapped signals, and bindItems() reads each one. An entry changing its own value re-renders that avatar; the list changing shape re-renders the group.

To exclude the local user’s own avatar — what setOwnAvatarVisible(false) does — filter the stream on the collaborator identifier and create a separate Avatar component for the local user.

Model the shared form state as an immutable record and hold it in a single SharedValueSignal. Each field binds to one property through map() for reading and updater() for writing:

This is the whole of the value-synchronization half of CollaborationBinder. updater() performs a compare-and-set update that retries on conflict, so two users editing different properties concurrently both keep their edits.

Compared with the Collaboration Kit version, several restrictions disappear:

The type restrictions change shape rather than disappearing. Collaboration Kit needs an explicit serializer for values it can’t convert to JSON; a shared signal needs the same values to be Jackson-serializable. Instead of registering a serializer, store the JSON-friendly representation in the record — typically an entity identifier — and resolve it when populating the field:

Two details matter here. The identifier is nullable, because the write callback stores null whenever the field is cleared, so the lookup needs a guard. And a plain form.map(value → personService.findById(value.supervisorId())) is derived from the whole record, which means the backend call runs again on every change to any property, including each keystroke in an unrelated text field. Caching the identifier first cuts the chain: the outer cached signal isn’t invalidated while the identifier produces the same value, so the lookup runs only when the supervisor actually changes.

A multi-select field needs its element type named, which is what CollaborationBinder::forField used the two-class forField(field, Set.class, Role.class) form for. Pass a Jackson TypeReference instead:

The overload exists on SharedValueSignal, SharedListSignal, and SharedMapSignal, and on SharedNodeSignal.asValue(), asList(), and asMap(). Use the Class form for everything else — it’s shorter, and only a parameterized type needs the type reference.

A single record for the whole form is the simplest option and the one to reach for first. Use a SharedMapSignal keyed by property name — the structure Collaboration Kit uses internally — when properties are added dynamically, or when a form is large enough that per-property change granularity matters:

Read the entry defensively as above: a key that no user has written yet has no entry signal.

Keep Binder for validation and for writing to the entity. The fields are bound to signals for synchronization and to the binder for validation at the same time:

Collaboration Kit stores one entry per user, property, and sub-field. Model it the same way, in a list rather than a map, so that each user only ever adds and removes their own entry and no user can clear another user’s entry:

The Java artifact, vaadin-field-highlighter-flow, is already on the classpath: vaadin-core depends on it. Collaboration Kit declares it as provided, so removing Collaboration Kit doesn’t take it away.

What removing Collaboration Kit does take away is the frontend module. The @NpmPackage and @JsModule annotations for @vaadin/field-highlighter sit on FieldHighlighterInitializer, and Flow’s production build only includes frontend resources declared on classes your code actually reaches. Collaboration Kit reached that class; once it’s gone, nothing does. A call to executeJs referring to the custom element by name isn’t a reference Flow can see, so the module is left out of the production bundle. The failure is delayed and confusing — development mode works, because the module is in the default bundle, and customElements.get('vaadin-field-highlighter') is undefined only in production.

Reach the class the same way Collaboration Kit does, by extending it:

init() is protected static, so a subclass can call it. Using it in place of a hand-written executeJs call matters for a second reason: it runs the initialization on every attach, not once. A field that’s detached and re-attached — a @PreserveOnRefresh view surviving a reload, a cached view, a field moved between layouts — comes back as a fresh client-side element without the focus observer, and a one-shot call would leave that user’s focus silently unreported from then on.

Once initialized, the field fires vaadin-highlight-show and vaadin-highlight-hide. Both carry a fieldIndex in the event detail: 0 for a simple field, and the index of the focused sub-field for a composite such as DateTimePicker. Add and remove the local user’s entry from those events rather than from focus and blur listeners, so that composite fields are handled correctly:

Remove by matching the property and the user rather than by remembering the signal returned when the entry was inserted. Two vaadin-highlight-show events can arrive without a hide between them — moving between the date and time parts of a DateTimePicker is exactly that case — and a single remembered handle would lose the earlier entry, leaving a highlight on the field that nobody can clear. Collaboration Kit sweeps every entry matching the user and the property for the same reason:

An effect sends the current editors of the field to the component whenever the shared list changes. Filter out the local user, the same way CollaborationBinder does — you highlight other people’s focus, not your own:

The ObjectMapper is tools.jackson.databind.ObjectMapper, the Jackson 3 mapper the framework uses, and Element::executeJs accepts the resulting node directly. The four properties are what the component expects. colorIndex selects the outline color from the same --vaadin-user-color-* palette the avatars use, so highlights and avatars agree on who is who.

That’s the whole mechanism. It handles several simultaneous editors on one field and sub-field indexes, because the component does, and it looks the same as Collaboration Kit because it is the same component.

For a form with more than a couple of fields, wrap the three parts in one helper that takes the field, the property name, and the shared list, and call it per binding.

If you’d rather not add the dependency, the same shared state drives a plain CSS outline. This loses the name tags and the sub-field precision, but needs no JavaScript:

CollaborationMessagePersister exists because Collaboration Kit owns the message store and needs a hook into yours. With signals, your code owns both sides, so persistence is a plain write-through: save first, then insert what the backend returned.

Load the history where the state is created, in the registry:

insertAllLast() inserts the whole history in a single transaction, so other users see one atomic change instead of one per message. The timestamp-based FetchQuery protocol has no equivalent and isn’t needed: nothing polls the backend, because the signal is the shared copy.

A key that no user has written yet has no entry signal, so guard peek().get(key) against null. Where Collaboration Kit uses a conditional replace() to avoid overwriting another user’s initialization, SharedMapSignal offers putIfAbsent(), which CollaborationMap does not have.

SharedMapSignal has its own verifyKey(), but it isn’t the counterpart of CollaborationMap::replace: it checks that a key maps to a particular child signal, not that the entry holds a particular value. Compare values with replace() or verifyValue() on the entry signal itself. verifyHasKey() and verifyKeyAbsent() cover the presence of a key.

Use get() inside effects, computed signals, and transactions, where it registers a reactive dependency. Use peek() everywhere else — click listeners, initialization code, background jobs. Calling get() outside a reactive context throws IllegalStateException.

The important difference is the handle. Collaboration Kit identifies an entry by ListKey and asks the list to operate on it; shared signals give you the child SharedValueSignal, which is both the handle and the way to read and write the value.

Rendering a list is where the difference pays off. A subscriber that adds, removes, and reorders components by hand collapses into one binding:

Components aren’t recreated when an item value changes, only the bindings inside them are updated.

ListOperation conditions become verifications inside a transaction. The transaction is rejected as a whole if a verification fails:

A transaction is scoped to one shared signal and its children. Reaching into a second, independent shared signal from inside one throws, as described in Step 1.

Use verifyChild() before updating an entry that another user might have removed in the meantime. Collaboration Kit’s conditions are per-operation; a signals transaction can verify several conditions and apply several changes atomically, which is more expressive.

These migrate, and the guide shows how, but Collaboration Kit does the work for you and signals don’t. Nothing here is blocked; each one is code you write instead of code you configure. Budget for them.

Smaller gaps, but each one is a place where a direct translation compiles and then behaves differently.

Some Collaboration Kit features look framework-specific but carry over unchanged, and it’s worth not budgeting time for them: