diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 7fb22ab92863fc..2c748ca8f1fab4 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -146,6 +146,8 @@ Because you don't build any native code when using Create React Native App to cr If you know that you'll eventually need to include your own native code, Create React Native App is still a good way to get started. In that case you'll just need to "[eject](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md#ejecting-from-create-react-native-app)" eventually to create your own native builds. If you do eject, the "Building Projects with Native Code" instructions will be required to continue working on your project. +Create React Native App configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check [this document](https://github.com/react-community/create-react-native-app/blob/master/VERSIONS.md) to find out what versions are supported. + If you're integrating React Native into an existing project, you'll want to skip Create React Native App and go directly to setting up the native build environment. Select "Building Projects with Native Code" above for instructions on configuring a native build environment for React Native. diff --git a/docs/Upgrading.md b/docs/Upgrading.md index d7118b4409b533..2b1196db24c9d7 100644 --- a/docs/Upgrading.md +++ b/docs/Upgrading.md @@ -1,61 +1,66 @@ --- id: upgrading -title: Upgrading +title: Upgrading to new React Native versions layout: docs category: Guides permalink: docs/upgrading.html -banner: ejected next: native-modules-ios previous: understanding-cli --- -Upgrading to new versions of React Native will give you access to more APIs, views, developer tools -and other goodies. Because React Native projects are essentially made up of an Android project, an -iOS project and a JavaScript project, all combined under an npm package, upgrading can be rather -tricky. But we try to make it easy for you. Here's what you need to do to upgrade from an older -version of React Native: +Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it easy for you. The instructions are a bit different depending on whether you used `create-react-native-app` or `react-native init` to create your project. -## Upgrade based on Git +## Create React Native App projects -**IMPORTANT:** You don't have to install the new version of React Native, it will be installed automatically. +Upgrading your Create React Native App project to a new version of React Native requires updating the `react-native`, `react`, and `expo` package versions in your `package.json` file. Please refer to [this document](https://github.com/react-community/create-react-native-app/blob/master/VERSIONS.md) to find out what versions are supported. You will also need to set the correct `sdkVersion` in your `app.json` file. -The module `react-native-git-upgrade` provides a one-step operation to upgrade the source files with -a minimum of conflicts. Under the hood, it consists in 2 phases: +See the [CRNA user guide](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md#updating-to-new-releases) for up-to-date information about upgrading your project. + +## Projects built with native code + + + +Because React Native projects built with native code are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. Here's what you need to do to upgrade from an older version of React Native. + +### Upgrade based on Git + +The module `react-native-git-upgrade` provides a one-step operation to upgrade the source files with a minimum of conflicts. Under the hood, it consists in 2 phases: * First, it computes a Git patch between both old and new template files, * Then, the patch is applied on the user's sources. -### 1. Install Git -Your project doesn't have to be handled by the Git versioning system (could be Mercurial, SVN or none) -but Git has to be installed and available in the `PATH`. You can download Git here: -https://git-scm.com/downloads +> **IMPORTANT:** You don't have to install the new version of the `react-native` package, it will be installed automatically. + +#### 1. Install Git -### 2. Install the `react-native-git-upgrade` module +While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to [install Git](https://git-scm.com/downloads) on your system in order to use `react-native-git-upgrade`. Git will also need to be available in the `PATH`. -It's a CLI tool and must be installed globally: +#### 2. Install the `react-native-git-upgrade` module + +The `react-native-git-upgrade` module provides a CLI and must be installed globally: ```sh $ npm install -g react-native-git-upgrade ``` -### 3. Run the command +#### 3. Run the command -Run the command to start the process: +Run the following command to start the process of upgrading to the latest version: ```sh $ react-native-git-upgrade -# Upgrade React Native to the latest version - -# Or: - -$ react-native-git-upgrade X.Y.Z -# Upgrade React Native to the X.Y.Z version ``` -The templates are upgraded in a optimized way. You still may encounter conflicts but only where the Git -3-way merge have failed, depending on the version and how you modified your sources. +> You may specify a React Native version by passing an argument: `react-native-git-upgrade X.Y` -### 4. Resolve the conflicts +The templates are upgraded in a optimized way. You still may encounter conflicts but only where the Git 3-way merge have failed, depending on the version and how you modified your sources. + +#### 4. Resolve the conflicts Conflicted files include delimiters which make very clear where the changes come from. For example: @@ -84,15 +89,13 @@ Conflicted files include delimiters which make very clear where the changes come You can think of "ours" as "your team" and "theirs" as "the React Native dev team". -## Alternative +### Alternative Use this only in case the above didn't work. -### 1. Upgrade the `react-native` dependency - -Note the latest version of the `react-native` npm package from here (or use `npm info react-native` to check): +#### 1. Upgrade the `react-native` dependency -* https://www.npmjs.com/package/react-native +Note the latest version of the `react-native` npm package [from here](https://www.npmjs.com/package/react-native) (or use `npm info react-native` to check). Now install that version of `react-native` in your project with `npm install --save`: @@ -108,7 +111,7 @@ $ npm install --save react@R # where R is the new version of react from the peerDependency warning you saw ``` -### 2. Upgrade your project templates +#### 2. Upgrade your project templates The new npm package may contain updates to the files that are normally generated when you run `react-native init`, like the iOS and the Android sub-projects. @@ -126,10 +129,8 @@ This will check your files against the latest template and perform the following * If there is a new file in the template, it is simply created. * If a file in the template is identical to your file, it is skipped. -* If a file is different in your project than the template, you will be prompted; you have options - to keep your file or overwrite it with the template version. - +* If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version. -# Manual Upgrades +## Manual Upgrades Some upgrades require manual steps, e.g. 0.13 to 0.14, or 0.28 to 0.29. Be sure to check the [release notes](https://github.com/facebook/react-native/releases) when upgrading so that you can identify any manual changes your particular project may require. diff --git a/website/src/react-native/versions.js b/website/src/react-native/versions.js index 80657f1ecb15cd..7dfe3ecd07f752 100644 --- a/website/src/react-native/versions.js +++ b/website/src/react-native/versions.js @@ -14,7 +14,9 @@ var Site = require('Site'); module.exports = React.createClass({ render: function() { - var availableDocs = (Metadata.config.RN_AVAILABLE_DOCS_VERSIONS || '').split(','); + var availableDocs = (Metadata.config.RN_AVAILABLE_DOCS_VERSIONS || + '') + .split(','); var latestVersion = Metadata.config.RN_LATEST_VERSION; var versions = [ @@ -24,22 +26,31 @@ module.exports = React.createClass({ release: null, type: 'master', }, - ].concat(availableDocs.map((version) => { - const isLatest = latestVersion === version; - const isRC = latestVersion < version; + ].concat( + availableDocs.map(version => { + const isLatest = latestVersion === version; + const isRC = latestVersion < version; - var title = version; - if (isRC) { - title += '-RC'; - } + var title = version; + if (isRC) { + title += '-RC'; + } - return { - title: title, - path: isLatest ? '/react-native' : '/react-native/releases/' + version, - release: 'https://github.com/facebook/react-native/releases/tag/v' + version + '.0' + (isRC ? '-rc.0' : ''), - type: isLatest ? 'latest' : (isRC ? 'release-candidate' : 'release'), - }; - })); + return { + title: title, + path: isLatest + ? '/react-native' + : '/react-native/releases/' + version, + release: 'https://github.com/facebook/react-native/releases/tag/v' + + version + + '.0' + + (isRC ? '-rc.0' : ''), + type: isLatest + ? 'latest' + : isRC ? 'release-candidate' : 'release', + }; + }) + ); if (!latestVersion) { versions = [ @@ -58,9 +69,11 @@ module.exports = React.createClass({ var masters = versions.filter(function(version) { return version.type === 'master'; }); - var releaseCandidates = versions.filter(function(version) { - return version.type === 'release-candidate'; - }); + var releaseCandidates = versions.filter( + function(version) { + return version.type === 'release-candidate'; + } + ); var releases = versions.filter(function(version) { return version.type === 'release'; }); @@ -68,66 +81,144 @@ module.exports = React.createClass({ // Note: Our Algolia DocSearch box supports version-specific queries. If you will be drastically changing the way versions are listed in this page, make sure https://github.com/algolia/docsearch-configs/blob/master/configs/react-native-versions.json is updated accordingly. return ( - -
+ +

