MDN React tutorials #1: Getting started #30177

mxmason · 2023-11-10T06:26:07Z

Description

This set of PRs is intended to update the MDN learning area React tutorials to use Vite instead of create-react-app, and make sure that any other React/JSX code uses up-to-date best practices.

Refer to the task list at mdn/mdn#474 to see the overall completion status of each tutorial.

Fixes mdn/mdn#474

When all of these PRs are complete, merge this one first.

github-actions · 2023-11-10T06:29:04Z

Preview URLs

/en-US/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started

External URLs (11)

URL: /en-US/docs/Learn/Tools_and_testing/Client-side_JavaScript_frameworks/React_getting_started
Title: Getting started with React

https://docs.npmjs.com/cli/v9/configuring-npm/package-json/ (1 time) (Note! This may be a new URL 👀)
https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json (1 time) (Note! This may be a new URL 👀)
https://nodejs.org/en/ (2 times) (Note! This may be a new URL 👀)
https://react.dev/ (1 time) (Note! This may be a new URL 👀)
https://react.dev/docs/fragments (1 time) (Note! This may be a new URL 👀)
https://react.dev/learn/add-react-to-an-existing-project (2 times) (Note! This may be a new URL 👀)
https://react.dev/reference/react-dom (1 time) (Note! This may be a new URL 👀)
https://react.dev/reference/react-dom/client/createRoot (1 time) (Note! This may be a new URL 👀)
https://react.dev/reference/react/StrictMode (1 time) (Note! This may be a new URL 👀)
https://vitejs.dev/ (1 time) (Note! This may be a new URL 👀)
https://vitejs.dev/guide/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-12-21 10:50:54)

…j/react/vite

chrisdavidmills · 2023-11-10T09:35:57Z

This PR is not complete, but I wanted to create something for reviewers to look at before it got too far. Also, since this work will be part of a body of significant changes, should we work off of a staging or development branch of some sort until we're ready to publish?

I'd be fine with turning this branch into the development branch for the overall update project, or with anything the maintainers would like me to do!

Hi @mxmason, nice to see you on here!

So, we don't really have staging for MDN content; we just work off of a fork taken from main, and then merge it in. You will notice that the environment auto-generates preview URLs so we can see what the rendered content looks like without having to build the branch locally and render it: #30177 (comment)

In terms of process for this work, there are no hard and fast rules, but I'm happy to figure out a process that works for the both of us. Historically I have generally worked with single giant PRs for my changes, but that is changing, as reviewers tend to find that unwieldy, plus it takes longer to produce the first draft to review.

One system that has worked in the past (which I did for the WebGPU reference docs) is to:

Create a separate PR for each unit of work (per page would probably work here), clearly labeled "DO NOT MERGE", and test and review each article separately.
When each component PR has been reviewed, updated, and approved, merge each one into a single final PR.
Do a final walkthrough of the pages to make sure they all work together in this PR (usually this is a good place to spot broken links and continuity errors), ad make final changes.
Merge the final PR.

Would this work for you? The disadvantage here is that it is harder to check whether each subsequent page is consistent with the ones that came before. You just need to have the preview pages from the previous PRs open in separate tabs to refer to as you review each one. But, it is OK.

Or we could do a kind of hybrid approach, where either you do a couple of pages per PR, and/or maybe merge each approved PR into the next PR in the sequence as it is approved.

What option do you prefer? Or do you have another idea?

mxmason · 2023-11-10T16:11:34Z

Hello, @chrisdavidmills! 💜

Thanks for explaining our options. I figured you might not have a staging branch, but I thought I should ask. If it works for you, could we do an approach in which this branch (or a new one, I'm not fussed) is the trunk for all our content changes, and we merge subsequent PRs into it? Would your CI tools build previews for those, or does it only build if the PR is based on main?

One example of what I'm thinking:

I continue working on this page in this branch. You review & approve when it's ready
I base my next PR off of this branch. You approve & review. I merge that branch down into this one
I again base a PR off the updates done to this branch, and merge into this branch when those changes are done
Repeat until we're ready for release, at which point we merge into main

Does that make sense/is it doable? It sounds kind of like your final suggestion, but I wanna be super sure I understand :)

