From 6078e001e63da7bdebeb72d0b342532a51064f2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 19 Apr 2019 22:06:19 +0200 Subject: [PATCH 1/3] docs: update and rearrange documentation --- README.md | 41 +- docs/autolinking.md | 3 + docs/commands.md | 429 ++++++++++++++++++ docs/plugins.md | 3 + packages/cli/README.md | 238 +--------- packages/cli/src/commands/server/runServer.js | 3 - packages/cli/src/commands/server/server.js | 8 - .../src/commands/logAndroid/index.js | 2 +- 8 files changed, 473 insertions(+), 254 deletions(-) create mode 100644 docs/autolinking.md create mode 100644 docs/commands.md create mode 100644 docs/plugins.md diff --git a/README.md b/README.md index adef7f5bd..e8b403f32 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,56 @@ # React Native CLI -Command Line Interface for React Native. +Command line tools to interact with React Native projects. [![Build Status][build-badge]][build] [![Version][version-badge]][package] [![MIT License][license-badge]][license] [![PRs Welcome][prs-welcome-badge]][prs-welcome] _Note: CLI has been extracted from core `react-native` as a part of "[Lean Core](https://github.com/facebook/react-native/issues/23313)" effort. Please read [this blog post](https://blog.callstack.io/the-react-native-cli-has-a-new-home-79b63838f0e6) for more details._ +## Compatibility + +This CLI is intended to be used with a certain version of React Native. You'll find the support table with compatible versions below. + +| CLI | React Native | +| ------ | ------------ | +| ^2.0.0 | ^0.60.0 | +| ^1.0.0 | ^0.59.0 | + +## Documentation + +- [commands](./docs/commands.md) +- [autolinking](./docs/autolinking.md) +- [plugins](./docs/plugins.md) + ## About This repository contains tools and helpers for React Native projects in form of a CLI. We want to make a couple of things clear for you first: - this is a monorepo; -- there are currently two CLIs: the actual one called [`@react-native-community/cli`](./packages/cli) that does all the job and global `react-native-cli` which is used as its proxy; +- there are currently two CLIs: the actual one called [`@react-native-community/cli`](./packages/cli) that does all the job and global [`react-native-cli`](./packages/global-cli) which is used as its proxy and installation helper; We know it's confusing, but we're actively working to make this indirection gone. ## Creating a new React Native project -To start a new React Native project, you'll need to install a global module [`react-native-cli`](./packages/global-cli) and follow instructions there. +There are two ways to start a React Native project. + +### Using `npx` + +> Available since `react-native@0.60` + +This method is preferred if you don't want to install global packages. + +```sh +npx react-native init MyApp +``` + +### Using global CLI + +You'll need to install a global module [`react-native-cli`](./packages/global-cli) and follow instructions there. We strongly encourage you to **only use global `react-native-cli` for bootstrapping new projects**. Use local version for everything else. -## Usage in existing React Native project +## Usage in an existing React Native project Once you're inside an existing project, a local `react-native` binary will be available for you to use. Feel free to use Yarn to call it directly. @@ -49,8 +78,8 @@ Everything inside this repository is [MIT licensed](./LICENSE). -[build-badge]: https://img.shields.io/circleci/project/github/react-native-community/react-native-cli/master.svg?style=flat-square -[build]: https://circleci.com/gh/react-native-community/react-native-cli/tree/master +[build-badge]: https://img.shields.io/circleci/project/github/react-native-community/cli/master.svg?style=flat-square +[build]: https://circleci.com/gh/react-native-community/cli/tree/master [version-badge]: https://img.shields.io/npm/v/@react-native-community/cli.svg?style=flat-square [package]: https://www.npmjs.com/package/@react-native-community/cli.svg [license-badge]: https://img.shields.io/npm/l/@react-native-community/cli.svg?style=flat-square diff --git a/docs/autolinking.md b/docs/autolinking.md new file mode 100644 index 000000000..f4898ba55 --- /dev/null +++ b/docs/autolinking.md @@ -0,0 +1,3 @@ +# Autolinking + +TBD diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 000000000..db51d3547 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,429 @@ +# Commands + +React Native CLI comes with following commands: + +- [`bundle`](#bundle) +- [`config`](#config) +- [`info`](#info) +- [`install`](#install) +- [`library`](#library) +- [`link`](#link) +- [`log-android`](#log-android) +- [`log-ios`](#log-ios) +- [`ram-bundle`](#ram-bundle) +- [`run-android`](#run-android) +- [`run-ios`](#run-ios) +- [`start`](#start) +- [`uninstall`](#uninstall) +- [`unlink`](#unlink) +- [`upgrade`](#upgrade) + +### `bundle` + +Usage: + +```sh +react-native bundle +``` + +Builds the JavaScript bundle for offline use. + +#### `--entry-file ` + +Path to the root JS file, either absolute or relative to JS root. + +#### `--platform [string]` + +> default: ios + +Either "ios" or "android". + +#### `--transformer [string]` + +Specify a custom transformer to be used. + +#### `--dev [boolean]` + +> default: true + +If false, warnings are disabled and the bundle is minified. + +#### `--minify [boolean]` + +Allows overriding whether bundle is minified. This defaults to false if dev is true, and true if dev is false. Disabling minification can be useful for speeding up production builds for testing purposes. + +#### `--bundle-output ` + +File name where to store the resulting bundle, ex. `/tmp/groups.bundle`. + +#### `--bundle-encoding [string]` + +> default: utf8 + +Encoding the bundle should be written in (https://nodejs.org/api/buffer.html#buffer_buffer). + +#### `--max-workers [number]` + +Specifies the maximum number of workers the worker-pool will spawn for transforming files. This defaults to the number of the cores available on your machine. + +#### `--sourcemap-output [string]` + +File name where to store the sourcemap file for resulting bundle, ex. `/tmp/groups.map`. + +#### `--sourcemap-sources-root [string]` + +Path to make sourcemaps sources entries relative to, ex. `/root/dir`. + +#### `--sourcemap-use-absolute-path` + +> default: false + +Report SourceMapURL using its full path. + +#### `--assets-dest [string]` + +Directory name where to store assets referenced in the bundle. + +#### `--reset-cache` + +> default: false + +Removes cached files. + +#### `--read-global-cache` + +> default: false + +Try to fetch transformed JS code from the global cache, if configured. + +#### `--config [string]` + +Path to the CLI configuration file. + +### `config` + +Usage: + +```sh +react-native config +``` + +Output project and dependencies configuration in JSON format to stdout. Used by [autolinking](./autolinking.md). + +### `info` + +Usage: + +```sh +react-native info +``` + +Get relevant version info about OS, toolchain and libraries. Useful when sending bug reports. + +### `install` + +Usage: + +```sh +react-native install +``` + +Installs single package from npm and then links native dependencies. If `install` detects `yarn.lock` in your project, it will use Yarn as package manager. Otherwise `npm` will be used. + +### `library` + +Usage: + +```sh +react-native library +``` + +Generates a native library bridge. + +#### `--name ` + +Name of the library to generate. + +### `link` + +> Will be replaced by [autolinking](./autolinking.md) soon. + +Usage: + +```sh +react-native link [packageName] +``` + +Link native dependency or all native dependencies if no `packageName` passed. + +#### Options + +#### `--platforms [list]` + +Pass comma-separated list of platforms to scope `link` to. + +### `log-android` + +Usage: + +```sh +react-native log-android +``` + +Starts [`logkitty`](https://github.com/zamotany/logkitty) displaying pretty Android logs. + +### `log-ios` + +Usage: + +```sh +react-native log-ios +``` + +Starts iOS device syslog tail. + +### `ram-bundle` + +Usage: + +```sh +react-native ram-bundle [options] +``` + +Builds JavaScript as a "Random Access Module" bundle for offline use. + +#### Options + +Accepts all of [bundle commands](#bundle) and following: + +#### `--indexed-ram-bundle` + +Force the "Indexed RAM" bundle file format, even when building for Android. + +### `run-android` + +Usage: + +```sh +react-native run-android [options] +``` + +Builds your app and starts it on a connected Android emulator or device. + +#### Options + +#### `--install-debug` + +#### `--root [string]` + +Override the root directory for the Android build (which contains the android directory)'. + +#### `--variant [string]` + +> default: 'debug' + +#### `--appFolder [string]` + +> default: 'app' + +Specify a different application folder name for the Android source. If not, we assume is "app". + +#### `--appId [string]` + +Specify an `applicationId` to launch after build. + +#### `--appIdSuffix [string]` + +Specify an `applicationIdSuffix` to launch after build. + +#### `--main-activity [string]` + +> default: 'MainActivity' + +Name of the activity to start. + +#### `--deviceId [string]` + +builds your app and starts it on a specific device/simulator with the given device id (listed by running "adb devices" on the command line). + +#### `--no-packager` + +Do not launch packager while building. + +#### `--port [number]` + +> default: process.env.RCT_METRO_PORT || 8081, + +#### `--terminal [string]` + +> default: process.env.REACT_TERMINAL || process.env.TERM_PROGRAM + +Launches the Metro Bundler in a new window using the specified terminal path. + +### `run-ios` + +Usage: + +```sh +react-native run-ios [options] +``` + +Builds your app and starts it on iOS simulator. + +#### Options + +#### `--simulator [simulator_name]` + +Explicitly set the simulator to use. Optionally include iOS version between parenthesis at the end to match an exact version, e.g. `"iPhone 6 (10.0)"`. + +Default: `"iPhone X"` + +Notes: `simulator_name` must be a valid iOS simulator name. If in doubt, open your AwesomeApp/ios/AwesomeApp.xcodeproj folder on XCode and unroll the dropdown menu containing the simulator list. The dropdown menu is situated on the right hand side of the play button (top left corner). + +Example: this will launch your projet directly onto the iPhone XS Max simulator: + +```sh +react-native run-ios --simulator "iPhone XS Max" +``` + +#### `--configuration [string]` + +Explicitly set the scheme configuration to use default: 'Debug'. + +#### `--scheme [string]` + +Explicitly set Xcode scheme to use. + +#### `--project-path [string]` + +Path relative to project root where the Xcode project (.xcodeproj) lives. default: 'ios'. + +#### `--device [string]` + +Explicitly set device to use by name. The value is not required if you have a single device connected. + +#### `--udid [string]` + +Explicitly set device to use by udid. + +#### `--no-packager` + +Do not launch packager while building. + +#### `--verbose` + +Do not use `xcpretty` even if installed. + +#### `--port [number]` + +Runs packager on specified port + +Default: `process.env.RCT_METRO_PORT || 8081` + +### `start` + +Usage: + +``` +react-native start [option] +``` + +Starts the server that communicates with connected devices + +#### Options + +#### `--port [number]` + +Specify port to listen on + +#### `--watchFolders [list]` + +Specify any additional folders to be added to the watch list + +#### `--assetExts [list]` + +Specify any additional asset extensions to be used by the packager + +#### `--sourceExts [list]` + +Specify any additional source extensions to be used by the packager + +#### `--platforms [list]` + +Specify any additional platforms to be used by the packager + +#### `--providesModuleNodeModules [list]` + +Specify any npm packages that import dependencies with providesModule + +#### `--max-workers [number]` + +Specifies the maximum number of workers the worker-pool will spawn for transforming files. This defaults to the number of the cores available on your machine + +#### `--transformer [string]` + +Specify a custom transformer to be used + +#### `--reset-cache, --resetCache` + +Removes cached files + +#### `--custom-log-reporter-path, --customLogReporterPath [string]` + +Path to a JavaScript file that exports a log reporter as a replacement for TerminalReporter + +#### `--verbose` + +Enables logging + +#### `--https` + +Enables https connections to the server + +#### `--key [path]` + +Path to custom SSL key + +#### `--cert [path]` + +Path to custom SSL cert + +#### `--config [string]` + +Path to the CLI configuration file + +### `uninstall` + +Usage: + +```sh +react-native uninstall +``` + +Unlinks single package native dependencies and then uninstalls it from `package.json`. If `uninstall` detects `yarn.lock` in your project, it will use Yarn as package manager. Otherwise `npm` will be used. + +### `unlink` + +> Will be replaced by [autolinking](./autolinking.md) soon. + +Usage: + +``` +react-native unlink +``` + +Unlink native dependency linked with the `link` command. + +### `upgrade` + +Usage: + +```sh +react-native upgrade [npm-version] +``` + +Upgrade your app's template files to the specified or latest npm version using [rn-diff-purge](https://github.com/react-native-community/rn-diff-purge) project. Only valid semver versions are allowed. + +Using this command is a recommended way of upgrading relatively simple React Native apps with not too many native libraries linked. The more iOS and Android build files are modified, the higher chance for a conflicts. The command will guide you on how to continue upgrade process manually in case of failure. + +_Note: If you'd like to upgrade using this method from React Native version lower than 0.59.0, you may use a standalone version of this CLI: `npx @react-native-community/cli upgrade`._ diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 000000000..88db0a547 --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,3 @@ +# Plugins + +TBD diff --git a/packages/cli/README.md b/packages/cli/README.md index 1e49d90c4..09780d1a5 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -2,240 +2,6 @@ Command line tools to interact with React Native projects. -## Commands +This package contains source code for `@react-native-community/cli`, the actual CLI that comes bundled with React Native. You don't need to install it separately in your project. -CLI comes with a set of commands and flags you can pass to them. - -- [`bundle`](#bundle) -- [`dependencies`](#dependencies) -- [`info`](#info) -- [`install`](#install) -- [`library`](#library) -- [`link`](#link) -- [`log-android`](#log-android) -- [`log-ios`](#log-ios) -- [`ram-bundle`](#ram-bundle) -- [`run-android`](#run-android) -- [`run-ios`](#run-ios) -- [`start`](#start) -- [`uninstall`](#uninstall) -- [`unlink`](#unlink) -- [`upgrade`](#upgrade) - -_Note: This document is still under development and doesn't represent the full API area._ - -### `bundle` - -### `dependencies` - -### `info` - -### `install` - -Usage: - -```sh -react-native install -``` - -Installs single package from npm and then links native dependencies. If `install` detects `yarn.lock` in your project, it will use Yarn as package manager. Otherwise `npm` will be used. - -### `library` - -### `link` - -Usage: - -```sh -react-native link [packageName] -``` - -Link native dependency or all native dependencies if no `packageName` passed. - -#### Options - -#### `--platforms [list]` - -Pass comma-separated list of platforms to scope `link` to. - -### `log-android` - -### `log-ios` - -### `ram-bundle` - -### `run-android` - -### `run-ios` - -Usage: - -```sh -react-native run-ios [options] -``` - -Builds your app and starts it on iOS simulator. - -#### Options - -#### `--simulator [simulator_name]` - -Explicitly set the simulator to use. Optionally include iOS version between parenthesis at the end to match an exact version, e.g. `"iPhone 6 (10.0)"`. - -Default: `"iPhone X"` - -Notes: `simulator_name` must be a valid iOS simulator name. If in doubt, open your AwesomeApp/ios/AwesomeApp.xcodeproj folder on XCode and unroll the dropdown menu containing the simulator list. The dropdown menu is situated on the right hand side of the play button (top left corner). - -Example: this will launch your projet directly onto the iPhone XS Max simulator: - -```sh -react-native run-ios --simulator "iPhone XS Max" -``` - -#### `--configuration [string]` - -Explicitly set the scheme configuration to use default: 'Debug'. - -#### `--scheme [string]` - -Explicitly set Xcode scheme to use. - -#### `--project-path [string]` - -Path relative to project root where the Xcode project (.xcodeproj) lives. default: 'ios'. - -#### `--device [string]` - -Explicitly set device to use by name. The value is not required if you have a single device connected. - -#### `--udid [string]` - -Explicitly set device to use by udid. - -#### `--no-packager` - -Do not launch packager while building. - -#### `--verbose` - -Do not use `xcpretty` even if installed. - -#### `--port [number]` - -Runs packager on specified port - -Default: `process.env.RCT_METRO_PORT || 8081` - -### `start` - -Usage: - -``` -react-native start [option] -``` - -Starts the server that communicates with connected devices - -#### Options - -#### `--port [number]` - -Specify port to listen on - -#### `--watchFolders [list]` - -Specify any additional folders to be added to the watch list - -#### `--assetExts [list]` - -Specify any additional asset extensions to be used by the packager - -#### `--sourceExts [list]` - -Specify any additional source extensions to be used by the packager - -#### `--platforms [list]` - -Specify any additional platforms to be used by the packager - -#### `--providesModuleNodeModules [list]` - -Specify any npm packages that import dependencies with providesModule - -#### `--max-workers [number]` - -Specifies the maximum number of workers the worker-pool will spawn for transforming files. This defaults to the number of the cores available on your machine - -#### `--skipflow` - -Disable flow checks - -#### `--nonPersistent` - -Disable file watcher - -#### `--transformer [string]` - -Specify a custom transformer to be used - -#### `--reset-cache, --resetCache` - -Removes cached files - -#### `--custom-log-reporter-path, --customLogReporterPath [string]` - -Path to a JavaScript file that exports a log reporter as a replacement for TerminalReporter - -#### `--verbose` - -Enables logging - -#### `--https` - -Enables https connections to the server - -#### `--key [path]` - -Path to custom SSL key - -#### `--cert [path]` - -Path to custom SSL cert - -#### `--config [string]` - -Path to the CLI configuration file - -### `uninstall` - -Usage: - -```sh -react-native uninstall -``` - -Unlinks single package native dependencies and then uninstalls it from `package.json`. If `uninstall` detects `yarn.lock` in your project, it will use Yarn as package manager. Otherwise `npm` will be used. - -### `unlink` - -Usage: - -``` -react-native unlink -``` - -Unlink native dependency linked with the `link` command. - -### `upgrade` - -Usage: - -```sh -react-native upgrade [npm-version] -``` - -Upgrade your app's template files to the specified or latest npm version using [rn-diff-purge](https://github.com/react-native-community/rn-diff-purge) project. Only valid semver versions are allowed. - -Using this command is a recommended way of upgrading relatively simple React Native apps with not too many native libraries linked. The more iOS and Android build files are modified, the higher chance for a conflicts. The command will guide you on how to continue upgrade process manually in case of failure. - -_Note: If you'd like to upgrade using this method from React Native version lower than 0.59.0, you may use a standalone version of this CLI: `npx @react-native-community/cli upgrade`._ +See the [list of available commands](../../docs/commands.md). diff --git a/packages/cli/src/commands/server/runServer.js b/packages/cli/src/commands/server/runServer.js index 9d73050df..535955ef5 100644 --- a/packages/cli/src/commands/server/runServer.js +++ b/packages/cli/src/commands/server/runServer.js @@ -19,7 +19,6 @@ import MiddlewareManager from './middleware/MiddlewareManager'; import loadMetroConfig from '../../tools/loadMetroConfig'; export type Args = {| - assetExts?: string[], assetPlugins?: string[], cert?: string, customLogReporterPath?: string, @@ -27,10 +26,8 @@ export type Args = {| https?: boolean, maxWorkers?: number, key?: string, - nonPersistent?: boolean, platforms?: string[], port?: number, - providesModuleNodeModules?: string[], resetCache?: boolean, sourceExts?: string[], transformer?: string, diff --git a/packages/cli/src/commands/server/server.js b/packages/cli/src/commands/server/server.js index e4b5ac073..d5184ac6f 100644 --- a/packages/cli/src/commands/server/server.js +++ b/packages/cli/src/commands/server/server.js @@ -68,14 +68,6 @@ export default { 'cores available on your machine.', parse: (workers: string) => Number(workers), }, - { - command: '--skipflow', - description: 'Disable flow checks', - }, - { - command: '--nonPersistent', - description: 'Disable file watcher', - }, { command: '--transformer [string]', description: 'Specify a custom transformer to be used', diff --git a/packages/platform-android/src/commands/logAndroid/index.js b/packages/platform-android/src/commands/logAndroid/index.js index b17f56b3d..bdeff9190 100644 --- a/packages/platform-android/src/commands/logAndroid/index.js +++ b/packages/platform-android/src/commands/logAndroid/index.js @@ -34,6 +34,6 @@ async function logAndroid() { export default { name: 'log-android', - description: 'starts adb logcat', + description: 'starts logkitty', func: logAndroid, }; From c1d1ed0237197002d9a782c5bd60dd1624c9d873 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 19 Apr 2019 22:47:15 +0200 Subject: [PATCH 2/3] add autolinking base docs --- docs/autolinking.md | 66 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/docs/autolinking.md b/docs/autolinking.md index f4898ba55..9fd5ff862 100644 --- a/docs/autolinking.md +++ b/docs/autolinking.md @@ -1,3 +1,67 @@ # Autolinking -TBD +Autolinking is a mechanism built into CLI that allows adding a dependency with native components for React Native to be as simple as: + +```sh +yarn add react-native-firebase +``` + +## How does it work + +React Native CLI provides a [`config`](./commands.md#config) command which grabs all of the configuration for React Native packages installed in the project (by scanning dependenecies in `package.json`) and outputs it in JSON format. + +This information is then used by the projects advertised as platforms (with `react-native` being a default project supporting both iOS and Android platforms) that implement their autolinking behavior. + +This design ensures consistent settings for any platform and allows `react-native config` to update the implementation of how to source this information (be it specified filenames, entries in the module’s package.json, etc). + +## Platform iOS + +The `Podfile` gets the package metadata from `react-native config` and: + +1. Adds dependencies via CocoaPods dev pods (using files from a local path). +1. Adds build phase scripts to the App project’s build phase. (see examples below) + +This means that all libraries need to ship a Podspec in the root of their folder to work seamlessly. This references the native code that your library depends on, and notes any of its other native dependencies. + +The implementation ensures that a library is imported only once, so if you need to have a custom `pod` directive then including it above the function `use_native_modules!`. + +Script Phases +A project which wants to add an Xcode script phase to a user's app can use the custom support in iOS auto-linking via custom settings in either the project's `package.json` under `"react-native"` or via a `react-native.config.js` file in the root. + +The options for the build phase are passed more-or-less directly to the `Podfile` via `build_phase`. Here's an example of adding the settings in your `package.json`: + +```json +{ + "react-native": + "ios": + "scriptPhases": { + "name": "My Dep pre-parser", + "path": "relative/path/to/script.sh", + "execution_position": "after_compile" + } + } + } +} +``` + +`"path"` is an extra option provided to simplify storing the scripts in your repo, it sets `"script"` for you. You can see all available options [here](https://www.rubydoc.info/gems/cocoapods-core/Pod/Podfile/DSL#script_phase-instance_method). + +See implementation of [native_modules.rb](https://github.com/react-native-community/cli/blob/master/packages/platform-ios/native_modules.rb). + +## Platform Android + +1. At build time, before the build script is run, a first gradle plugin (`settings.gradle`) is ran that takes the package metadata from `react-native config` to dynamically include Android library projects into the build. +1. A second plugin then adds those dependencies to the app project and generates a manifest of React Native packages to include in the fully generated file `/android/build/generated/rn/src/main/java/com/facebook/react/PackageList.java`. +1. Finally, at runtime (on startup) the list of React Native packages, generated in step 2, is used to instruct the React Native runtime of what native modules are available. + +See implementation of [native_modules.gradle](https://github.com/react-native-community/cli/blob/master/packages/platform-android/native_modules.gradle). + +## What do I need to have in my package to make it work? + +You’re already using Gradle, so Android support will work by default. + +On the iOS side, you will need to ensure you have a Podspec to the root of your repo. The `react-native-webview` Podspec is a good example of a [`package.json`](https://github.com/react-native-community/react-native-webview/blob/master/react-native-webview.podspec)-driven Podspec. + +## How can I customize how autolinking works for my package? + +A library can add a `react-native.config.js` configuration file, which will customize the defaults. From 982c03235017f044a2d7258590a92615142af3c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 19 Apr 2019 23:12:45 +0200 Subject: [PATCH 3/3] add init docs --- docs/commands.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/commands.md b/docs/commands.md index db51d3547..e34f8a76f 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -4,6 +4,7 @@ React Native CLI comes with following commands: - [`bundle`](#bundle) - [`config`](#config) +- [`init`](#init) - [`info`](#info) - [`install`](#install) - [`library`](#library) @@ -110,6 +111,63 @@ react-native config Output project and dependencies configuration in JSON format to stdout. Used by [autolinking](./autolinking.md). +### `init` + +> Available since 0.60.0 + +Usage: + +```sh +react-native init [options] +``` + +Initialize new React Native project. + +#### Options + +#### `--version [string]` + +Uses a valid semver version of React Native as a template. + +#### `--template [string]` + +Uses a custom template. Accepts either an npm package name or an absolute path to local directory. + +Example: + +```sh +react-native init MyApp --template react-native-custom-template +react-native init MyApp --template file:///Users/name/template-path +``` + +A template is any directory or npm package that contains a `template.config.js` file in the root with following of the following type: + +```ts +type Template = { + // Placeholder used to rename and replace in files + // package.json, index.json, android/, ios/ + placeholderName: string; + // Directory with template + templateDir: string; + // Path to script, which will be executed after init + postInitScript?: string; +}; +``` + +Example `template.config.js`: + +```js +module.exports = { + placeholderName: "ProjectName", + templateDir: "./template", + postInitScript: "./script.js", +}; +``` + +#### `--npm` + +Force use of npm during initialization + ### `info` Usage: