Has anyone been able to replicate Plate Playground?

[zacharykatsnelson]

Hi everyone,

I've spent a few hours trying to replicate this: https://platejs.org, even replicating the code-sandbox.io itself and trying to run it locally. Yet I always get some error and it breaks completely.

Has anyone been able to find a way to actually get it to work? If so, could you kindly share your repository? I'm not sure if I'm missing something from the documentation but all I am trying to do is replicate it locally and build from there.

Any assistance would be greatly appreciated. 🙏

[dylans]

Are you able to clone the repo and run something like yarn, yarn build, and yarn docs. That works for me.

[zacharykatsnelson]

@dylans do you mean cloning the code-sandbox repo?

[dylans]

No, this repo. It’s a monorepo and contains everything for the playground, mostly in the docs folder.

[zacharykatsnelson]

I seem to only be able to find this file: https://github.com/udecode/plate/blob/main/docs/docs/playground.mdx . Not sure where to find the playground files.
But ideally I would like to just integrate it into in an isolated Next.js or React Application and build from there.

[zbeyens]

Docs are indeed not perfect and I'm open to PRs. Can you share the error messages you have?

[zacharykatsnelson]

@zbeyens The errors are as follows:

Could not find a required file.
  Name: index.js
  Searched in: /home/wizard/slate-react-test/src

This is fixed by changing index.tsx -> index.js. However, I then get this error:
Module not found: Can't resolve './config/mentionables' in '/home/wizard/slate-react-test/src'

Trying to fix this (by removing/altering the mentionables) just leads to more and more errors on various things. It seems the entire repo is broken in fundamental ways.

[zacharykatsnelson]

@zbeyens I would love to make some PRs and help out on the documentation side but I can't do that if I'm unable to replicate simple examples from what you've built 🤷‍♂️

[dylans]

"It seems the entire repo is broken in fundamental ways." That's simply not true, fwiw.

Yes, there's a barrier to entry as there is with any reasonably ambitious project.

The docs part of the website is setup in a way to support the features of the website rather than being a pure set of examples to copy/paste or clone. It's meant for discoverability and a quick test harness and as mentioned you can at least get it up and running with a few yarn commands, but it's not isolated.

Similarly, code sandbox requires some quirks to get things working in that environment, so simply copying that isn't ideal.

@zbeyens we probably should just create a quick hello world repo that users can replicate to try things out that matches a typical dev workflow. That said, it took me maybe 15 minutes to get things up and running the first time so it never occurred to me that this was a barrier to entry.

[zacharykatsnelson]

That would be great @dylans
Please link me once you do that. Until then, there is far too much friction and barriers to starting up an example like Plate Playground or really any example other than the most basic one.

Documentation is really the heart of any open-source project and improving it so that it can (at the very least) replicate examples on the site should be a very high priority imo. It is not only my opinion, others have reached out telling me that if I want proper documentation to start with to look at other projects like TipTap or Remirror.

If it truly does take you only 15 minutes to start up... then I'm sure this won't be an issue for too long?

[zbeyens]

Thanks for the feedback, I'll try to increase its priority.

Could you reproduce the "Getting Started" section?

[zacharykatsnelson]

Hey @zbeyens I can manage up until we get to Basic Plugins. That's when stuff begins to break -- I was able to get through it but it took me over half an hour to understand how to import and configure everything.

Another recommendation I can give if I may -- just to standardise everything... is replace
() => <Plate />
To something like:

import React from 'react';
import { Plate } from '@udecode/plate'
// any other imports

function MyApp(){
   return <Plate />
}

export default MyApp

This may be slightly longer but it's far worth it for the clarity and plug-and-play functionality.

[GuiBibeau]

👋 Hello, I thought I might drop in quickly here.

First of all I want to thank you for this great package! It's really powerful and I see the potential. I have been researching various rich text editor to be used in Next.js for internal work I am doing at Vercel and I have had difficulty on boarding on some of the more complex features you provide. I have some feedback to share (as a dev who spends my days prototyping and exploring packages):

Good parts:

Getting to the basic editor is super easy and simple to do. It took me 5 minutes by reading the docs. The repo is amazingly modular and it's clear you are building this to be flexible.