chrisdavidmills · 2023-11-13T08:37:08Z

Hello, @chrisdavidmills! 💜

Thanks for explaining our options. I figured you might not have a staging branch, but I thought I should ask. If it works for you, could we do an approach in which this branch (or a new one, I'm not fussed) is the trunk for all our content changes, and we merge subsequent PRs into it? Would your CI tools build previews for those, or does it only build if the PR is based on main?

Sure, this sounds good to me. As far as I know, the CI tools should build previews for all of those, yes.

One example of what I'm thinking:

1. I continue working on this page in this branch. You review & approve when it's ready

2. I base my next PR off of this branch. You approve & review. I merge that branch down into this one

3. I again base a PR off the updates done to this branch, and merge into this branch when those changes are done

4. Repeat until we're ready for release, at which point we merge into main

Does that make sense/is it doable? It sounds kind of like your final suggestion, but I wanna be super sure I understand :)

Yes, this sounds good to me. Let's do it!

mxmason · 2023-11-16T04:11:19Z

Hello, @chrisdavidmills! I've done broad edits of this whole page, so I think we're ready for a review.

The content in this file hits the same points as before, with the largest changes being related to Vite, and the fact that Vite provides different boilerplate than create-react-app does. Some questions:

Are we still ok with how much boilerplate we're asking folks to create and then throw away? It crossed my mind that MDN could host its own template repo for this lesson. I'd be happy to do this, but would also understand if you think the effort of creating and maintaining our own template isn't worth it.
We still have to capture a new "this is what the app should look like" screenshot asset for this page. I wanted to hold off on that until I confirmed that we do in fact want to keep this template
While editing some of the old code samples here, I saw references to line numbers, but we don't provide line numbers in rendered markup :( am I missing any syntax that would allow this, or is this a shortcoming of the yari server? Do I need to make a pull request there, because I totally will 👀

chrisdavidmills

Ok, that'll do for now for my first review. Quite a few comments here @mxmason, but barring a couple, nothing serious and mostly just grammar/language suggestions.

...-us/learn/tools_and_testing/client-side_javascript_frameworks/react_getting_started/index.md

chrisdavidmills · 2023-11-16T12:21:37Z

@mxmason and some responses to your questions:

Are we still ok with how much boilerplate we're asking folks to create and then throw away? It crossed my mind that MDN could host its own template repo for this lesson. I'd be happy to do this, but would also understand if you think the effort of creating and maintaining our own template isn't worth it.

I think it Is fine. It really isn't very much boilerplate, and I think it is useful to give the reader the experience of using the command line and delving into the code. Plus, if we created a template repo we'd have to decide where to put it, and that would create another thing we have to maintain.

We still have to capture a new "this is what the app should look like" screenshot asset for this page. I wanted to hold off on that until I confirmed that we do in fact want to keep this template

Yup, capture away ;-)

While editing some of the old code samples here, I saw references to line numbers, but we don't provide line numbers in rendered markup :( am I missing any syntax that would allow this, or is this a shortcoming of the yari server? Do I need to make a pull request there, because I totally will 👀

No, we don't use line numbers anymore. Old Kuma MDN used to do this, but I'm not sure if yari does. Also, I seem to remember line numbers being a pain because you'd inevitably change the code example, then have to remember to update all the line number references to suit. Absolute pain. Also, if your code blocks are big enough that you need line numbers to help readers navigate them, they are really too big.

Co-authored-by: Chris Mills <[email protected]>

mxmason

Once again to you, @chrisdavidmills

mxmason · 2023-11-21T01:36:59Z

...-us/learn/tools_and_testing/client-side_javascript_frameworks/react_getting_started/index.md

