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..f1a7a3246 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -121,7 +121,7 @@ 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). #### Options diff --git a/docs/init.md b/docs/init.md new file mode 100644 index 000000000..bbc4bdff5 --- /dev/null +++ b/docs/init.md @@ -0,0 +1,81 @@ +# 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 init && yarn add react-native && yarn 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', ); }