Add Draft JS to Lexical migration documentation

[thegreatercurve]

Following @trueadm announcement tweet, we had a few questions about how users could migrate from DraftJS to Lexical. The APIs are fairly incompatible, but providing some guidance on how best to migrate could help drive adoption.

[carlosbaraza]

It'd be nice to know how Facebook would approach this migration. Two things I can think of that would be really useful:

• A library to convert from a Draft state to Lexical state.
• A migration guide to create a plugin from a custom Draft plugin.

[dacox]

Following @trueadm announcement tweet, we had a few questions about how users could migrate from DraftJS to Lexical. The APIs are fairly incompatible, but providing some guidance on how best to migrate could help drive adoption.

@thegreatercurve Can you clarify - are they "fairly compatible", or actually "fairly incompatible"? The surface level onChange API looks similar, but I'm worried about entities, etc.

[trueadm]

@dacox Unfortunately, Lexical and Draft are not compatible when comparing the data models of both. Lexical has a tree structure that represents its state, which can be seen as like a DOM-like structure. Draft has a block + entities based structure, which is based on offsets. It's possible to build functions can that convert from Draft format to Lexical format, but in many cases where custom functionality as been built in Draft – it will have to be re-written for Lexical.

The other key difference is that Lexical isn't based on React, like Draft is. Lexical has its own reconciler and although you can use Lexical's DecorateNode to render React into a Lexical node, these are constrained to being non-text based – and we mark them as contenteditable="false" to ensure this is the case. It was always a bad design to "fight" Lexical for selection. So instead, some things can be ported to be custom nodes that extend Lexical's DecoratorNode, others will need to extend ElementNode and TextNode.

We'll look into writing a comprehensive set of guides around these concepts and hopefully this can help the folks out there migrate from Draft! :)

[tubbo]

@trueadm If that's true, could one convert to html first and then import that html into lexical? We persist the draftjs format in our DB so if we wanted to move to lexical, rewriting everything by hand just wouldn't be an option. There are tools for the conversion process on both sides, so at least for more simple jobs I think this could work out.

[jlombardo-tableau]

Is there any ETA on this migration guide?

[meatnordrink]

We'll look into writing a comprehensive set of guides around these concepts and hopefully this can help the folks out there migrate from Draft! :)

I think that, even if "migration" will basically mean re-writing everything, just having a section in the docs that recaps the info available in this thread (whether migrating is possible, why/why not, where and how the APIs differ) would be helpful, at the very least for people considering whether to even try switching to Lexical from draft-js.

[comp615]

A library to convert from a Draft state to Lexical state.

Carlos' assessment seems spot on and wanted to add a +1. Although you obviously have to rewrite the plugins, having a skeleton data state migrator would be extremely helpful in enabling people to update to Lexical from Draft (instead of going through markdown or something more complex / lossy). It's hard to figure out how we'd go about getting onto Lexical right now since we store the raw DraftJS JSON.

[alfaproject]

We also persist the blocks in our database so a migration isn't exactly easy right now. If there was a way to convert from blocks and to blocks then we could at least have an easier migration path. Does anyone know if anyone made utility functions for that?