React Native Versions

-

React Native follows a monthly release train. Every month, a new branch created off master enters the Release Candidate phase, and the previous Release Candidate branch is released and considered stable.

+

+ React Native follows a monthly release train. Every month, a new branch created off master enters the + {' '} + + Release Candidate + + {' '} + phase, and the previous Release Candidate branch is released and considered + {' '} + stable + . +

+

+ If you have an existing project that uses React Native, read the release notes to learn about new features and fixes. You can follow + {' '} + + our guide to upgrade your app + + {' '} + to the latest version. +

-

Current Version (Stable)

+

Current version (Stable)

- {latests.map((version) => + {latests.map(version => ( - - + + - )} + ))}
{version.title}Documentation{version.release && Release Notes} + + Documentation + + + {version.release && + + Release Notes + } +
-

This is the version that is configured automatically when you run react-native init. We highly recommend using the current version of React Native when starting a new project.

-

If you have an existing project that uses React Native, read the release notes to learn about new features and fixes. You can follow our guide to upgrade your app to the latest version.

+

+ This is the version that is configured automatically when you create a new project using + {' '} + react-native init + . +

-

Pre-release Versions

+

Pre-release versions

- {masters.map((version) => + {masters.map(version => ( - - + + - )} - {releaseCandidates.map((version) => + ))} + {releaseCandidates.map(version => ( - - + + - )} + ))}
masterDocumentation{version.release && Release Notes} + + Documentation + + + {version.release && + + Release Notes + } +
{version.title}Documentation{version.release && Release Notes} + + Documentation + + + {version.release && + + Release Notes + } +
-

For those who live on the bleeding edge. Only recommended if you're actively contributing code to React Native, or if you need to verify how your application behaves in an upcoming release.

+

+ To see what changes are coming and provide better feedback to React Native contributors, use the latest release candidate when possible. By the time a release candidate is released, the changes it contains will have been shipped in production Facebook apps for over two weeks. +

-

Past Versions

+

Past versions

- {releases.map((version) => + {releases.map(version => ( - - + + - )} + ))}
{version.title}Documentation{version.release && Release Notes} + + Documentation + + + {version.release && + + Release Notes + } +
-

You can find past versions of React Native on GitHub. The release notes can be useful if you would like to learn when a specific feature or fix was released.

-

You can also view the docs for a particular version of React Native by clicking on the Docs link next to the release in this page. You can come back to this page and switch the version of the docs you're reading at any time by clicking on the version number at the top of the page.

+

+ You can find past versions of React Native + {' '} + + on GitHub + + . The release notes can be useful if you would like to learn when a specific feature or fix was released. +

+

+ You can also view the docs for a particular version of React Native by clicking on the Docs link next to the release in this page. You can come back to this page and switch the version of the docs you're reading at any time by clicking on the version number at the top of the page. +

); - } + }, });