+The **`src`** directory is where we'll spend most of our time, as it's where the source code for our application lives. You'll notice that JavaScript files in this directory end in the extension `.jsx`. This extension is necessary for any file that contains JSX – it tells Vite to turn the JSX syntax into JavaScript that your browser can understand. The `src/assets` directory contains the React logo you saw in the browser.
+
+The `package.json` and `package-lock.json` files contain metadata about our project. These files are not unique to React applications: Vite populated `package.json` for us, and npm created `package-lock.json` for when we installed the app's dependencies. You don't need to understand these files at all to complete this tutorial. However, if you'd like to learn more about them, you can read about [`package.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json/) and [`package-lock.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json) in the npm docs. We also talk about `package.json` in our [Package management basics](/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Package_management) tutorial.


These paragraphs are a little more complete. I mention the assets directory within src and acknowledge the package.json lockfile, with some links.

Looking good.

...-us/learn/tools_and_testing/client-side_javascript_frameworks/react_getting_started/index.md

chrisdavidmills

@mxmason LGTM! Ready to go on to the next one ;-)

Let me know if you need me to do anything to get the process set up for the next stage.

mxmason · 2023-11-21T23:50:25Z

So, @chrisdavidmills: I think we have hit an impasse with my proposed strategy for managing PRs: if I use this branch as a base for a new PR, the pull request will be opened against my fork, not against MDN's repo – you can see this here. Can you create some kind of react-rewrite or other dev branch for us to work in? If not, I think we have to go with your suggestion of opening a bunch of unrelated PRs against main.

Whatever you'd like to do, that branch is basically ready for you to look at!

chrisdavidmills · 2023-11-22T09:02:56Z

So, @chrisdavidmills: I think we have hit an impasse with my proposed strategy for managing PRs: if I use this branch as a base for a new PR, the pull request will be opened against my fork, not against MDN's repo – you can see this here. Can you create some kind of react-rewrite or other dev branch for us to work in? If not, I think we have to go with your suggestion of opening a bunch of unrelated PRs against main.

Whatever you'd like to do, that branch is basically ready for you to look at!

OK, so here is a thought. We could do the same thing as I have been doing for my Google MDN work, in which I get the technical review done in one PR, then close that PR and open another one based on the same branch to do the editorial review in.

So, each time one of your new articles is reviewed and approved, I close the PR, open another one based on the same branch, and you carry on your work in that for the next article. Each PR would only contain the comments for a single article, saving all the confusion of having all comments in one PR.

What do you think?

mxmason · 2023-11-22T10:05:03Z

Oh, I like that! I've never really worked on a branch after closing a PR so this wouldn't have crossed my mind. Let's do it!

chrisdavidmills · 2023-11-22T10:17:50Z

Oh, I like that! I've never really worked on a branch after closing a PR so this wouldn't have crossed my mind. Let's do it!

Great, I'll set this up then. I'll close this and create a fresh PR for you to continue working in.

chrisdavidmills · 2023-11-22T10:48:35Z

Oh, I like that! I've never really worked on a branch after closing a PR so this wouldn't have crossed my mind. Let's do it!

Great, I'll set this up then. I'll close this and create a fresh PR for you to continue working in.

OK, scratch that. For some reason, your fork won't show up in the list of forks to compare against when I try to create a new PR based on it. I can't figure out why. This is really annoying.

So how about you create a new fork based on mdn/content and do the second article update in it (or more if it ends up being a small update), and then we'll keep this one open, and make a note on each subsequent one to not merge it until the previous one has been merged. Each time we merge one we'll update the next one against the base branch and make sure there are no conflicts before merging it, etc.?

mxmason · 2023-11-22T15:14:07Z

Terrible of GitHub to do this to us! Your suggestion works for me. I'll realign my branch with main and open a PR in a few.

github-actions · 2023-12-07T15:52:34Z

This pull request has merge conflicts that must be resolved before it can be merged.

