Platform Docs: Update `intro.md` #60087

michalczaplinski · 2024-03-21T17:31:01Z

I tried following the intro.md and ran into a few problems that I'm fixing here:

We need to import React from "react" when using JSX with Vite because by default it's using the React 16 flavour of the JSX transform: https://vitejs.dev/guide/features.html#jsx. Alternatively we can use a JSX helper:
```
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  esbuild: {
    jsxInject: `import React from 'react'`,
  },
})
```
We need to define the process.env.IS_GUTENBERG_PLUGIN variable. Otherwise, the editor will crash. I added a brief instruction on how to do that.
Just some minor reformatting 🙂.

…ing IS_GUTENBERG_PLUGIN to false and fixing errors

youknowriad · 2024-03-22T07:36:56Z

platform-docs/docs/intro.md

@@ -30,13 +30,39 @@ To build a block editor, you need to install the following dependencies:

 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`


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.

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?

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

@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.

github-actions · 2024-03-22T07:37:08Z

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: michalczaplinski <[email protected]>
Co-authored-by: youknowriad <[email protected]>
Co-authored-by: oandregal <[email protected]>
Co-authored-by: swissspidy <[email protected]>
Co-authored-by: talldan <[email protected]>
Co-authored-by: stokesman <[email protected]>

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

youknowriad · 2024-03-22T07:37:47Z

platform-docs/docs/intro.md

 ```jsx
-import { createElement, useState } from "react";
+import React, { useState } from "react";


This is fine but I kind of thought that vite uses the automatic JSX config by default. it's not the case?

There are more details in https://v2.vitejs.dev/guide/features.html#jsx but TL;DR is that it's not the case out of the box. We can also do one of those things

use the React plugin https://www.npmjs.com/package/@vitejs/plugin-react

add sth like those lines to the vite config:
export default defineConfig({ esbuild: { jsxInject: `import React from 'react'` } })

Let's keep it simple and just import React like you did for now.

If you create the Vite app with the "React" / "JavaScript" config instead of "Vanilla" / "JavaScript" config, this works automatically. The vite config becomes:

import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' // https://vitejs.dev/config/ export default defineConfig({ plugins: [react()], });

Actually, starting with the "Vanilla" vite config cerates a few issues (jsx, react), why not change the docs to suggeste starting with the "React" vite config? Those things will be solved.

If starting with "Vanilla" then react and react-dom aren’t added as dependencies so it seems like that would warrant mentioning them in "Installing dependencies" section.

I'd favor instructing to use the "React" variant. It seems like it simplifies the instructions and provides a better starting place as it adds some helpful packages like eslint with react-related plugins.

youknowriad · 2024-03-22T07:38:37Z

I really appreciate that you're actually following the tutorial, I guess so far it has been only me

youknowriad · 2024-04-24T10:35:17Z

platform-docs/docs/intro.md

