Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@ React Native CLI has a configuration mechanism that allows changing its behavior

> Note: Configuring CLI used to be possible via `rn-cli.config.js` (that has been renamed to `metro.config.js`) and never documented `rnpm` entry on the `package.json`. We have provided migration guides where possible.

React Native CLI can be configured by creating a `react-native.config.js` at the root of the project. Depending on the type of a package, the set of valid properties is different.
React Native CLI can be configured by creating a `react-native.config.js` at the root of the project. Depending on the type of a package, the set of valid properties is different.

Check the documentation for

- [projects](./projects.md)
- [dependencies](./dependencies.md)
- [platforms](./platforms.md)
Expand Down
44 changes: 22 additions & 22 deletions docs/dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ A dependency is a JavaScript package that is listed under dependencies present i

For example, `lodash` is a dependency that doesn't have any native code to link. On the other hand, `react-native-vector-icons` is a dependency that contains not only native code, but also font assets that the CLI should link.

By default, CLI analyses the folder structure inside the dependency and looks for assets and native files to link. This simple heuristic works in most of the cases.
By default, CLI analyses the folder structure inside the dependency and looks for assets and native files to link. This simple heuristic works in most of the cases.

At the same time, a dependency can explicitly set its configuration in case CLI cannot infer it properly. A dependency can also define additional settings, such as a script to run after linking, in order to support some advanced use-cases.
At the same time, a dependency can explicitly set its configuration in case CLI cannot infer it properly. A dependency can also define additional settings, such as a script to run after linking, in order to support some advanced use-cases.

## How does it work?

Expand Down Expand Up @@ -34,37 +34,37 @@ The following type describes the configuration of a dependency that can be set u
```ts
type DependencyConfigT = {
platforms: {
[key: string]: any,
},
assets: string[],
[key: string]: any;
};
assets: string[];
hooks: {
[key: string]: string,
}
[key: string]: string;
};
};
```

> Note: This interface is subject to breaking changes. We may consider renaming some keys to simplify the configuration further. If you are going to use it, be prepared to update before we ship a stable 0.60.0 release.

### platforms

A map of specific settings that can be set per platform. The exact shape is always defined by the package that provides given platform.
A map of specific settings that can be set per platform. The exact shape is always defined by the package that provides given platform.

In most cases, as a library author, you should not need to define any of these.

The following settings are available on iOS and Android:

```ts
type DependencyParamsIOST = {
project?: string,
podspec?: string,
sharedLibraries?: string[],
project?: string;
podspec?: string;
sharedLibraries?: string[];
};

type DependencyParamsAndroidT = {
sourceDir?: string,
manifestPath?: string,
packageImportPath?: string,
packageInstance?: string
sourceDir?: string;
manifestPath?: string;
packageImportPath?: string;
packageInstance?: string;
};
```

Expand Down Expand Up @@ -94,7 +94,7 @@ Custom package import. For example: `import com.acme.AwesomePackage;`.

#### platforms.android.packageInstance

Custom syntax to instantiate a package. By default, it's a `new AwesomePackage()`. It can be useful when your package requires additional arguments while initializing.
Custom syntax to instantiate a package. By default, it's a `new AwesomePackage()`. It can be useful when your package requires additional arguments while initializing.

For settings applicable on other platforms, please consult their respective documentation.

Expand All @@ -104,7 +104,7 @@ An array of assets folders to glob for files to link.

### hooks

A map where key is the name of a hook and value is the path to a file to execute.
A map where key is the name of a hook and value is the path to a file to execute.

For example, `link` command supports `prelink` and `postlink` hooks to run before and after linking is done.

Expand All @@ -116,7 +116,7 @@ These are the only ones supported by CLI at the moment. Depending on the package

The changes are mostly cosmetic so the migration should be pretty straight-forward.

> Note: We read `rnpm` configuration to remain backwards-compatible. Dependency maintainers should update their configuration in the nearest future.
> Note: We read `rnpm` configuration to remain backwards-compatible. Dependency maintainers should update their configuration in the nearest future.

### Changing the configuration