* chore: replace create-react-app with vite * chore: .js --> .jsx * chore: add dev script section * chore: update App component walkthrough * fix: use correct h1 link * feat: rewrite more * chore: apply suggestions from review Co-authored-by: Chris Mills <[email protected]> * chore: fix npm script syntax * chore: rewrite node install instructions * chore: delete extraneous section * chore: delete image from replacement code * chore: add syntax explainer * chore: clean up final section * chore: rewrite jsx section * chore: nitpick notes * chore: delete React 17 note * chore(nit): hard drive -> machine * chore: apply suggestions from code review Co-authored-by: Chris Mills <[email protected]> * remove superfluous quote * chore: replace create-react-app image with vite * chore: index.jsx --> main.jsx * chore: clean up prop-comment section * chore: delete note on multi-word attributes * chore: use code syntax in heading * chore: change npm script note * chore: update note again * chore: fix image alt * chore: apply suggestions from code review Co-authored-by: Chris Mills <[email protected]> * chore: replace rollup mention with generic bundler reference * chore: document assets directory * chore: document lockfile * chore: disambiguate app function and component * chore: add some * Small App() related tweaks --------- Co-authored-by: Chris Mills <[email protected]>

mxmason added 4 commits November 9, 2023 21:35

chore: replace create-react-app with vite

85585fe

chore: .js --> .jsx

213059d

chore: add dev script section

0561a1d

chore: update App component walkthrough

eab5181

github-actions bot added the Content:Learn:Client-side Content under “Client-side JavaScript frameworks” (Svelte, React, Angular, Vue) and related subtrees label Nov 10, 2023

Merge branch 'main' into ej/react/vite

b9d63c0

mxmason added 2 commits November 9, 2023 22:32

fix: use correct h1 link

4de45c5

Merge branch 'ej/react/vite' of github.com:mxmason/mdn-content into e…

8aaae0f

…j/react/vite

chrisdavidmills mentioned this pull request Nov 10, 2023

[PROJECT]: Modernize React tutorials mdn/mdn#474

Closed

10 tasks

mxmason added 3 commits November 13, 2023 20:21

Merge branch 'main' of github.com:mdn/content into ej/react/vite

b76da0e

feat: rewrite more

299b66f

Merge remote-tracking branch 'upstream/main' into ej/react/vite

f61ebff

mxmason marked this pull request as ready for review November 16, 2023 04:11

mxmason requested a review from a team as a code owner November 16, 2023 04:11

mxmason requested review from zfox23 and removed request for a team November 16, 2023 04:11

Merge branch 'main' into ej/react/vite

0997847

chrisdavidmills requested changes Nov 16, 2023

View reviewed changes

mxmason and others added 6 commits November 16, 2023 18:40

chore: apply suggestions from review

47c7a49

Co-authored-by: Chris Mills <[email protected]>

chore: fix npm script syntax

a35203e

chore: rewrite node install instructions

c3e7587

chore: delete extraneous section

308f6f1

chore: delete image from replacement code

1a1340e

chore: add syntax explainer

9805b8a

mxmason added 2 commits November 20, 2023 17:33

chore: disambiguate app function and component

310e62f

chore: add some

75c5bfa

mxmason commented Nov 21, 2023

View reviewed changes

chrisdavidmills added 2 commits November 21, 2023 09:32

Small App() related tweaks

417bd9d

Merge branch 'main' into ej/react/vite

f4ad9a7

chrisdavidmills approved these changes Nov 21, 2023

View reviewed changes

chrisdavidmills closed this Nov 22, 2023

chrisdavidmills changed the title ~~[WIP] Replace create-react-app with Vite~~ DO NOT MERGE: Replace create-react-app with Vite in React tutorials #1 Nov 22, 2023

chrisdavidmills reopened this Nov 22, 2023

Merge branch 'main' into ej/react/vite

134f89d

chrisdavidmills closed this Nov 22, 2023

chrisdavidmills reopened this Nov 22, 2023

mxmason mentioned this pull request Nov 22, 2023

MDN React tutorials #2: Todo list beginning #30453

Merged

chrisdavidmills changed the title ~~DO NOT MERGE: Replace create-react-app with Vite in React tutorials #1~~ DO NOT MERGE: MDN React tutorials #1: Getting started Nov 23, 2023

github-actions bot added the merge conflicts 🚧 [PR only] label Dec 7, 2023

