Skip to content

Commit

Permalink
[Fix] Improve Getting started with iOS (facebook#3323)
Browse files Browse the repository at this point in the history
  • Loading branch information
Riccardo authored Sep 15, 2022
1 parent 791d9d1 commit 1285a79
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 18 deletions.
44 changes: 35 additions & 9 deletions docs/_getting-started-macos-ios.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import M1Cocoapods from './\_markdown-m1-cocoapods.mdx'; import RemoveGlobalCLI

## Installing dependencies

You will need Node, Watchman, the React Native command line interface, Xcode and CocoaPods.
You will need Node, Watchman, the React Native command line interface, a Ruby version manager, Xcode and CocoaPods.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Expand All @@ -19,6 +19,31 @@ If you have already installed Node on your system, make sure it is Node 14 or ne

[Watchman](https://facebook.github.io/watchman) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

### Ruby

React Native uses a `.ruby-version` file to make sure that your version of Ruby is aligned with what is needed. Currently, macOS 12.5.1 is shipped with Ruby 2.6.8, which is **not** what is required by React Native. Our suggestion is to install a Ruby version manager and to install the proper version of Ruby in your system.

Some common Ruby version manager are:

- [rbenv](https://github.com/rbenv/rbenv)
- [RVM](https://rvm.io/)
- [chruby](https://github.com/postmodern/chruby)
- [asdf-vm](https://github.com/asdf-vm) with the [asdf-ruby](https://github.com/asdf-vm/asdf-ruby) plugin

To check what is your current version of Ruby, you can run this command:

```
ruby --version
```

React Native uses [this version](https://github.com/facebook/react-native/blob/main/template/_ruby-version) of Ruby. You can also find which version your specific project needs in the `.ruby-version` file at root of your RN project.

### Bundler

[Bundler](https://bundler.io/) is a Ruby gem that helps managing the Ruby dependencies of your project. We need Ruby to install Cocoapods and using Bundler will make sure that all the dependencies are aligned and that the project works properly.

If you want to learn more about why we need this tool, you can read [this article](https://bundler.io/guides/rationale.html#bundlers-purpose-and-rationale).

### Xcode

The easiest way to install Xcode is via the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12). Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.
Expand All @@ -39,14 +64,6 @@ To install a simulator, open <strong>Xcode > Preferences...</strong> and select

[CocoaPods](https://cocoapods.org/) is built with Ruby and it will be installable with the default Ruby available on macOS.

Using the default Ruby available on macOS will require you to use `sudo` when installing gems. (This is only an issue for the duration of the gem installation, though.)

```shell
sudo gem install cocoapods
```

Otherwise you can use a Ruby version manager, such as `rbenv`. Apps created with the command `npx react-native init` described below are configured to work well with `rbenv` and will pick the correct Ruby version requested by the template.

For more information, please visit [CocoaPods Getting Started guide](https://guides.cocoapods.org/using/getting-started.html).

<M1Cocoapods />
Expand All @@ -67,6 +84,15 @@ npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see [Integration with Existing Apps](integration-with-existing-apps.md)). You can also use a third-party CLI to init your React Native app, such as [Ignite CLI](https://github.com/infinitered/ignite).

:::info
If you are having trouble with iOS, try to reinstall the dependencies by running:

1. `cd ios` to navigate to the
2. `bundle install` to install Bundler
1. If needed: install a [Ruby Version Manager](#ruby) and update the Ruby version
3. `bundle exec pod install` to install the iOS dependencies.
:::

### [Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the `--version` argument:
Expand Down
44 changes: 35 additions & 9 deletions website/versioned_docs/version-0.70/_getting-started-macos-ios.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import M1Cocoapods from './\_markdown-m1-cocoapods.mdx'; import RemoveGlobalCLI

## Installing dependencies

You will need Node, Watchman, the React Native command line interface, Xcode and CocoaPods.
You will need Node, Watchman, the React Native command line interface, a Ruby version manager, Xcode and CocoaPods.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Expand All @@ -19,6 +19,31 @@ If you have already installed Node on your system, make sure it is Node 14 or ne

[Watchman](https://facebook.github.io/watchman) is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

### Ruby

React Native uses a `.ruby-version` file to make sure that your version of Ruby is aligned with what is needed. Currently, macOS 12.5.1 is shipped with Ruby 2.6.8, which is **not** what is required by React Native. Our suggestion is to install a Ruby version manager and to install the proper version of Ruby in your system.

Some common Ruby version manager are:

- [rbenv](https://github.com/rbenv/rbenv)
- [RVM](https://rvm.io/)
- [chruby](https://github.com/postmodern/chruby)
- [asdf-vm](https://github.com/asdf-vm) with the [asdf-ruby](https://github.com/asdf-vm/asdf-ruby) plugin

To check what is your current version of Ruby, you can run this command:

```
ruby --version
```

React Native uses [this version](https://github.com/facebook/react-native/blob/main/template/_ruby-version) of Ruby. You can also find which version your specific project needs in the `.ruby-version` file at root of your RN project.

### Bundler

[Bundler](https://bundler.io/) is a Ruby gem that helps managing the Ruby dependencies of your project. We need Ruby to install Cocoapods and using Bundler will make sure that all the dependencies are aligned and that the project works properly.

If you want to learn more about why we need this tool, you can read [this article](https://bundler.io/guides/rationale.html#bundlers-purpose-and-rationale).

### Xcode

The easiest way to install Xcode is via the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12). Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.
Expand All @@ -39,14 +64,6 @@ To install a simulator, open <strong>Xcode > Preferences...</strong> and select

[CocoaPods](https://cocoapods.org/) is built with Ruby and it will be installable with the default Ruby available on macOS.

Using the default Ruby available on macOS will require you to use `sudo` when installing gems. (This is only an issue for the duration of the gem installation, though.)

```shell
sudo gem install cocoapods
```

Otherwise you can use a Ruby version manager, such as `rbenv`. Apps created with the command `npx react-native init` described below are configured to work well with `rbenv` and will pick the correct Ruby version requested by the template.

For more information, please visit [CocoaPods Getting Started guide](https://guides.cocoapods.org/using/getting-started.html).

<M1Cocoapods />
Expand All @@ -67,6 +84,15 @@ npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see [Integration with Existing Apps](integration-with-existing-apps.md)). You can also use a third-party CLI to init your React Native app, such as [Ignite CLI](https://github.com/infinitered/ignite).

:::info
If you are having trouble with iOS, try to reinstall the dependencies by running:

1. `cd ios` to navigate to the
2. `bundle install` to install Bundler
1. If needed: install a [Ruby Version Manager](#ruby) and update the Ruby version
3. `bundle exec pod install` to install the iOS dependencies.
:::

### [Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the `--version` argument:
Expand Down

0 comments on commit 1285a79

Please sign in to comment.