From 6da0a2a82f36d484e2fdd1cb9c1d08c4104320b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 21 May 2019 13:32:06 +0200 Subject: [PATCH 1/2] feat: remove manifest from config output --- docs/configuration.md | 3 +- docs/dependencies.md | 42 +++--- docs/init.md | 8 +- docs/platforms.md | 121 +++++++++--------- docs/plugins.md | 23 ++-- docs/projects.md | 51 ++++---- packages/platform-android/src/config/index.js | 2 +- types/index.js | 14 -- 8 files changed, 127 insertions(+), 137 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 173f4df37..bca5ad350 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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) diff --git a/docs/dependencies.md b/docs/dependencies.md index afdc4f198..c8302df2a 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -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? @@ -34,12 +34,12 @@ 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; + }; }; ``` @@ -47,7 +47,7 @@ type DependencyConfigT = { ### 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. @@ -55,16 +55,16 @@ 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; }; ``` @@ -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. @@ -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. @@ -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 @@ -146,9 +146,9 @@ module.exports = { }, assets: ['./path-to-assets'], hooks: { - prelink: './path-to-a-postlink-hook' - } - } + prelink: './path-to-a-postlink-hook', + }, + }, }; ``` diff --git a/docs/init.md b/docs/init.md index 8bd4e5d3b..b222f2524 100644 --- a/docs/init.md +++ b/docs/init.md @@ -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`. @@ -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 ``` @@ -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', }; ``` diff --git a/docs/platforms.md b/docs/platforms.md index 23f6c2d0b..fa2f66d8e 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -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. @@ -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'); @@ -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. @@ -59,15 +61,16 @@ type PlatformConfig = { 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. @@ -76,29 +79,29 @@ 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, - plist: Array, + sourceDir: string; + folder: string; + pbxprojPath: string; + podfile: null; + podspec: null; + projectPath: string; + projectName: string; + libraryFolder: string; + sharedLibraries: Array; + plist: Array; }; 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; }; ``` @@ -106,17 +109,18 @@ We suggest performing all side-effects inside this function (such as resolving p ### 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: @@ -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. @@ -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 @@ -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" } @@ -191,7 +190,7 @@ to `react-native.config.js` module.exports = { platforms: { windows: require('./local-cli/platform.js').windows, - } + }, }; ``` @@ -199,7 +198,7 @@ module.exports = { ### Changing platform configuration for a [`dependency`](./dependencies.md) -Platform keys are now under `dependency.platforms`. +Platform keys are now under `dependency.platforms`. For example: @@ -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: @@ -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. diff --git a/docs/plugins.md b/docs/plugins.md index b5f0dc1d4..82d988b59 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -15,16 +15,15 @@ module.exports = { commands: [ { name: 'foo-command', - func: () => console.log('It worked') - } - ] + func: () => console.log('It worked'), + }, + ], }; ``` -> Above is an example of a plugin that exports a command named `foo-command` that can be executed with `react-native foo-command` and logs "It worked" and exits. +> Above is an example of a plugin that exports a command named `foo-command` that can be executed with `react-native foo-command` and logs "It worked" and exits. - -At the startup, React Native CLI reads configuration from all dependencies listed in `package.json` and reduces them into a single configuration. +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, an array of commands concatenated from all plugins is passed on to the CLI to be loaded after built-in commands. @@ -56,7 +55,7 @@ type Command = { #### `name` -A name that will be used in order to run the command. +A name that will be used in order to run the command. Note: If you want your command to accept additional arguments, make sure to include them in the name. @@ -110,26 +109,30 @@ A command with arguments and options (if applicable) that can be run in order to ## 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 A `plugin` property should be renamed to `commands`. For example, the following `rnpm` configuration inside `package.json`: + ```json { "rnpm": { - "plugin": "./path-to-commands.js", + "plugin": "./path-to-commands.js" } } ``` + should be moved to a `react-native.config.js`: + ```js module.exports = { - commands: require('./path-to-commands.js') + commands: require('./path-to-commands.js'), }; ``` + provided that `./path-to-commands.js` returns an array of commands. ### Renaming command options diff --git a/docs/projects.md b/docs/projects.md index 1a2a681ff..1d8cb92dc 100644 --- a/docs/projects.md +++ b/docs/projects.md @@ -14,10 +14,10 @@ For example, below configuration informs CLI of the additional assets to link an module.exports = { project: { ios: { - project: './CustomProject.xcodeproj' - } + project: './CustomProject.xcodeproj', + }, }, - assets: ['./assets'] + assets: ['./assets'], }; ``` @@ -59,7 +59,7 @@ React Native from a (custom) source. ### project -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 React Native developer, you should not need to define any of these. @@ -67,23 +67,23 @@ The following settings are available on iOS and Android: ```ts type ProjectParamsAndroidT = { - sourceDir?: string, - manifestPath?: string, - packageName?: string, - packageFolder?: string, - mainFilePath?: string, - stringsPath?: string, - settingsGradlePath?: string, - assetsPath?: string, - buildGradlePath?: string, - packageName?: string, + sourceDir?: string; + manifestPath?: string; + packageName?: string; + packageFolder?: string; + mainFilePath?: string; + stringsPath?: string; + settingsGradlePath?: string; + assetsPath?: string; + buildGradlePath?: string; + packageName?: string; }; type ProjectParamsIOST = { - project?: string, - sharedLibraries?: string[], - libraryFolder?: string, - plist: any[], + project?: string; + sharedLibraries?: string[]; + libraryFolder?: string; + plist: any[]; }; ``` @@ -104,17 +104,19 @@ An array of commands defined inside a project. You can check the format and opti Dependencies is a map where key is the name of the dependency and value is an object that can override any of the resolved settings for a particular package. For example, you could set: + ```js module.exports = { dependencies: { ['react-native-webview']: { platforms: { - ios: null - } - } - } -} + ios: null, + }, + }, + }, +}; ``` + in order to disable linking of React Native WebView on iOS. The object provided here is deep merged with the dependency config. Check [`projectConfig`](platforms.md#projectconfig) and [`dependencyConfig`](platforms.md#dependencyConfig) return values for a full list of properties that you can override. @@ -150,6 +152,3 @@ module.exports = { assets: ['./path-to-assets'], }; ``` - - - diff --git a/packages/platform-android/src/config/index.js b/packages/platform-android/src/config/index.js index e6cbf5155..78ab2f682 100644 --- a/packages/platform-android/src/config/index.js +++ b/packages/platform-android/src/config/index.js @@ -126,5 +126,5 @@ export function dependencyConfig(folder, userConfig = {}) { const packageInstance = userConfig.packageInstance || `new ${packageClassName}()`; - return {sourceDir, folder, manifest, packageImportPath, packageInstance}; + return {sourceDir, folder, packageImportPath, packageInstance}; } diff --git a/types/index.js b/types/index.js index 313d0e5ed..a17e6f305 100644 --- a/types/index.js +++ b/types/index.js @@ -245,20 +245,6 @@ type ProjectConfigAndroidT = { type DependencyConfigAndroidT = { sourceDir: string, folder: string, - manifest: Manifest, packageImportPath: string, packageInstance: string, }; - -type Manifest = { - name: string, - attr: { - [key: string]: string, - package: string, - }, - val: string, - isValCdata: boolean, - children: Array, - firstChild: Manifest, - lastChild: Manifest, -}; From 8b313b4b0075bc0b5c94a702f5a4c843b7987767 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 21 May 2019 13:37:52 +0200 Subject: [PATCH 2/2] fix typo in the docs --- docs/dependencies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dependencies.md b/docs/dependencies.md index c8302df2a..128b20582 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -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" } } } @@ -146,7 +146,7 @@ module.exports = { }, assets: ['./path-to-assets'], hooks: { - prelink: './path-to-a-postlink-hook', + prelink: './path-to-a-prelink-hook', }, }, };