fb2f44e86f
* [Gatsby docs a11y] Add `aria-label` to search input **what is the change?:** See title. **why make this change?:** There was no label on this input, and screen readers might not have been able to identify it's purpose. [The `placeholder` doesn't count as a label.](http://a11yproject.com/posts/placeholder-input-elements/) **test plan:** Manually inspected the HTML in the devtools, and ran the aXe a11y audit tool, and the warning generated by aXe was gone. **issue:** Checklist item on list of docs a11y issues - https://github.com/bvaughn/react/wiki/Gatsby-A11y-Fixes * [Gatsby Docs a11y] Increase contrast of 'installation' page tabs **what is the change?:** Change the dark blue used for the text/background of the tabs on the 'installation' page to a slightly darker blue, which we were already using for the 'focus' style of the tabs. It looked a bit weird before, imo, when the 'focus' was darker. Now the 'focus' style just lightens the border to the new signature blue. **why make this change?:** To add enough contrast that folks who see colors differently can still decipher the writing on the tabs on this page. We plan to refactor this page and remove the tabs soon, so not too worried about making this fix perfect. **test plan:** Manual testing - loaded the page and it looks ok, and ran aXe a11y audit, no more warnings about contrast. :) (Flarnie will insert a screenshot) **issue:** checklist item on https://github.com/bvaughn/react/wiki/Gatsby-A11y-Fixes
11 KiB
id, title, permalink, redirect_from, next
| id | title | permalink | redirect_from | next | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| installation | Installation | docs/installation.html |
|
hello-world.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.
- Try React
- Create a New App
- Add React to an Existing App
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. 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, 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 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.
npm install -g create-react-app
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 and webpack 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 and the User Guide.
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.
While React can be used without a build pipeline, we recommend setting it up so you can be more productive. A modern build pipeline typically consists of:
- A package manager, such as Yarn or npm. It lets you take advantage of a vast ecosystem of third-party packages, and easily install or update them.
- A bundler, such as webpack or Browserify. It lets you write modular code and bundle it together into small packages to optimize load time.
- A compiler such as Babel. It lets you write modern JavaScript code that still works in older browsers.
Installing React
Note:
Once installed, we strongly recommend setting up a production build process to ensure you're using the fast version of React in production.
We recommend using Yarn or npm for managing front-end dependencies. If you're new to package managers, the Yarn documentation is a good place to get started.
To install React with Yarn, run:
yarn init
yarn add react react-dom
To install React with npm, run:
npm init
npm install --save react react-dom
Both Yarn and npm download packages from the npm registry.
Enabling ES6 and JSX
We recommend using React with Babel to let you use ES6 and JSX in your JavaScript code. ES6 is a set of modern JavaScript features that make development easier, and JSX is an extension to the JavaScript language that works nicely with React.
The Babel setup instructions explain how to configure Babel in many different build environments. Make sure you install babel-preset-react and babel-preset-es2015 and enable them in your .babelrc configuration, and you're good to go.
Hello World with ES6 and JSX
We recommend using a bundler like webpack or Browserify so you can write modular code and bundle it together into small packages to optimize load time.
The smallest React example looks like this:
import React from 'react';
import ReactDOM from 'react-dom';
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
This code renders into a DOM element with the id of root so you need <div id="root"></div> somewhere in your HTML file.
Similarly, you can render a React component inside a DOM element somewhere inside your existing app written with any other JavaScript UI library.
Learn more about integrating React with existing code.
Development and Production Versions
By default, React includes many helpful warnings. These warnings are very useful in development.
However, they make the development version of React larger and slower so you should use the production version when you deploy the app.
Learn how to tell if your website is serving the right version of React, and how to configure the production build process most efficiently:
- Creating a Production Build with Create React App
- Creating a Production Build with Single-File Builds
- Creating a Production Build with Brunch
- Creating a Production Build with Browserify
- Creating a Production Build with Rollup
- Creating a Production Build with webpack
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:
<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
The versions above are only meant for development, and are not suitable for production. Minified and optimized production versions of React are available at:
<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
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 attribute set:
<script crossorigin src="..."></script>
We also recommend to verify that the CDN you are using sets the Access-Control-Allow-Origin: * HTTP header:
This enables a better error handling experience in React 16 and later.