|
| 1 | +# Create React App [](https://travis-ci.org/facebookincubator/create-react-app) |
| 2 | + |
| 3 | +Create React apps with no build configuration. |
| 4 | + |
| 5 | +* [Creating an App](#creating-an-app) – How to create a new app. |
| 6 | +* [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md) – How to develop apps bootstrapped with Create React App. |
| 7 | + |
| 8 | +Create React App works on macOS, Windows, and Linux.<br> |
| 9 | +If something doesn’t work, please [file an issue](https://github.com/facebookincubator/create-react-app/issues/new). |
| 10 | + |
| 11 | +## Quick Overview |
| 12 | + |
| 13 | +```sh |
| 14 | +npx create-react-app my-app |
| 15 | +cd my-app |
| 16 | +npm start |
| 17 | +``` |
| 18 | + |
| 19 | +*([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))* |
| 20 | + |
| 21 | +Then open [http://localhost:3000/](http://localhost:3000/) to see your app.<br> |
| 22 | +When you’re ready to deploy to production, create a minified bundle with `npm run build`. |
| 23 | + |
| 24 | +<p align='center'> |
| 25 | +<img src='https://cdn.rawgit.com/facebookincubator/create-react-app/6ab67e6b96457720d843aa3c557ff951a41bafc2/screencast.svg' width='600' alt=''> |
| 26 | +</p> |
| 27 | + |
| 28 | +### Get Started Immediately |
| 29 | + |
| 30 | +You **don’t** need to install or configure tools like Webpack or Babel.<br> |
| 31 | +They are preconfigured and hidden so that you can focus on the code. |
| 32 | + |
| 33 | +Just create a project, and you’re good to go. |
| 34 | + |
| 35 | +## Creating an App |
| 36 | + |
| 37 | +**You’ll need to have Node >= 6 on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to easily switch Node versions between different projects. |
| 38 | + |
| 39 | +To create a new app, run a single command: |
| 40 | + |
| 41 | +```sh |
| 42 | +npx create-react-app my-app |
| 43 | +``` |
| 44 | + |
| 45 | +*([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))* |
| 46 | + |
| 47 | +It will create a directory called `my-app` inside the current folder.<br> |
| 48 | +Inside that directory, it will generate the initial project structure and install the transitive dependencies: |
| 49 | + |
| 50 | +``` |
| 51 | +my-app |
| 52 | +├── README.md |
| 53 | +├── node_modules |
| 54 | +├── package.json |
| 55 | +├── .gitignore |
| 56 | +├── public |
| 57 | +│ └── favicon.ico |
| 58 | +│ └── index.html |
| 59 | +│ └── manifest.json |
| 60 | +└── src |
| 61 | + └── App.css |
| 62 | + └── App.js |
| 63 | + └── App.test.js |
| 64 | + └── index.css |
| 65 | + └── index.js |
| 66 | + └── logo.svg |
| 67 | + └── registerServiceWorker.js |
| 68 | +``` |
| 69 | + |
| 70 | +No configuration or complicated folder structures, just the files you need to build your app.<br> |
| 71 | +Once the installation is done, you can open your project folder: |
| 72 | + |
| 73 | +```sh |
| 74 | +cd my-app |
| 75 | +``` |
| 76 | + |
| 77 | +Inside the newly created project, you can run some built-in commands: |
| 78 | + |
| 79 | +### `npm start` or `yarn start` |
| 80 | + |
| 81 | +Runs the app in development mode.<br> |
| 82 | +Open [http://localhost:3000](http://localhost:3000) to view it in the browser. |
| 83 | + |
| 84 | +The page will automatically reload if you make changes to the code.<br> |
| 85 | +You will see the build errors and lint warnings in the console. |
| 86 | + |
| 87 | +<img src='https://camo.githubusercontent.com/41678b3254cf583d3186c365528553c7ada53c6e/687474703a2f2f692e696d6775722e636f6d2f466e4c566677362e706e67' width='600' alt='Build errors'> |
| 88 | + |
| 89 | +### `npm test` or `yarn test` |
| 90 | + |
| 91 | +Runs the test watcher in an interactive mode.<br> |
| 92 | +By default, runs tests related to files changed since the last commit. |
| 93 | + |
| 94 | +[Read more about testing.](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#running-tests) |
| 95 | + |
| 96 | +### `npm run build` or `yarn build` |
| 97 | + |
| 98 | +Builds the app for production to the `build` folder.<br> |
| 99 | +It correctly bundles React in production mode and optimizes the build for the best performance. |
| 100 | + |
| 101 | +The build is minified and the filenames include the hashes.<br> |
| 102 | +By default, it also [includes a service worker](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app) so that your app loads from local cache on future visits. |
| 103 | + |
| 104 | +Your app is ready to be deployed. |
| 105 | + |
| 106 | +## User Guide |
| 107 | + |
| 108 | +The [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md) includes information on different topics, such as: |
| 109 | + |
| 110 | +- [Updating to New Releases](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#updating-to-new-releases) |
| 111 | +- [Folder Structure](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#folder-structure) |
| 112 | +- [Available Scripts](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#available-scripts) |
| 113 | +- [Supported Browsers](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#supported-browsers) |
| 114 | +- [Supported Language Features and Polyfills](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#supported-language-features-and-polyfills) |
| 115 | +- [Syntax Highlighting in the Editor](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#syntax-highlighting-in-the-editor) |
| 116 | +- [Displaying Lint Output in the Editor](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#displaying-lint-output-in-the-editor) |
| 117 | +- [Formatting Code Automatically](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#formatting-code-automatically) |
| 118 | +- [Debugging in the Editor](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#debugging-in-the-editor) |
| 119 | +- [Changing the Page `<title>`](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#changing-the-page-title) |
| 120 | +- [Installing a Dependency](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#installing-a-dependency) |
| 121 | +- [Importing a Component](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#importing-a-component) |
| 122 | +- [Code Splitting](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#code-splitting) |
| 123 | +- [Adding a Stylesheet](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-a-stylesheet) |
| 124 | +- [Post-Processing CSS](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#post-processing-css) |
| 125 | +- [Adding a CSS Preprocessor (Sass, Less etc.)](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-a-css-preprocessor-sass-less-etc) |
| 126 | +- [Adding Images, Fonts, and Files](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-images-fonts-and-files) |
| 127 | +- [Using the `public` Folder](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#using-the-public-folder) |
| 128 | +- [Using Global Variables](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#using-global-variables) |
| 129 | +- [Adding Bootstrap](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-bootstrap) |
| 130 | +- [Adding Flow](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-flow) |
| 131 | +- [Adding a Router](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-a-router) |
| 132 | +- [Adding Custom Environment Variables](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-custom-environment-variables) |
| 133 | +- [Can I Use Decorators?](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#can-i-use-decorators) |
| 134 | +- [Fetching Data with AJAX Requests](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#fetching-data-with-ajax-requests) |
| 135 | +- [Integrating with an API Backend](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#integrating-with-an-api-backend) |
| 136 | +- [Proxying API Requests in Development](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#proxying-api-requests-in-development) |
| 137 | +- [Using HTTPS in Development](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#using-https-in-development) |
| 138 | +- [Generating Dynamic `<meta>` Tags on the Server](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#generating-dynamic-meta-tags-on-the-server) |
| 139 | +- [Pre-Rendering into Static HTML Files](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#pre-rendering-into-static-html-files) |
| 140 | +- [Running Tests](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#running-tests) |
| 141 | +- [Debugging Tests](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#debugging-tests) |
| 142 | +- [Developing Components in Isolation](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#developing-components-in-isolation) |
| 143 | +- [Publishing Components to npm](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#publishing-components-to-npm) |
| 144 | +- [Making a Progressive Web App](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app) |
| 145 | +- [Analyzing the Bundle Size](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#analyzing-the-bundle-size) |
| 146 | +- [Deployment](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#deployment) |
| 147 | +- [Advanced Configuration](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#advanced-configuration) |
| 148 | +- [Troubleshooting](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#troubleshooting) |
| 149 | + |
| 150 | +A copy of the user guide will be created as `README.md` in your project folder. |
| 151 | + |
| 152 | +## How to Update to New Versions? |
| 153 | + |
| 154 | +Please refer to the [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#updating-to-new-releases) for this and other information. |
| 155 | + |
| 156 | +## Philosophy |
| 157 | + |
| 158 | +* **One Dependency:** There is just one build dependency. It uses Webpack, Babel, ESLint, and other amazing projects, but provides a cohesive curated experience on top of them. |
| 159 | + |
| 160 | +* **No Configuration Required:** You don't need to configure anything. Reasonably good configuration of both development and production builds is handled for you so you can focus on writing code. |
| 161 | + |
| 162 | +* **No Lock-In:** You can “eject” to a custom setup at any time. Run a single command, and all the configuration and build dependencies will be moved directly into your project, so you can pick up right where you left off. |
| 163 | + |
| 164 | +## What’s Included? |
| 165 | + |
| 166 | +Your environment will have everything you need to build a modern single-page React app: |
| 167 | + |
| 168 | +* React, JSX, ES6, and Flow syntax support. |
| 169 | +* Language extras beyond ES6 like the object spread operator. |
| 170 | +* Autoprefixed CSS, so you don’t need `-webkit` or other prefixes. |
| 171 | +* A fast interactive unit test runner with built-in support for coverage reporting. |
| 172 | +* A live development server that warns about common mistakes. |
| 173 | +* A build script to bundle JS, CSS, and images for production, with hashes and sourcemaps. |
| 174 | +* An offline-first [service worker](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers) and a [web app manifest](https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/), meeting all the [Progressive Web App](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app) criteria. |
| 175 | +* Hassle-free updates for the above tools with a single dependency. |
| 176 | + |
| 177 | +Check out [this guide](https://github.com/nitishdayal/cra_closer_look) for an overview of how these tools fit together. |
| 178 | + |
| 179 | +The tradeoff is that **these tools are preconfigured to work in a specific way**. If your project needs more customization, you can ["eject"](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#npm-run-eject) and customize it, but then you will need to maintain this configuration. |
| 180 | + |
| 181 | +## Popular Alternatives |
| 182 | + |
| 183 | +Create React App is a great fit for: |
| 184 | + |
| 185 | +* **Learning React** in a comfortable and feature-rich development environment. |
| 186 | +* **Starting new single-page React applications.** |
| 187 | +* **Creating examples** with React for your libraries and components. |
| 188 | + |
| 189 | +Here’s a few common cases where you might want to try something else: |
| 190 | + |
| 191 | +* If you want to **try React** without hundreds of transitive build tool dependencies, consider [using a single HTML file or an online sandbox instead](https://reactjs.org/docs/try-react.html). |
| 192 | + |
| 193 | +* If you need to **integrate React code with a server-side template framework** like Rails or Django, or if you’re **not building a single-page app**, consider using [nwb](https://github.com/insin/nwb) or [Neutrino](https://neutrino.js.org/) which are more flexible. |
| 194 | + |
| 195 | +* If you need to **publish a React component**, [nwb](https://github.com/insin/nwb) can [also do this](https://github.com/insin/nwb#react-components-and-libraries), as well as [Neutrino's react-components preset](https://neutrino.js.org/packages/react-components/). |
| 196 | + |
| 197 | +* If you want to do **server rendering** with React and Node.js, check out [Next.js](https://github.com/zeit/next.js/) or [Razzle](https://github.com/jaredpalmer/razzle). Create React App is agnostic of the backend, and just produces static HTML/JS/CSS bundles. |
| 198 | + |
| 199 | +* If your website is **mostly static** (for example, a portfolio or a blog), consider using [Gatsby](https://www.gatsbyjs.org/) instead. Unlike Create React App, it pre-renders the website into HTML at the build time. |
| 200 | + |
| 201 | +* If you want to use **TypeScript**, consider using [create-react-app-typescript](https://github.com/wmonk/create-react-app-typescript). |
| 202 | + |
| 203 | +* Finally, if you need **more customization**, check out [Neutrino](https://neutrino.js.org/) and its [React preset](https://neutrino.js.org/packages/react/). |
| 204 | + |
| 205 | +All of the above tools can work with little to no configuration. |
| 206 | + |
| 207 | +If you prefer configuring the build yourself, [follow this guide](https://reactjs.org/docs/add-react-to-an-existing-app.html). |
| 208 | + |
| 209 | +## Contributing |
| 210 | + |
| 211 | +We'd love to have your helping hand on `create-react-app`! See [CONTRIBUTING.md](CONTRIBUTING.md) for more information on what we're looking for and how to get started. |
| 212 | + |
| 213 | +## React Native |
| 214 | + |
| 215 | +Looking for something similar, but for React Native?<br> |
| 216 | +Check out [Create React Native App](https://github.com/react-community/create-react-native-app/). |
| 217 | + |
| 218 | +## Acknowledgements |
| 219 | + |
| 220 | +We are grateful to the authors of existing related projects for their ideas and collaboration: |
| 221 | + |
| 222 | +* [@eanplatter](https://github.com/eanplatter) |
| 223 | +* [@insin](https://github.com/insin) |
| 224 | +* [@mxstbr](https://github.com/mxstbr) |
0 commit comments