+
+export default defineConfig({
+  define: {
+    "process.env.IS_GUTENBERG_PLUGIN": JSON.stringify(false),


I actually don't think we should add this to the docs, it doesn't make sense for third-party developers and shouldn't be required.

I looked a bit into this and found that a similar request for the @wordpress/warning package was addressed by creating a SCRIPT_DEBUG global. There was a conversation about an alternative approach that was similar to what I was thinking to fix this specific use case for the block library.: process?.env?.IS_GUTENBERG_PLUGIN ?? false.

My understanding is that we cannot use import.meta unless we ship our scripts as modules. Both vite and webpack favor this approach these days, but people find it problematic with many libraries and end up defining the process.env themselves — like we do in Gutenberg and people recommend for vite.

This is the options I see:

Document in the framework docs (this PR).

Make it not to break just for the @wordpress/block-library package: process?.env?.IS_GUTENBERG_PLUGIN ?? false. I don't find this approach sustainable in the whole codebase, though.

Update the variable to a IS_GUTENBERG_PLUGIN global.

I'd like to summon @gziolo @jsnajdr @swissspidy @talldan @t-hamano that have participated in similar conversations, in case they have thoughts/advice.

My understanding is that we cannot use import.meta unless we ship our scripts as modules.

FWIW, I think we already publish our scripts as modules. So is the idea to use process.env for the CJS build and import.meta for the modules build? That might be the best approach no?

IDK why Gutenberg uses process.env.IS_GUTENBERG_PLUGIN, but just using a IS_GUTENBERG_PLUGIN global (like the SCRIPT_DEBUG one that was added recently) makes more sense. Web scripts shouldn't artificially introduce a process.env that doesn't exist. Also weird that the global isn't replaced in build scripts 🤔

like we do in Gutenberg and vitejs/vite#1973.

Tip: when linking to files on GitHub, copy its permalink via the three-dots menu or press Y on the keyboard to get the permalink. This way we can see the file in the version at the time of writing, even when the file is later modified or moved.

Web scripts shouldn't artificially introduce a process.env that doesn't exist

For bundled scripts yes, but packages can ship and support environment variables. process.env variables have always been the standard in the JS community for env variables but lately import.meta is becoming the standard when it comes to ES modules.

Personally, I'd love if we can experiment with this #60087 (comment) and use consistently for all of our env variables. SCRIPT_DEBUG is a runtime variable, so it's different.

That said, I don't want to block this PR more. I'm fine with mentioning the variable in our docs temporarily while we figure this out.

I mentioned it in slack, but will mention it here too. There's also usage of process.env.NODE_ENV in the codebase (in packages like blocks, components, data).

I don't know if build tools handle that property in a special way or if it also causes the same issues as IS_GUTENBERG_PLUGIN. It might be the latter, but it's just that IS_GUTENBERG_PLUGIN causes an error first.

Just mentioning it as I'd hate to see effort go into fixing IS_GUTENBERG_PLUGIN but then later realize there's still a problem with NODE_ENV.

Unblocking the PR :)

michalczaplinski · 2024-04-30T13:40:14Z

@youknowriad are you fine with using the "React" vite config as suggested by @oandregal in #60087 (comment)?

youknowriad · 2024-04-30T16:53:10Z

@michalczaplinski yes as a temporary measure but it would be good to check whether defining process.env.NODE_ENV is necessary as well.

stokesman · 2024-05-03T02:25:10Z

platform-docs/docs/intro.md

 ## Bootstrap your block editor

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


When using "Vanilla" starter index.html imports main.js and there is no index.jsx. Additionally, since Vite doesn’t automatically apply JSX transforms to js files we’d probably want to do something like:

Suggested change

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

It's time to render our first block editor. Rename your `main.js` file to `main.jsx` and update it with the following code:

It’s one more small reason to prefer the "React" starter as relevant files will already be .jsx. Then we can say to put the code in src/App.jsx and also remove the bits about createRoot and render because those will already exist in src/main.jsx.

I'd be happy to put the switch to "React" starter in a follow-up PR though because, well, like a goof I already created one that does that (and has many of the changes in this one) because I didn’t check first to see if it was being worked on.

michalczaplinski · 2024-05-13T11:53:50Z

I've updated the docs now:

They mention using the react Vite preset.
As pointed out by @stokesman, Vite creates a main.jsx file, not an index.jsx so I've also updated those references.
React refresh only works if the root component is exported from another file. So, I had to split the "old" index.js into main.jsx and Editor.jsx.

I've just noticed that @stokesman 's PR ( #61341 ) also includes very similar changes and builds on them, so perhaps we should merge that one instead.

michalczaplinski · 2024-05-16T09:42:19Z

There's work in #61486 to use globalThis instead of process.env.

If it gets merged, we can get rid of the instructions to define the process.env.IS_GUTENBERG_PLUGIN variable. While trying to access process.env.IS_GUTENBERG_PLUGIN in the browser will throw an error, trying to access globalThis.IS_GUTENBERG_PLUGIN simply returns undefined.

michalczaplinski · 2024-12-05T17:33:56Z

I'm going to close this in favour of @stokesman 's #61341.

That PR contains more comprehensive changes.

michalczaplinski added 2 commits March 21, 2024 12:17

Update intro.md with instructions for configuring build tooling, sett…

fe80dfe

…ing IS_GUTENBERG_PLUGIN to false and fixing errors

Update intro.md with Gutenberg Block Editor setup

8bd0748

michalczaplinski added Framework Issues related to broader framework topics, especially as it relates to javascript [Type] Developer Documentation Documentation for developers labels Mar 21, 2024

michalczaplinski requested a review from youknowriad March 21, 2024 17:31

youknowriad reviewed Mar 22, 2024

View reviewed changes

oandregal approved these changes Apr 24, 2024

View reviewed changes

youknowriad previously requested changes Apr 24, 2024

View reviewed changes

stokesman reviewed May 3, 2024

View reviewed changes

stokesman mentioned this pull request May 3, 2024

Update platform docs intro #61341

Merged

michalczaplinski added 2 commits May 13, 2024 11:44

Merge branch 'trunk' into update/platform-docs-intro

f6dd539

Use the react preset and split into main.jsx and Editor.jsx

015a33f

michalczaplinski closed this Dec 5, 2024

oandregal deleted the update/platform-docs-intro branch December 5, 2024 17:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Platform Docs: Update `intro.md` #60087

Platform Docs: Update `intro.md` #60087

michalczaplinski commented Mar 21, 2024 •

edited

Loading

youknowriad Mar 22, 2024

michalczaplinski Apr 1, 2024

michalczaplinski Apr 1, 2024

youknowriad Apr 2, 2024

github-actions bot commented Mar 22, 2024 •

edited

Loading

youknowriad Mar 22, 2024

michalczaplinski Apr 1, 2024 •

edited

Loading

youknowriad Apr 2, 2024

oandregal Apr 24, 2024

oandregal Apr 24, 2024

stokesman May 3, 2024

youknowriad commented Mar 22, 2024

youknowriad Apr 24, 2024

oandregal Apr 26, 2024 •

edited by swissspidy

Loading

youknowriad Apr 26, 2024

swissspidy Apr 26, 2024

youknowriad Apr 26, 2024

youknowriad Apr 26, 2024

talldan Apr 29, 2024

michalczaplinski commented Apr 30, 2024

youknowriad commented Apr 30, 2024

stokesman May 3, 2024 •

edited

Loading

michalczaplinski commented May 13, 2024

michalczaplinski commented May 16, 2024

michalczaplinski commented Dec 5, 2024

		@@ -30,13 +30,39 @@ To build a block editor, you need to install the following dependencies:

		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`

	It's time to render our first block editor. Update your `index.jsx` file with the following code:
	It's time to render our first block editor. Rename your `main.js` file to `main.jsx` and update it with the following code:

Platform Docs: Update intro.md #60087

Platform Docs: Update intro.md #60087

Conversation

michalczaplinski commented Mar 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Mar 22, 2024 • edited Loading

Choose a reason for hiding this comment

michalczaplinski Apr 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad commented Mar 22, 2024

Choose a reason for hiding this comment

oandregal Apr 26, 2024 • edited by swissspidy Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michalczaplinski commented Apr 30, 2024

youknowriad commented Apr 30, 2024

stokesman May 3, 2024 • edited Loading

Choose a reason for hiding this comment

michalczaplinski commented May 13, 2024

michalczaplinski commented May 16, 2024

michalczaplinski commented Dec 5, 2024

Platform Docs: Update `intro.md` #60087

Platform Docs: Update `intro.md` #60087

michalczaplinski commented Mar 21, 2024 •

edited

Loading

github-actions bot commented Mar 22, 2024 •

edited

Loading

michalczaplinski Apr 1, 2024 •

edited

Loading

oandregal Apr 26, 2024 •

edited by swissspidy

Loading

stokesman May 3, 2024 •

edited

Loading