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.

Sign up for GitHub

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

Platform Docs: Update intro.md #60087

Closed
wants to merge 4 commits into from
Closed

Platform Docs: Update intro.md #60087

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fe80dfe
Update intro.md with instructions for configuring build tooling, sett…
michalczaplinski Mar 21, 2024
8bd0748
Update intro.md with Gutenberg Block Editor setup
michalczaplinski Mar 21, 2024
f6dd539
Merge branch 'trunk' into update/platform-docs-intro
michalczaplinski May 13, 2024
015a33f
Use the react preset and split into main.jsx and Editor.jsx
michalczaplinski May 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 84 additions & 42 deletions platform-docs/docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,82 +4,124 @@ sidebar_position: 1

# Getting Started

Let's discover how to use the **Gutenberg Block Editor** to build your own block editor in less than 10 minutes**.

Let's discover how to use the **Gutenberg Block Editor** to build your own block editor in less than 10 minutes.

## What you'll need

- [Node.js](https://nodejs.org/en/download/) version 20.10 or above.
- We're going to be using "vite" to setup our single page application (SPA) that contains a block editor. You can use your own setup, and your own application for this.
- [Node.js](https://nodejs.org/en/download/) version 20.10 or above.
- We're going to be using "vite" to setup our single page application (SPA) that contains a block editor. You can use your own setup, and your own application for this.

## Preparing the SPA powered by Vite.

First bootstrap a vite project using `npm create vite@latest` and pick `Vanilla` variant and `JavaScript` as a language.
First bootstrap a vite project using `npm create vite@latest` and pick `React` variant and `JavaScript` as a language.

Once done, you can navigate to your application folder and run it locally using `npm run dev`. Open the displayed local URL in a browser.
Once done, you can navigate to your application folder, install dependencies
using `npm install` and run it locally using `npm run dev`. Open the displayed local URL in a
browser.

## Installing dependencies

To build a block editor, you need to install the following dependencies:

- `@wordpress/block-editor`
- `@wordpress/block-library`
- `@wordpress/components`
- `@wordpress/block-editor`
- `@wordpress/block-library`
- `@wordpress/components`

## JSX

We're going to be using JSX to write our UI and components. So one of the first steps we need to do is to configure our build tooling, By default vite supports JSX and and outputs the result as a React pragma. The Block editor uses React so there's no need to configure anything here but if you're using a different bundler/build tool, make sure the JSX transpilation is setup properly.

## Side note: `process.env.IS_GUTENBERG_PLUGIN`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should fix this in Gutenberg directly. We should make sure that it works by default without setting this rather than having npm consumers learn about this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, that makes sense! I see that this is actually a GB issue because it should have been replaced at build time and we even have a lint for it.

Do you have any idea why that would not be the case?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that the version of the packages published to npm does not have the value of process.env.IS_GUTENBERG_PLUGIN replaced. E.g.: You can check here: https://unpkg.com/browse/@wordpress/[email protected]/build/resolvers.js

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@michalczaplinski yes, that's fine, because Gutenberg also consumes the built npm packages like any other app. The problem is that it shouldn't cause an error by default but should assume "false" if you don't define the variable.


The Gutenberg block editor reads from the `process.env.IS_GUTENBERG_PLUGIN`
variable for example in the `@wordpress/block-library` package. This feature
is used to distinguish the code that is part of the Gutenberg block editor
[plugin](https://wordpress.org/plugins/gutenberg/) and the code that is part of
WordPress Core.

For our purposes, as we're building a standalone block editor that is completely
separate from WordPress, we want to set this variable to `false`.

When using Vite, we can do it by updating the `vite.config.js` file. It should
now look like this:

```js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

// https://vitejs.dev/config/
export default defineConfig( {
plugins: [ react() ],
define: {
'process.env.IS_GUTENBERG_PLUGIN': JSON.stringify( false ),
},
} );
```

If you are using Webpack, you can use the
[DefinePlugin](https://webpack.js.org/plugins/define-plugin/) to accomplish the
same thing.

## Bootstrap your block editor

It's time to render our first block editor.
It's time to render our first block editor. Update your `main.jsx` file with the following code:

- Update your `index.jsx` file with the following code:
```jsx
import { createElement, useState } from "react";
import { createRoot } from 'react-dom/client';
import {
BlockEditorProvider,
BlockCanvas,
} from "@wordpress/block-editor";
import { registerCoreBlocks } from "@wordpress/block-library";
import React from 'react';
import ReactDOM from 'react-dom/client';
import { Editor } from './Editor.jsx';

import { registerCoreBlocks } from '@wordpress/block-library';

// Default styles that are needed for the editor.
import "@wordpress/components/build-style/style.css";
import "@wordpress/block-editor/build-style/style.css";
import '@wordpress/components/build-style/style.css';
import '@wordpress/block-editor/build-style/style.css';

// Default styles that are needed for the core blocks.
import "@wordpress/block-library/build-style/common.css";
import "@wordpress/block-library/build-style/style.css";
import "@wordpress/block-library/build-style/editor.css";
import '@wordpress/block-library/build-style/common.css';
import '@wordpress/block-library/build-style/style.css';
import '@wordpress/block-library/build-style/editor.css';

// Register the default core block types.
registerCoreBlocks();

function Editor() {
const [blocks, setBlocks] = useState([]);
return (
/*
ReactDOM.createRoot( document.getElementById( 'root' ) ).render(
<React.StrictMode>
<Editor />
</React.StrictMode>
);
```

Next, create an `Editor.jsx` file and add the following code:

```jsx
import { useState } from 'react';
import { BlockEditorProvider, BlockCanvas } from '@wordpress/block-editor';

export function Editor() {
const [ blocks, setBlocks ] = useState( [] );
return (
/*
The BlockEditorProvider is the wrapper of the block editor's state.
All the UI elements of the block editor need to be rendered within this provider.
*/
<BlockEditorProvider
value={blocks}
onChange={setBlocks}
onInput={setBlocks}
>
{/*
<BlockEditorProvider
value={ blocks }
onChange={ setBlocks }
onInput={ setBlocks }
>
{ /*
The BlockCanvas component renders the block list within an iframe
and wire up all the necessary events to make the block editor work.
*/}
<BlockCanvas height="500px" />
</BlockEditorProvider>
);
*/ }
<BlockCanvas height="500px" />
</BlockEditorProvider>
);
}

// Render your React component instead
const root = createRoot(document.getElementById("app"));
root.render(<Editor />);
```

That's it! You now have a very basic block editor with several block types included by default: paragraphs, headings, lists, quotes, images...
You can remove all the other files in the `src` directory, we only need
`main.jsx` and `Editor.jsx`.

That's it! You now have a very basic block editor with several block types
included by default: paragraphs, headings, lists, quotes, images...
Loading