What is the correct way to apply document migrations?

3

Thanks for sharing. It’s indeed an important problem to solve if you want local-first solution.

There is this post that explains it’s possible to create updates that never have precedence over other updates (which is exactly what we are looking for): Initial offline value of a shared document - #6 by dmonad

But there is this big warning: “However, once a client initializes state slightly differently, you will break all documents.”

Does someone know what “initializes state slightly differently” means? I’d like to understand why and how a document can be broken with a custom client ID.

Could it be dangerous if all document changes applied in a migration function were done with a client ID of zero?

I’d like to implement something like this:

function applyDocumentMigration(doc: Y.Doc) {
  const clientID = doc.clientID
  doc.clientID = 0

  const version = doc.getMap().get("version")

  switch (version) {
    case 0:
      // ... apply migrations from v0 to v1
    case 1:
      // ... apply migrations from v1 to v2
  }

  doc.clientID = clientID
}
1 Like