Stuff I would love to see

The starting tutorial should bring users to a point where they understand how to build a toolbar or bubble toolbar:

• In many examples constants seem to be used but are not shown in the example
• reverse engineering the playground would take hours and if I want to integrate in a lightweight repo I can't clone then clear out what I don't need

In this current state the barrier to entry is not user friendly, some help would be appreciated in at least making a tool bar render without having to reverse engineer or clone to repo.

[kevcmk]

This is a fantastic project, but I want to echo the above sentiments. Most of the examples from the documentation do not stand on their own-- most examples reference CONFIG, VALUES, and seemingly-hello-world essential code housed in the sandbox. Instead of making the maintainers publish an opinionated hello-world repo, perhaps just point at some well-executed deployments of Plate?

[zacharykatsnelson]

To be honest @kevcmk and @gbibeaul ... if you want a good editor with proper documentation I would use TipTap. The documentation on this project is just ... non-workable. The time you would lose just trying to integrate any functionality into your project is simply not worth it until they fix the documentation.

[dylans]

And my point was you’re comparing an open source project with a commercial model and dedicated full time people with one with a much smaller team working on it in their spare time and not trying to commercialize it.

We heard your feedback, we’ll work on it as we can, we don’t have infinite time and resources, and frankly it took me maybe 5-10 min to setup plate the first time so yes I was surprised by your feedback.

But then instead of giving us time to work on better docs, you respond to follow up feedback telling people they shouldn’t use Plate until we fix our docs to your satisfaction and act as if we’re not listening to you because we cannot immediately address your perspective, leading us to need to spend more time responding to the same feedback. It’s the kind of approach that frankly demotivates open source maintainers.

When I first started using Plate and Slate in 2020 there were things that bugged me. Instead of complaining I started raising PRs. Same with Slate. Now I’m a co-maintainer of both, just trying to do my part to make them better as time permits.

Complaining is easy. Giving useful feedback is better. Doing something about it adds real value to the ecosystem.

[zacharykatsnelson]

That's fair. I would be happy to help out and submit a few PRs but can't do that until I can get something more than a basic editor going without running into issues.

[zacharykatsnelson]

And by the way, I am a huge fan of what Plate is and by no means am saying it is worse/better than another project. In fact, this is the text editor I preferred to start with for my project because the feature set is very impressive and the functionality looks great. Ofc I also appreciate that you are completely open-source.

I do believe that once the documentation is sorted you may see an explosion of more activity for the project since I think it is the main thing holding it back.

[zbeyens]

It's just a matter of priority.

Plate scope is too big for one person so my strategy was to plant the tree (core) and many seeds (plugins), counting on the long term to get valuable contributions. I may be mistaken but I don't think we'll get a lot of value from those who are blocked by the current docs (you may be the exception).

In other words, our first target users are the ones who will dig a bit into the code, rather than those using Plate as a finished product and not planning to contribute. Note that Slate has almost no marketing efforts for a similar reason.

[kevcmk]

I agree with @zacharykatsnelson. I think their criticism is in good spirit and their ultimate aim is in support of what you're doing here. I will personally be sticking with Plate -- I believe this project is headed in the right direction.

@zbeyens As much as possible don't take Github Issues too personally. Keep up the good work, we appreciate what you're doing here

[egwoo]

I went thru the same struggle in the past couple days myself, but got the playground working on its own with some work.

Unfortunately I didn't see the CONTRIBUTING.md until after my effort, but following it, I was able to build the docs site that hosts the playground.

I got the playground working on its own here. I cloned the repo, copied the playground source into an empty react app, and then started hacking away at it until it worked. In the notes of the README, I jotted down the extra deps and tweaks I had to make to get the code to compile in Typescript.

Hope this is helpful.

As a note, I have also found some difficulty following the docs and examples as well, but I do understand how hard it is to maintain a project and appreciate what y'all have accomplished.

[zbeyens]

We now have a working example of the playground, head over https://github.com/udecode/plate-playground, which is linked to our sandbox https://codesandbox.io/s/github/udecode/plate-playground

See also /examples/apps/next