Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update platform docs intro so following it actually works #61341

Draft
wants to merge 1 commit into
base: trunk
Choose a base branch
from

Conversation

stokesman
Copy link
Contributor

@stokesman stokesman commented May 3, 2024

Keeping this drafted at least until #60087 lands because that takes care of much of this.

What?

Updates the intro.md with some critical things that were missing for a workable build to be produced when following the guide. Among those:

  • Recommends the React variant as part of npm create vite@latest as without this JSX won’t work by default and react dependencies won’t be installed. The React variant also installs some other nice defaults like eslint with react related plugins.
  • Details that @wordpress/block-library expects IS_GUTENBERG_PLUGIN and how to provide it as without this a runtime error makes for a broken app.
  • Adds a missing style import @wordpress/block-editor/build-style/content.css
  • Changes style imports to assign them to a variable so they can also be passed to styles prop of BlockCanvas as without this various things won’t be styled in the canvas.

Less important changes:

  • Adds ?raw param to style imports to avoid Vite ever trying to process them. This has the effect of making Vite not inject them automatically and thats why they are also rendered into a style tag within the Editor component.
  • Puts registerCoreBlocks() within a conditional so it won’t execute during HMR and cause errors (they are non-fatal but they sure clutter up the console). A minor downside to this is it requires an extra package @wordpress/blocks.
  • Specifies to update src/App.jsx instead of index.jsx because it’s what’ll exist when using the React variant and it also means the createRoot/render bits can be removed from the code sample.

Along with that there were a some minor edits to either fix typos or try to make it read a little better.

Why?

To hopefully approach the expectation that following this guide will produce a working example in 10 minutes. From the docs homepage:
image
You’ll probably go well over 10 minutes if you have to discover how to fix all the gotchas you'll hit by following the guide as is.

How?

I think this is mostly covered in What. I may add some review comments.

Testing Instructions

cd platform-docs
npm install
npm run start

Ensure it all looks good.

Copy link

github-actions bot commented May 3, 2024

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: stokesman <presstoke@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@stokesman stokesman marked this pull request as draft May 3, 2024 01:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
1 participant