From 7fafb9f916ca43904c9a7df9f35c34bbac59ade3 Mon Sep 17 00:00:00 2001 From: Alex Date: Sat, 23 Dec 2017 06:37:23 -0900 Subject: [PATCH] Break out Installation into top-level doc section (#452) * Break out Installation into top-level doc section * Update navigation (prev/next, nav tree) - Move Installation section to top - Add next/prev to install pages * add links to other install options from try react page * fix markdown link * Clarify that Quick Start and Install are optional "next steps" * Add top-level CDN page This is useful for Codepen and other Unpkg-y setups * Add link to Tutorial from Try React * Update CRA link in tutorial * Make Try React subheader a proper sentence * Add "minimal" * Explain local dev setup is more work than Codepen etc * Fix typos * Add : between headings * add note that CRA is not lightweight * fix typo * Update add-react-to-a-new-app.md * Update add-react-to-a-new-app.md * Remove the Bower note * Update try-react.md * Tweak wording * Use direct link --- content/docs/add-react-to-a-new-app.md | 47 ++++++++++ ...ion.md => add-react-to-an-existing-app.md} | 91 ++----------------- content/docs/cdn-links.md | 37 ++++++++ content/docs/hello-world.md | 4 +- content/docs/nav.yml | 12 ++- content/docs/try-react.md | 41 +++++++++ content/tutorial/tutorial.md | 2 +- src/components/LayoutFooter/Footer.js | 8 +- 8 files changed, 146 insertions(+), 96 deletions(-) create mode 100644 content/docs/add-react-to-a-new-app.md rename content/docs/{installation.md => add-react-to-an-existing-app.md} (51%) create mode 100644 content/docs/cdn-links.md create mode 100644 content/docs/try-react.md diff --git a/content/docs/add-react-to-a-new-app.md b/content/docs/add-react-to-a-new-app.md new file mode 100644 index 00000000..84fa540f --- /dev/null +++ b/content/docs/add-react-to-a-new-app.md @@ -0,0 +1,47 @@ +--- +id: add-react-to-a-new-app +title: Add React to a New Application +permalink: docs/add-react-to-a-new-app.html +prev: try-react.html +next: add-react-to-an-existing-app.html +--- + +The easiest way to get started on a new React project is by using a starter kit. + +> Note: +> +> Check out the [Try React](/docs/try-react.html) page if you are looking for lightweight environments to experiment with React. +> The options on this page are designed to help bootstrap single-page applications with linting, testing, bundling, production optimizations, and more. + +## Create React App + +[Create React App](http://github.com/facebookincubator/create-react-app) is the best way to start building a new React single page application. 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 >= 6 on your machine. + +```bash +npm install -g create-react-app +create-react-app my-app + +cd my-app +npm start +``` + +If you have npm 5.2.0+ installed, you may use [npx](https://www.npmjs.com/package/npx) instead. + +```bash +npx create-react-app my-app + +cd my-app +npm start +``` + +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. It uses build tools like [Babel](http://babeljs.io/) and [webpack](https://webpack.js.org/) under the hood, but works with zero configuration. + +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://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#table-of-contents). + +## Other Starter Kits + +See the Community section for a list of [starter kits](/community/starter-kits.html). + +## Advanced + +If you prefer to configure a project manually, see [Installing React](/docs/add-react-to-an-existing-app.html#installing-react) in the next section. diff --git a/content/docs/installation.md b/content/docs/add-react-to-an-existing-app.md similarity index 51% rename from content/docs/installation.md rename to content/docs/add-react-to-an-existing-app.md index 77844cfd..8a6cf3f0 100644 --- a/content/docs/installation.md +++ b/content/docs/add-react-to-an-existing-app.md @@ -1,60 +1,11 @@ --- -id: installation -title: Installation -permalink: docs/installation.html -redirect_from: - - "download.html" - - "downloads.html" - - "docs/tooling-integration.html" - - "docs/package-management.html" - - "docs/language-tooling.html" - - "docs/environments.html" -next: hello-world.html +id: add-react-to-an-existing-app +title: Add React to an Existing Application +permalink: docs/add-react-to-an-existing-app.html +prev: add-react-to-a-new-app.html +next: cdn-links.html --- -React is flexible and can be used in a variety of projects. You can create new apps with it, but you can also gradually introduce it into an existing codebase without doing a rewrite. - -Here are a couple of ways to get started: - -* [Try React](#trying-out-react) -* [Create a New App](#creating-a-new-application) -* [Add React to an Existing App](#adding-react-to-an-existing-application) - -## Trying Out React - -If you're just interested in playing around with React, you can use CodePen. Try starting from [this Hello World example code](http://codepen.io/gaearon/pen/rrpgNB?editors=0010). You don't need to install anything; you can just modify the code and see if it works. - -If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production. - -If you want to use it for a full application, there are two popular ways to get started with React: using Create React App, or adding it to an existing application. - -## Creating a New Application - -[Create React App](http://github.com/facebookincubator/create-react-app) is the best way to start building a new React single page application. 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 >= 6 on your machine. - -```bash -npm install -g create-react-app -create-react-app my-app - -cd my-app -npm start -``` - -If you have npm 5.2.0+ installed, you may use [npx](https://www.npmjs.com/package/npx) instead. - -```bash -npx create-react-app my-app - -cd my-app -npm start -``` - -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. It uses build tools like [Babel](http://babeljs.io/) and [webpack](https://webpack.js.org/) under the hood, but works with zero configuration. - -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://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#table-of-contents). - -## Adding React to an Existing Application - You don't need to rewrite your app to start using React. We recommend adding React to a small part of your application, such as an individual widget, so you can see if it works well for your use case. @@ -134,34 +85,4 @@ Learn [how to tell if your website is serving the right version of React](/docs/ ### Using a CDN -If you don't want to use npm to manage client packages, the `react` and `react-dom` npm packages also provide single-file distributions in `umd` folders, which are hosted on a CDN: - -```html - - -``` - -The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at: - -```html - - -``` - -To load a specific version of `react` and `react-dom`, replace `16` with the version number. - -If you use Bower, React is available via the `react` package. - -#### Why the `crossorigin` Attribute? - -If you serve React from a CDN, we recommend to keep the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute set: - -```html - -``` - -We also recommend to verify that the CDN you are using sets the `Access-Control-Allow-Origin: *` HTTP header: - -![Access-Control-Allow-Origin: *](../images/docs/cdn-cors-header.png) - -This enables a better [error handling experience](/blog/2017/07/26/error-handling-in-react-16.html) in React 16 and later. +If you don't want to use npm to manage client packages, the `react` and `react-dom` npm packages also provide single-file distributions in `umd` folders. See the [CDN](/docs/cdn-links.html) page for links. diff --git a/content/docs/cdn-links.md b/content/docs/cdn-links.md new file mode 100644 index 00000000..9205e721 --- /dev/null +++ b/content/docs/cdn-links.md @@ -0,0 +1,37 @@ +--- +id: cdn-links +title: CDN Links +permalink: docs/cdn-links.html +prev: add-react-to-an-existing-app.html +next: hello-world.html +--- + +The UMD builds of React and ReactDOM are available over a CDN. + +```html + + +``` + +The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at: + +```html + + +``` + +To load a specific version of `react` and `react-dom`, replace `16` with the version number. + +### Why the `crossorigin` Attribute? + +If you serve React from a CDN, we recommend to keep the [`crossorigin`](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) attribute set: + +```html + +``` + +We also recommend to verify that the CDN you are using sets the `Access-Control-Allow-Origin: *` HTTP header: + +![Access-Control-Allow-Origin: *](../images/docs/cdn-cors-header.png) + +This enables a better [error handling experience](/blog/2017/07/26/error-handling-in-react-16.html) in React 16 and later. diff --git a/content/docs/hello-world.md b/content/docs/hello-world.md index be30b5b9..5138af59 100644 --- a/content/docs/hello-world.md +++ b/content/docs/hello-world.md @@ -2,7 +2,7 @@ id: hello-world title: Hello World permalink: docs/hello-world.html -prev: installation.html +prev: cdn-links.html next: introducing-jsx.html redirect_from: - "docs/" @@ -12,7 +12,7 @@ redirect_from: - "docs/getting-started-zh-CN.html" --- -The easiest way to get started with React is to use [this Hello World example code on CodePen](codepen://hello-world). You don't need to install anything; you can just open it in another tab and follow along as we go through examples. If you'd rather use a local development environment, check out the [Installation](/docs/installation.html) page. +The easiest way to get started with React is to use [this Hello World example code on CodePen](codepen://hello-world). You don't need to install anything; you can just open it in another tab and follow along as we go through examples. If you'd rather use a local development environment, check out the [Installation](/docs/try-react.html) section. The smallest React example looks like this: diff --git a/content/docs/nav.yml b/content/docs/nav.yml index ef204d97..c10bf60d 100644 --- a/content/docs/nav.yml +++ b/content/docs/nav.yml @@ -1,7 +1,15 @@ +- title: Installation + items: + - id: try-react + title: Try React + - id: add-react-to-a-new-app + title: Add React to a New App + - id: add-react-to-an-existing-app + title: Add React to an Existing App + - id: cdn-links + title: CDN Links - title: Quick Start items: - - id: installation - title: Installation - id: hello-world title: Hello World - id: introducing-jsx diff --git a/content/docs/try-react.md b/content/docs/try-react.md new file mode 100644 index 00000000..49ec1046 --- /dev/null +++ b/content/docs/try-react.md @@ -0,0 +1,41 @@ +--- +id: try-react +title: Try React +permalink: docs/try-react.html +next: add-react-to-a-new-app.html +redirect_from: + - "docs/installation.html" + - "download.html" + - "downloads.html" + - "docs/tooling-integration.html" + - "docs/package-management.html" + - "docs/language-tooling.html" + - "docs/environments.html" +--- + +Try React online or set up your local development environment. + +## Online + +If you're just interested in playing around with React, you can use an online code playground. Try a Hello World template on [CodePen](codepen://hello-world) or [CodeSandbox](https://codesandbox.io/s/new). + +## Minimal HTML Template + +If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production. + +## Next Steps + +### Quick Start + +- Head over to the [Quick Start](/docs/hello-world.html) section for a step-by-step introduction to React concepts. + +- Try the [Tutorial](/tutorial/tutorial.html) for a hands-on practical example. + +### Complete Development Environment + +The lightweight solutions above are the best fit if you are new to React or just experimenting. + +When you are ready to build your first application with React, check out the install guides below. These setups are designed to get you up and running with a great developer experience and are ready for production. They include linting, testing, and optimizations built-in; however, they require more time and disk space to set up and install. + +- [Add React to a New App](/docs/add-react-to-a-new-app.html): Create a new app with a fully-featured starter kit. +- [Add React to an Existing App](/docs/add-react-to-a-new-app.html): Add React to a build system or a larger app. diff --git a/content/tutorial/tutorial.md b/content/tutorial/tutorial.md index 66c3562a..afe5e267 100644 --- a/content/tutorial/tutorial.md +++ b/content/tutorial/tutorial.md @@ -53,7 +53,7 @@ This is more work, but lets you work from the comfort of your editor. If you want to do it, here are the steps to follow: 1. Make sure you have a recent version of [Node.js](https://nodejs.org/en/) installed. -2. Follow the [installation instructions](/docs/installation.html#creating-a-new-application) to create a new project. +2. Follow the [installation instructions](/docs/add-react-to-a-new-app.html) to create a new project. ```bash npm install -g create-react-app diff --git a/src/components/LayoutFooter/Footer.js b/src/components/LayoutFooter/Footer.js index c7e80ccd..ff3accf7 100644 --- a/src/components/LayoutFooter/Footer.js +++ b/src/components/LayoutFooter/Footer.js @@ -62,13 +62,9 @@ const Footer = ({layoutHasSidebar = false}: {layoutHasSidebar: boolean}) => ( Docs {sectionListDocs.map(section => { - // Skip the Installation page for Quick Start - const defaultItem = - section.items[0].id === 'installation' - ? section.items[1].id - : section.items[0].id; + const defaultItem = section.items[0]; return ( - + {section.title} );