Expand All @@ -129,7 +129,7 @@ Properties were renamed. Look at the following example for the differences.
"android": {},
"assets": ["./path-to-assets"],
"hooks": {
"prelink": "./path-to-a-postlink-hook"
"prelink": "./path-to-a-prelink-hook"
}
}
}
Expand All @@ -146,9 +146,9 @@ module.exports = {
},
assets: ['./path-to-assets'],
hooks: {
prelink: './path-to-a-postlink-hook'
}
}
prelink: './path-to-a-prelink-hook',
},
},
};
```

Expand Down
8 changes: 5 additions & 3 deletions docs/init.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ 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`.
Expand All @@ -47,6 +48,7 @@ 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
```
Expand All @@ -69,13 +71,13 @@ Every custom template needs to have configuration file called `template.config.j
```js
module.exports = {
// Placeholder name that will be replaced in package.json, index.json, android/, ios/ for a project name.
placeholderName: "ProjectName",
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",
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",
postInitScript: './script.js',
};
```

Expand Down
121 changes: 60 additions & 61 deletions docs/platforms.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Platforms

A platform is a React Native package that enables writing and shipping React Native applications to a new target.
A platform is a React Native package that enables writing and shipping React Native applications to a new target.

For example, React Native Windows is a platform, because it allows to run React Native apps on Windows. At the same time, React Native itself is also a platform - it allows to run React Native apps on Android, iOS and tvOS.

Expand All @@ -9,6 +9,7 @@ Each platform can have an additional configuration for the CLI to enable bundlin
## How does it work?

A platform can define the following `react-native.config.js` at the root:

