From 5c9d785e4ad29da0bb5bdb5ac3457c2e95b4ad66 Mon Sep 17 00:00:00 2001 From: Kacper Wiszczuk Date: Tue, 23 Apr 2019 18:35:30 +0200 Subject: [PATCH 1/4] docs: add init documentation --- docs/init.md | 80 ++++++++++++++++++++++++++ packages/cli/src/commands/init/init.js | 2 +- 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 docs/init.md diff --git a/docs/init.md b/docs/init.md new file mode 100644 index 000000000..a48f7ef4b --- /dev/null +++ b/docs/init.md @@ -0,0 +1,80 @@ +# Initializing new project + +There are couple of ways to initialize new React Native projects. + +### For `react-native@0.60.0` or greater + +Using `npx` utility: + +```sh +npx react-native init ProjectName +``` + +> Note: If you have both `yarn` and `npm` installed on your machine, React Native CLI will always try to use `yarn`, so even if you use `npx` utility, only `react-native` executable will be installed using `npm` and the rest of the work will be delegated to `yarn`. You can force usage of `npm` adding `--npm` flag to the command. + +> Note: for Yarn users, `yarn dlx` command similar to `npx` will be featured in Yarn 2.0: https://github.com/yarnpkg/berry/pull/40 so we’ll be able to use it in a similar fashion. + +Installing `react-native` and invoking `init` command: + +```sh +yarn add react-native && react-native init ProjectName +``` + +Initializing project with custom version of `react-native`: + +```sh +# This will use the latest init command but will install react-native@VERSION and use its template +npx react-native init ProjectName --version ${VERSION} + +# This will use init command from react-native@VERSION +npx react-native@${VERSION} init ProjectName +``` + +Initializing project with custom template. In following examples `TEMPLATE_NAME` can be either: + +- Full package name, eg. `react-native-template-typescript`. +- Shorthand name of template, eg. `typescript`. +- Absolute path to directory containing template, eg. `file:///Users/username/project/some-template`. + +```sh +# This will initialize new project using template from TEMPLATE_NAME package +npx react-native init ProjectName --template ${TEMPLATE_NAME} + +# This will initialize new project using init command from react-native@VERSION but will use TEMPLATE_NAME custom template +npx react-native@${VERSION} init ProjectName --template ${TEMPLATE_NAME} +``` + +You can force usage of `npm` if you have both `yarn` and `npm` installed on your machine: +```sh +npx react-native init ProjectName --npm +``` + +### For older `react-native` versions + +Using legacy `react-native-cli` package: + +```sh +yarn global add react-native-cli +react-native init ProjectName +``` + +> Note: It is not recommended, but you can also use legacy `react-native-cli` package to initialize projects using latest `react-native` versions. + +# Creating custom template + +Every custom template needs to have configuration file called `template.config.js` in the root of the project: + +```js +module.exports = { + // Placeholder name that will be replaced in package.json, index.json, android/, ios/ for a project name. + placeholderName: "ProjectName", + + // Directory with the template which will be copied and processed by React Native CLI. Template directory should have package.json with all dependencies specified, including `react-native`. + templateDir: "./template", + + // Path to script, which will be executed after initialization process, but before installing all the dependencies specified in the template. + postInitScript: "./script.js", +}; +``` + +You can find example custom template [here](https://github.com/Esemesek/react-native-new-template). diff --git a/packages/cli/src/commands/init/init.js b/packages/cli/src/commands/init/init.js index 26a5cfed5..19639c58f 100644 --- a/packages/cli/src/commands/init/init.js +++ b/packages/cli/src/commands/init/init.js @@ -106,7 +106,7 @@ async function createFromReactNativeTemplate( try { if (semver.valid(version) && !semver.gte(version, '0.60.0')) { throw new Error( - 'Cannot use React Native CLI to initialize project with version less than 0.60.0', + 'Cannot use React Native CLI to initialize project with version lower than 0.60.0', ); } From 1c78e9a64f16ad91484129c4e0e3a4224bb7326f Mon Sep 17 00:00:00 2001 From: Kacper Wiszczuk Date: Tue, 23 Apr 2019 18:49:04 +0200 Subject: [PATCH 2/4] docs: add mentions in other files --- README.md | 5 ++++- docs/commands.md | 41 +---------------------------------------- docs/init.md | 9 +++++---- 3 files changed, 10 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index e8b403f32..47ea151eb 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ This CLI is intended to be used with a certain version of React Native. You'll f ## Documentation - [commands](./docs/commands.md) +- [init](./docs/init.md) - [autolinking](./docs/autolinking.md) - [plugins](./docs/plugins.md) @@ -48,7 +49,9 @@ npx react-native init MyApp 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. +> We strongly encourage you to **only use global `react-native-cli` for bootstrapping new projects**. Use local version for everything else. + +You can find out more about init command from the [documentation](./docs/init.md) ## Usage in an existing React Native project diff --git a/docs/commands.md b/docs/commands.md index e34f8a76f..0e4b54c9b 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -123,46 +123,7 @@ 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", -}; -``` +You can find out more use cases in [init docs](./init.md). #### `--npm` diff --git a/docs/init.md b/docs/init.md index a48f7ef4b..ade641ee5 100644 --- a/docs/init.md +++ b/docs/init.md @@ -4,7 +4,7 @@ There are couple of ways to initialize new React Native projects. ### For `react-native@0.60.0` or greater -Using `npx` utility: +#### Using `npx` utility: ```sh npx react-native init ProjectName @@ -14,13 +14,13 @@ npx react-native init ProjectName > Note: for Yarn users, `yarn dlx` command similar to `npx` will be featured in Yarn 2.0: https://github.com/yarnpkg/berry/pull/40 so we’ll be able to use it in a similar fashion. -Installing `react-native` and invoking `init` command: +#### Installing `react-native` and invoking `init` command: ```sh yarn add react-native && react-native init ProjectName ``` -Initializing project with custom version of `react-native`: +#### Initializing project with custom version of `react-native`: ```sh # This will use the latest init command but will install react-native@VERSION and use its template @@ -30,8 +30,9 @@ npx react-native init ProjectName --version ${VERSION} npx react-native@${VERSION} init ProjectName ``` -Initializing project with custom template. In following examples `TEMPLATE_NAME` can be either: +#### Initializing project with custom template. +In following examples `TEMPLATE_NAME` can be either: - Full package name, eg. `react-native-template-typescript`. - Shorthand name of template, eg. `typescript`. - Absolute path to directory containing template, eg. `file:///Users/username/project/some-template`. From eb07e5ca1d5a9f86d5733199cb22050e7a3a93f5 Mon Sep 17 00:00:00 2001 From: Kacper Wiszczuk Date: Tue, 23 Apr 2019 18:58:43 +0200 Subject: [PATCH 3/4] docs: revert --- docs/commands.md | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 0e4b54c9b..f1a7a3246 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -121,9 +121,48 @@ Usage: react-native init [options] ``` -Initialize new React Native project. +Initialize new React Native project. You can find out more use cases in [init docs](./init.md). -You can find out more use cases in [init docs](./init.md). +#### 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` From 914b454a4ed12dd9f45bdb4b2b1e2eab359a8723 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 23 Apr 2019 19:10:37 +0200 Subject: [PATCH 4/4] Update docs/init.md Co-Authored-By: Esemesek --- docs/init.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/init.md b/docs/init.md index ade641ee5..bbc4bdff5 100644 --- a/docs/init.md +++ b/docs/init.md @@ -17,7 +17,7 @@ npx react-native init ProjectName #### Installing `react-native` and invoking `init` command: ```sh -yarn add react-native && react-native init ProjectName +yarn init && yarn add react-native && yarn react-native init ProjectName ``` #### Initializing project with custom version of `react-native`: