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

Jump to bottom

Update recommended React toolchains, add Vite. #3828

Closed
wants to merge 2 commits into from
Closed

Update recommended React toolchains, add Vite. #3828

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a7455c
Update recommended React toolchains.
leerob Aug 3, 2021
7c93bbe
Merge branch 'main' into patch-1
leerob Feb 5, 2022
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
38 changes: 13 additions & 25 deletions content/docs/create-a-new-react-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,43 +30,29 @@ This is also **the easiest way to integrate React into an existing website.** Yo

The React team primarily recommends these solutions:

- If you're **learning React** or **creating a new [single-page](/docs/glossary.html#single-page-application) app,** use [Create React App](#create-react-app).
- If you're building a **server-rendered website with Node.js,** try [Next.js](#nextjs).
- If you're building a **static content-oriented website,** try [Gatsby](#gatsby).
- If you're building a **static or server-rendered application,** use [Next.js](#nextjs).
- If you're building a **static content-oriented website,** use [Gatsby](#gatsby).
- If you're building a **[single-page app](/docs/glossary.html#single-page-application)**, use [Create React App](#create-react-app).
Copy link
Collaborator

Choose a reason for hiding this comment

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

In the beta.reactjs.org we still recommend create-react-app if they are just getting started. Not sure how @gaearon feels about this? We might want to make it consistent in both sites.

- If you're building a **component library** or **integrating with an existing codebase**, try [More Flexible Toolchains](#more-flexible-toolchains).

### Create React App {#create-react-app}

[Create React App](https://github.com/facebookincubator/create-react-app) is a comfortable environment for **learning React**, and is the best way to start building **a new [single-page](/docs/glossary.html#single-page-application) application** in React.

It sets up your development environment so that you can use the latest JavaScript features, provides a nice developer experience, and optimizes your app for production. You’ll need to have [Node >= 14.0.0 and npm >= 5.6](https://nodejs.org/en/) on your machine. To create a project, run:

```bash
leerob marked this conversation as resolved.
Show resolved Hide resolved
npx create-react-app my-app
cd my-app
npm start
```

>Note
>
>`npx` on the first line is not a typo -- it's a [package runner tool that comes with npm 5.2+](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b).

Create React App doesn't handle backend logic or databases; it just creates a frontend build pipeline, so you can use it with any backend you want. Under the hood, it uses [Babel](https://babeljs.io/) and [webpack](https://webpack.js.org/), but you don't need to know anything about them.

When you're ready to deploy to production, running `npm run build` will create an optimized build of your app in the `build` folder. You can learn more about Create React App [from its README](https://github.com/facebookincubator/create-react-app#create-react-app--) and the [User Guide](https://facebook.github.io/create-react-app/).

### Next.js {#nextjs}

[Next.js](https://nextjs.org/) is a popular and lightweight framework for **static and server‑rendered applications** built with React. It includes **styling and routing solutions** out of the box, and assumes that you're using [Node.js](https://nodejs.org/) as the server environment.
[Next.js](https://nextjs.org/) is a framework for **static and server‑rendered applications** built with React. It includes **styling and routing solutions** out of the box and uses [Node.js](https://nodejs.org/) as the server environment.

Learn Next.js from [its official guide](https://nextjs.org/learn/).

### Gatsby {#gatsby}

[Gatsby](https://www.gatsbyjs.org/) is the best way to create **static websites** with React. It lets you use React components, but outputs pre-rendered HTML and CSS to guarantee the fastest load time.
[Gatsby](https://www.gatsbyjs.org/) is a framework for creating **static websites** with React. It lets you use React components, but outputs pre-rendered HTML and CSS to guarantee the fastest load time.

Learn Gatsby from [its official guide](https://www.gatsbyjs.org/docs/) and a [gallery of starter kits](https://www.gatsbyjs.org/docs/gatsby-starters/).

### Create React App {#create-react-app}

[Create React App](https://github.com/facebookincubator/create-react-app) is framework for **small, [single-page](/docs/glossary.html#single-page-application) applications** in React.
leerob marked this conversation as resolved.
Show resolved Hide resolved
Copy link

Choose a reason for hiding this comment

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

I suggest to keep old description here, but remove "comfortable" and best". Something like this:

Create React App is a pre-configured environment which lets you start building single-page application or just learning React without configuring build tools like webpack or Babel.

My main concerns with proposed version are:

is framework

It puts CRA on the same shelf with Next.js and Gatsby, but CRA provides almost no guidelines on app structure. Maybe it can serve as a difference here instead: if you want a framework, use Next.js or Gatsby.

for small applications

I'd say size should not be differentiating point here. CRA can be a suitable choice for medium-sized or even large apps unless you need to configure something in underlying tools.

Seems like "small" here means "simple" or even "quite typical single-page app with predictable build tooling requirements" :)

Copy link
Contributor

Choose a reason for hiding this comment

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

@44px Would you prefer changing "small" to "non-production" to match Dan's comment?

...starting with 2.0, [CRA is] mostly in maintenance mode and does not strive to be the best tool for production React apps. It is a tool to get started and get something running fast. Perhaps, it's not even best at that anymore.

Copy link

Choose a reason for hiding this comment

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

I'm afraid it can nudge someone to build app with custom webpack config because they have "production" app :)

For the last year I saw at least two apps with config problems:

  • One had broken caching because of improperly set chunk name
  • Second had large production bundle because of inlined source maps

Both problems have simple fixes, but they might not happen at all if these apps were built with CRA. And they could, these were "simple" apps.

I still see the CRA as the only option if you need to build "classic SPA". It provides good DX (TypeScript support, Fast Refresh, babel-macro, using SVGs as React components, detection of CSS modules, REACT_APP_* env vars substitution) and produces optimized production bundles.

Copy link
Contributor

Choose a reason for hiding this comment

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

Should we add the "without configuring build tools like webpack or Babel" to the Next.js and Gastby descriptions too?

Copy link

Choose a reason for hiding this comment

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

Good point! We don't need to say this at all because all tools from "Recommended Toolchains" section are zero-config.


Learn Create React App from [its official guide](https://create-react-app.dev/).

### More Flexible Toolchains {#more-flexible-toolchains}

The following toolchains offer more flexibility and choice. We recommend them to more experienced users:
Expand All @@ -79,6 +65,8 @@ The following toolchains offer more flexibility and choice. We recommend them to

- **[Razzle](https://github.com/jaredpalmer/razzle)** is a server-rendering framework that doesn't require any configuration, but offers more flexibility than Next.js.

- **[Vite](https://vitejs.dev/)** is a build tool that aims to provide a faster and leaner development experience for modern web projects.
leerob marked this conversation as resolved.
Show resolved Hide resolved

## Creating a Toolchain from Scratch {#creating-a-toolchain-from-scratch}

A JavaScript build toolchain typically consists of:
Expand Down