Merge branch 'main' into ej/react/vite

8fc7459

github-actions bot removed the merge conflicts 🚧 [PR only] label Dec 7, 2023

bsmth added the do not merge [PR only] Not ready to land label Dec 13, 2023

Merge branch 'main' into ej/react/vite

487a53c

chrisdavidmills removed the do not merge [PR only] Not ready to land label Dec 21, 2023

chrisdavidmills changed the title ~~DO NOT MERGE: MDN React tutorials #1: Getting started~~ MDN React tutorials #1: Getting started Dec 21, 2023

chrisdavidmills merged commit 264ca2e into mdn:main Dec 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MDN React tutorials #1: Getting started #30177

MDN React tutorials #1: Getting started #30177

mxmason commented Nov 10, 2023 •

edited by chrisdavidmills

Loading

github-actions bot commented Nov 10, 2023 •

edited

Loading

chrisdavidmills commented Nov 10, 2023 •

edited

Loading

mxmason commented Nov 10, 2023

chrisdavidmills commented Nov 13, 2023

mxmason commented Nov 16, 2023 •

edited

Loading

chrisdavidmills left a comment

chrisdavidmills commented Nov 16, 2023 •

edited

Loading

mxmason left a comment

mxmason Nov 21, 2023

chrisdavidmills Nov 21, 2023

chrisdavidmills left a comment

mxmason commented Nov 21, 2023

chrisdavidmills commented Nov 22, 2023

mxmason commented Nov 22, 2023

chrisdavidmills commented Nov 22, 2023

chrisdavidmills commented Nov 22, 2023

mxmason commented Nov 22, 2023

github-actions bot commented Dec 7, 2023

		The `src` directory is where we'll spend most of our time, as it's where the source code for our application lives. You'll notice that JavaScript files in this directory end in the extension `.jsx`. This extension is necessary for any file that contains JSX – it tells Vite to turn the JSX syntax into JavaScript that your browser can understand. The `src/assets` directory contains the React logo you saw in the browser.

		The `package.json` and `package-lock.json` files contain metadata about our project. These files are not unique to React applications: Vite populated `package.json` for us, and npm created `package-lock.json` for when we installed the app's dependencies. You don't need to understand these files at all to complete this tutorial. However, if you'd like to learn more about them, you can read about [`package.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json/) and [`package-lock.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json) in the npm docs. We also talk about `package.json` in our [Package management basics](/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Package_management) tutorial.

MDN React tutorials #1: Getting started #30177

MDN React tutorials #1: Getting started #30177

Conversation

mxmason commented Nov 10, 2023 • edited by chrisdavidmills Loading

Description

github-actions bot commented Nov 10, 2023 • edited Loading

chrisdavidmills commented Nov 10, 2023 • edited Loading

mxmason commented Nov 10, 2023

chrisdavidmills commented Nov 13, 2023

mxmason commented Nov 16, 2023 • edited Loading

chrisdavidmills left a comment

Choose a reason for hiding this comment

chrisdavidmills commented Nov 16, 2023 • edited Loading

mxmason left a comment

Choose a reason for hiding this comment

mxmason Nov 21, 2023

Choose a reason for hiding this comment

chrisdavidmills Nov 21, 2023

Choose a reason for hiding this comment

chrisdavidmills left a comment

Choose a reason for hiding this comment

mxmason commented Nov 21, 2023

chrisdavidmills commented Nov 22, 2023

mxmason commented Nov 22, 2023

chrisdavidmills commented Nov 22, 2023

chrisdavidmills commented Nov 22, 2023

mxmason commented Nov 22, 2023

github-actions bot commented Dec 7, 2023

mxmason commented Nov 10, 2023 •

edited by chrisdavidmills

Loading

github-actions bot commented Nov 10, 2023 •

edited

Loading

chrisdavidmills commented Nov 10, 2023 •

edited

Loading

mxmason commented Nov 16, 2023 •

edited

Loading

chrisdavidmills commented Nov 16, 2023 •

edited

Loading