Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Fix] Improve Getting started with iOS #3323

Merged
merged 1 commit into from
Sep 15, 2022
Merged

[Fix] Improve Getting started with iOS #3323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 35 additions & 9 deletions docs/_getting-started-macos-ios.md
View file
Open in desktop
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.
cipolleschi marked this conversation as resolved.
Show resolved Hide resolved

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
cipolleschi marked this conversation as resolved.
Show resolved Hide resolved

[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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Ruby gem" phrase is not friendly for beginners in this space, adds another term specific just for Ruby.

I'd prefer something like this:
"Bundler is a Ruby gem—equivalent of package in Node.js—that helps managing the Ruby dependencies of your project. Think npm or Yarn for Ruby."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I rephrased it a little bit, adding a small introduction to ruby gems


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
View file
Open in desktop
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