```js
const ios = require('@react-native-community/cli-platform-ios');
const android = require('@react-native-community/cli-platform-android');
Expand All @@ -18,19 +19,20 @@ module.exports = {
ios: {
linkConfig: ios.linkConfig,
projectConfig: ios.projectConfig,
dependencyConfig: ios.dependencyConfig
dependencyConfig: ios.dependencyConfig,
},
android: {
linkConfig: android.linkConfig,
projectConfig: android.projectConfig,
dependencyConfig: android.dependencyConfig
}
}
}
dependencyConfig: android.dependencyConfig,
},
},
};
```
> The above config adds support for linking Android and iOS dependencies by the CLI as well as bundling code for these platforms. This config can be found in [React Native repository](https://github.com/facebook/react-native/blob/0.60-stable/react-native.config.js) from 0.60 version on.

At the startup, React Native CLI reads configuration from all dependencies listed in `package.json` and reduces them into a single configuration.
> The above config adds support for linking Android and iOS dependencies by the CLI as well as bundling code for these platforms. This config can be found in [React Native repository](https://github.com/facebook/react-native/blob/0.60-stable/react-native.config.js) from 0.60 version on.

At the startup, React Native CLI reads configuration from all dependencies listed in `package.json` and reduces them into a single configuration.

At the end, a map of available platforms is passed to the bundler (Metro) to make it aware of the platforms available. This allows APIs such as `Platform.select` and requiring files with platform extensions to work properly.

Expand Down Expand Up @@ -59,15 +61,16 @@ type PlatformConfig<ProjectParams, ProjectConfig, DependencyConfig> = {

Returns a project configuration for a given platform or `null`, when no project found. This is later used inside `linkConfig` to perform linking and unlinking.

First argument is a root folder where the project is located.
First argument is a root folder where the project is located.

Second argument is everything that users defined under:

```js
module.exports = {
project: {
[yourPlatformKey]: {}
}
}
[yourPlatformKey]: {},
},
};
```

> Note: You may find this useful in order to alter the default behavior of your function. For example, on iOS, we find an `.xcodeproj` by globbing the project files and taking the first match. There's a possibility we pick the wrong one in case the project has multiple `.xcodeproj` files. In order to support this use-case, we have allowed users to define an exact path to an iOS project in order to overwrite our `glob` mechanism.
Expand All @@ -76,47 +79,48 @@ On Android and iOS, this function returns:

```ts
type ProjectConfigIOST = {
sourceDir: string,
folder: string,
pbxprojPath: string,
podfile: null,
podspec: null,
projectPath: string,
projectName: string,
libraryFolder: string,
sharedLibraries: Array<any>,
plist: Array<any>,
sourceDir: string;
folder: string;
pbxprojPath: string;
podfile: null;
podspec: null;
projectPath: string;
projectName: string;
libraryFolder: string;
sharedLibraries: Array<any>;
plist: Array<any>;
};

type ProjectConfigAndroidT = {
sourceDir: string,
isFlat: boolean,
folder: string,
stringsPath: string,
manifestPath: string,
buildGradlePath: string,
settingsGradlePath: string,
assetsPath: string,
mainFilePath: string,
packageName: string,
sourceDir: string;
isFlat: boolean;
folder: string;
stringsPath: string;
manifestPath: string;
buildGradlePath: string;
settingsGradlePath: string;
assetsPath: string;
mainFilePath: string;
packageName: string;
};
```

We suggest performing all side-effects inside this function (such as resolving paths to native files) and making `linkConfig` functions pure, operating on provided data.

### dependencyConfig

Similar to [`projectConfig`](#projectconfig) above, but for a dependency of a project.
Similar to [`projectConfig`](#projectconfig) above, but for a dependency of a project.

First argument is a path to a root folder of a dependency.

Second argument is everything that dependency authors defined under:

```js
module.exports = {
dependency: {
[yourPlatformKey]: {}
}
}
[yourPlatformKey]: {},
},
};
```

On Android and iOS, this function returns:
Expand All @@ -125,17 +129,16 @@ On Android and iOS, this function returns:
type DependencyConfigIOST = ProjectConfigIOST;

type DependencyConfigAndroidT = {
sourceDir: string,
folder: string,
manifest: Manifest,
packageImportPath: string,
packageInstance: string,
sourceDir: string;
folder: string;
packageImportPath: string;
packageInstance: string;
};
```

### linkConfig

Returns an object with utilities that are run by the CLI while linking.
Returns an object with utilities that are run by the CLI while linking.

> Note: The following is deprecated and will stop working in the future. Consider providing a [`autolinking`](./autolinking.md) support.

Expand All @@ -161,7 +164,7 @@ Performs platform-specific steps in order to unlink assets of a library from a p

## Migrating from `rnpm` configuration

The changes are mostly cosmetic so the migration should be pretty straight-forward.
The changes are mostly cosmetic so the migration should be pretty straight-forward.

### Changing the configuration for a platform

Expand All @@ -173,12 +176,8 @@ For example:
{
"rnpm": {
"haste": {
"platforms": [
"windows"
],
"providesModuleNodeModules": [
"react-native-windows"
]
"platforms": ["windows"],
"providesModuleNodeModules": ["react-native-windows"]
},
"platform": "./local-cli/platform.js"
}
Expand All @@ -191,15 +190,15 @@ to `react-native.config.js`
module.exports = {
platforms: {
windows: require('./local-cli/platform.js').windows,
}
},
};
```

> The above configuration is taken from `react-native-windows` and adds support for `windows` platform.

### Changing platform configuration for a [`dependency`](./dependencies.md)

Platform keys are now under `dependency.platforms`.
Platform keys are now under `dependency.platforms`.

For example:

Expand All @@ -220,18 +219,18 @@ module.exports = {
dependency: {
platforms: {
ios: {
project: 'PathToCustomProject.xcodeproj'
}
}
}
}
project: 'PathToCustomProject.xcodeproj',
},
},
},
};
```

> The above is a configuration of a dependency that explicitly sets a path to `.xcodeproj`.

### Changing platform configuration for a [`project`](./projects.md)

Platform keys are now under `project.platforms`.
Platform keys are now under `project.platforms`.

For example:

Expand All @@ -251,10 +250,10 @@ to `react-native.config.js`
module.exports = {
project: {
ios: {
project: 'PathToCustomProject.xcodeproj'
}
}
}
project: 'PathToCustomProject.xcodeproj',
},
},
};
```

> The above is a configuration of a project that explicitly sets its main `.xcodeproj` project.
Loading