From aa007a77e61f939733b8b184b5002c4f88bd984b Mon Sep 17 00:00:00 2001 From: Adam Foxman Date: Thu, 31 Mar 2022 10:15:12 -0700 Subject: [PATCH 1/4] Update README files --- incubator/patcher-rnmacos/README.md | 2 +- incubator/rn-changelog-generator/README.md | 2 +- packages/cli/README.md | 75 +++++++- packages/config/README.md | 177 ++++++++++++++---- packages/config/src/kitConfig.ts | 28 --- packages/eslint-plugin/README.md | 3 + .../README.md | 27 ++- 7 files changed, 237 insertions(+), 77 deletions(-) diff --git a/incubator/patcher-rnmacos/README.md b/incubator/patcher-rnmacos/README.md index 0654a1804..d28411060 100644 --- a/incubator/patcher-rnmacos/README.md +++ b/incubator/patcher-rnmacos/README.md @@ -1,4 +1,4 @@ -# patcher-rnmacos +# @rnx-kit/patcher-rnmacos [![Build](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml) [![npm version](https://img.shields.io/npm/v/@rnx-kit/patcher-rnmacos)](https://www.npmjs.com/package/@rnx-kit/patcher-rnmacos) diff --git a/incubator/rn-changelog-generator/README.md b/incubator/rn-changelog-generator/README.md index 592df906d..8eaea29c1 100644 --- a/incubator/rn-changelog-generator/README.md +++ b/incubator/rn-changelog-generator/README.md @@ -1,4 +1,4 @@ -# React Native core changelog generator +# @rnx-kit/rn-changelog-generator [![Build](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml) [![npm version](https://img.shields.io/npm/v/@rnx-kit/rn-changelog-generator)](https://www.npmjs.com/package/@rnx-kit/rn-changelog-generator) diff --git a/packages/cli/README.md b/packages/cli/README.md index 8f92948b5..5ac78716e 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -13,15 +13,53 @@ Command-line interface for working with `kit` packages in your repo. ## Bundle a Kit -Bundle a `kit` package using [Metro](https://facebook.github.io/metro). The +Bundle an application using [Metro](https://facebook.github.io/metro). The bundling process is controlled by -[kit configuration](https://github.com/microsoft/rnx-kit/tree/main/packages/config) +[configuration](https://github.com/microsoft/rnx-kit/tree/main/packages/config) and optional command-line overrides. +### Example Commands + +```bash +$ yarn react-native rnx-bundle + +$ yarn react-native rnx-bundle --platform ios --dev false --minify true + +$ yarn react-native rnx-bundle --bundle-prefix test-app --experimental-tree-shake true ``` -$ yarn react-native rnx-bundle [options] + +### Example Configuration + +```json +{ + "rnx-kit": { + "bundle": { + "entryPath": "src/index.ts", + "distPath": "dist", + "assetsPath": "dist", + "bundlePrefix": "main", + "detectCyclicDependencies": true, + "detectDuplicateDependencies": { + "ignoredModules": ["react-is"] + }, + "typescriptValidation": true, + "experimental_treeShake": true, + "targets": ["ios", "android", "windows", "macos"], + "platforms": { + "android": { + "assetsPath": "dist/reså" + }, + "macos": { + "typescriptValidation": false + } + } + } + } +} ``` +### Command-Line Overrides + | Override | Description | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --id [id] | Target bundle definition. This is only needed when the kit configuration has multiple bundle definitions. | @@ -43,15 +81,40 @@ $ yarn react-native rnx-bundle [options] ## Start a Bundle Server -Start a bundle server for a `kit` package using +Start a bundle server for an application using [Metro](https://facebook.github.io/metro). The server is controlled by -[kit configuration](https://github.com/microsoft/rnx-kit/tree/main/packages/config) +[configuration](https://github.com/microsoft/rnx-kit/tree/main/packages/config) and optional command-line overrides. +### Example Commands + +```bash +$ yarn react-native rnx-start + +$ yarn react-native rnx-start --host localhost --port 8812 ``` -$ yarn react-native rnx-start [options] + +### Example Configuration + +```json +{ + "rnx-kit": { + "server": { + "projectRoot": "src", + "detectCyclicDependencies": true, + "detectDuplicateDependencies": { + "ignoredModules": ["react-is"], + "throwOnError": false + }, + "typescriptValidation": true, + "experimental_treeShake": true + } + } +} ``` +### Command-Line Overrides + | Override | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --host [string] | Host name or address to bind when listening for incoming server requests. When not given, requests from all addresses are accepted. | diff --git a/packages/config/README.md b/packages/config/README.md index 0f8acc8f7..04c8e8721 100644 --- a/packages/config/README.md +++ b/packages/config/README.md @@ -3,39 +3,144 @@ [![Build](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml) [![npm version](https://img.shields.io/npm/v/@rnx-kit/config)](https://www.npmjs.com/package/@rnx-kit/config) -Define and query information about a `kit` package. - -This is designed to be part of the tooling pipeline, so it assumes it is running -in a node environment. - -## `getKitConfig([options]): KitConfig | null` - -Read configuration data for a `kit` package. - -| Option | Description | -| -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `module` | Module name of the `kit` package. The module is located via `require.resolve`, which means it needs to be a visible dependency of some sort. | -| `cwd` | Path to the `kit` package, or a directory within it. | - -The `kit` package is located via `options.module`, `options.cwd`, or the current -working directory (in that order). The location is then used as a starting-point -for a `cosmiconfig` search using the key **"rnx-kit"**. `cosmiconfig` will match -either `rnx-kit.config.js`, an "rnx-kit" section of `package.json`, or any of -the other -[standard ways of supplying configuration](https://github.com/davidtheclark/cosmiconfig#cosmiconfig). - -## Future Work - -This package is a work in progress. Future work may include: - -- Dependency gathering, both deep and direct. Required for platform bundling in - both dynamic metro configs as well as the babel transform. For performance - (and flexibility) the platform bundling step should produce generated output - to track the explicit list included. -- Definitions of how a platform bundle was produced, including where a shipped - version can be found. -- Configuration of how a platform bundle should be consumed -- Platform masking of configurations, likely needed for specialized out of tree - platform handling in metro configs -- Special handling instructions for bundling -- Special handling instructions for testing +Query for a package's configuration. + +Configuration influences how the CLI behaves. If you're not using the CLI, and +instead using a specific tool programmatically, you can use this library to read +configuration data and use it as tool input. + +## Schema + +Package configuration is under the top-level `rnx-kit` entry in package.hson. It +is of type `KitConfig`. + +### `KitConfig` + +| Name | Type | Description | +| --------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| kitType | "app", "library", undefined | Library or App package. Used by the dependency manager when projecting capabilities into `dependencies`, `devDependencies`, and `peerDependencies`. Library package dependencies are private, in dev and peer. App package dependencies are public. | +| reactNativeVersion | string, undefined | React Native version (or range) which this package supports. | +| reactNativeDevVersion | string, undefined | React Native version to use during development of this package. If not specified, the minimum `reactNativeVersion` is used. | +| bundle | `BundleConfig`, undefined | Bundler configuration for a package. If true, then all defaults will be used. If a `BundleDefinition` (or array) is given, the object(s) are a detailed specification of the bundling configurtion. If undefined, this package does not support bundling. | +| server | `ServerConfig`, undefined | Bundle server configuration. If not specified, this package does not support bundle serving. | +| capabilities | `Capability[]`, undefined | List of [capabilities](https://github.com/microsoft/rnx-kit/tree/main/packages/dep-check#capabilities) that this package needs. A capability is a well-known name (string). | +| customProfiles | string, undefined | Path to a file containing [custom profiles](https://github.com/microsoft/rnx-kit/tree/main/packages/dep-check#custom-profiles). | + +### `BundleConfig` + +Union of: boolean, `BundleDefinition`, `BundleDefinition[]` + +### `BundleDefinition` inherits `BundlerRuntimeParameters` + +| Name | Type | Default | Description | +| ----------------------- | ------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| id | string, undefined | | Unique identifier for this bundle definition. Only used as a reference within the build system. | +| targets | `AllPlatforms[]`, undefined | | The platform(s) for which this package may be bundled. | +| platforms | {[K in `AllPlatforms`]: `BundleDefinition`}, undefined | | Platform-specific overrides for bundling parameters. Any parameter not listed in an override gets its value from the shared bundle definition, or falls back to defaults. | +| entryPath | string, undefined | lib/index.js | Path to the .js file which is the entry-point for building the bundle. Either absolute, or relative to the package. | +| distPath | string, undefined | dist | Path where the bundle and source map files are written. Either absolute, or relative to the package. | +| assetsPath | string, undefined | dist | Path where all bundle assets (strings, images, fonts, sounds, ...) are written. Either absolute, or relative to the package. | +| bundlePrefix | string, undefined | index | Prefix for the bundle name, followed by the platform and either ".bundle" (win, android) or ".jsbundle" (mac, ios). | +| bundleEncoding | string, undefined | | [Encoding scheme](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to use when writing the bundle file. Currently limited to UTF-8, UTF-16 (little endian), and 7-bit ASCII. | +| sourceMapPath | string, undefined | | Path to use when creating the bundle source map file. Either absolute, or relative to the package. | +| sourceMapSourceRootPath | string, undefined | | Path to the package's source files. Used to make source-map paths relative and therefore portable. | + +### `AllPlatforms` + +Union of: "ios", "android", "windows", "win32", "macos" + +### `BundlerRuntimeParameters` + +| Name | Type | Default | Description | +| --------------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| detectCyclicDependencies | boolean, `CyclicDetectorOptions`, undefined | true | Choose whether to detect cycles in the dependency graph. If true, then a default set of options will be used. If `CyclicDetectorOptions` is given, the object is a detailed specification of cyclic detector configuration. | +| detectDuplicateDependencies | boolean, `DuplicateDetectorOptions`, undefined | true | Choose whether to detect duplicate packages in the dependency graph. If true, then a default set of options will be used. If `DuplicateDetectorOptions` is given, the object is a detailed specification of the duplicate detector configuration. | +| typescriptValidation | boolean, undefined | true | Choose whether to type-check the application during bundling and serving. | +| experimental_treeShake | boolean, undefined | false | **EXPERIMENTAL** -- Choose whether to enable tree-shaking. | + +### `CyclicDetectorOptions` + +| Name | Type | Default | Description | +| ------------------ | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------- | +| includeNodeModules | boolean, undefined | false | When scanning for circular dependencies, include all external packages from node_modules. | +| linesOfContext | number, undefined | 1 | When a cycle is detected, this controls the size of the module backtrace that is printed with the error message. | +| throwOnError | boolean, undefined | true | Whether or not to throw an exception when a cycle is detected. | + +### `DuplicateDetectorOptions` + +| Name | Type | Default | Description | +| -------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------- | +| ignoredModules | string[], undefined | | List of modules to ignore when scanning for duplicate dependencies. | +| bannedModules | string[], undefined | | List of modules that always cause a failure, regardless of whether or not they are duplicated. | +| throwOnError | boolean, undefined | true | Whether or not to throw an exception when a duplicate or banned module is detected. | + +### `ServerConfig` inherits `BundlerRuntimeParameters` + +| Name | Type | Default | Description | +| ------------ | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| projectRoot | string, undefined | | Path to the root of your react-native application. The bundle server uses this root path to resolve all web requests. The root path should contain your Babel config, otherwise Metro won't be able to find it. Either absolute, or relative to the package. | +| assetPlugins | string[], undefined | | Additional asset plugins to be used by the Metro Babel transformer. Comma-separated list containing plugin modules and/or absolute paths to plugin packages. | +| sourceExts | string[], undefined | | Additional source-file extensions to include when generating bundles. Comma-separated list, excluding the leading dot. | + +## API + +### `getKitConfig({module, cwd})` + +Query for a package's configuration. + +| Parameter | Type | Description | +| --------- | ----------------- | ----------------------------------------------------------------------------------------------- | +| module | string, undefined | Read package configuration from the named module. When given, this takes precedence over `cwd`. | +| cwd | string, undefined | Read package configuration from the given directory. Ignored when `module` is given. | +| [Return] | `KitConfig`, null | Package configuration, or `null` if nothing was found. | + +### `getBundleDefinition(config, id)` + +Get a "complete" bundle definition from the package configuration. + +If `id` is given, search for the matching bundle and return it. Otherwise, +return the first bundle definition found. + +| Parameter | Type | Description | +| --------- | ------------------ | ------------------------------------------------------------------------------------------------------- | +| config | `BundleConfig` | The bundle configuration, typically retrieved from the package configuration field `rnx-kit.bundle`. | +| id | string, undefined | The id of the target bundle definition to use. This is not needed if only one bundle definition exists. | +| [Return] | `BundleDefinition` | A "complete" bundle definition, with defaults applied for any missing values that have them. | + +### `getBundlePlatformDefinition(bundle, platform)` + +Get a platform bundle definition, applying any platform-specific overrides. + +| Parameter | Type | Description | +| --------- | ------------------ | ------------------------------------------------------------------------- | +| bundle | `BundleDefinition` | A "complete" bundle definition, typically from `getBundleDefinition()`. | +| platform | `AllPlatforms` | The platform to resolve. | +| [Return] | `BundleDefinition` | The input bundle definition with all platform-specific overrides applied. | + +### `getKitCapabilities(config)` + +Get capability information from the package configuration. + +| Parameter | Type | Description | +| --------- | ----------------- | ----------------------- | +| config | `KitConfig` | Package configuration. | +| [Return] | `KitCapabilities` | Capability information. | + +#### `KitCapabilities` + +| Name | Type | Default | Description | +| --------------------- | --------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| kitType | "app", "library", undefined | "library" | Library or App package. Used by the dependency manager when projecting capabilities into `dependencies`, `devDependencies`, and `peerDependencies`. Library package dependencies are private, in dev and peer. App package dependencies are public. | +| reactNativeVersion | string | | React Native version (or range) which this package supports. | +| reactNativeDevVersion | string | Min version in reactNativeVersion | React Native version to use during development of this package. If not specified, the minimum `reactNativeVersion` is used. | +| capabilities | `Capability[]` | `[]` | List of [capabilities](https://github.com/microsoft/rnx-kit/tree/main/packages/dep-check#capabilities) that this package needs. A capability is a well-known name (string). | +| customProfiles | string, undefined | | Path to a file containing [custom profiles](https://github.com/microsoft/rnx-kit/tree/main/packages/dep-check#custom-profiles). | + +### `getServerConfig(config)` + +Get a "complete" server configuration from the package configuration. + +| Parameter | Type | Description | +| --------- | -------------- | ----------------------------------------------------------------------------------------------- | +| config | `KitConfig` | The package configuration, typically retrieved from with `getKitConfig()`. | +| [Return] | `ServerConfig` | A "complete" server configuration, with defaults applied for any missing values that have them. | diff --git a/packages/config/src/kitConfig.ts b/packages/config/src/kitConfig.ts index ce6f12ccf..684247df8 100644 --- a/packages/config/src/kitConfig.ts +++ b/packages/config/src/kitConfig.ts @@ -78,26 +78,6 @@ export type KitConfig = { */ reactNativeDevVersion?: string; - /** - * Whether this kit produces a platform bundle. If true then all defaults will be used. Otherwise the object allows more detailed - * specification of platform bundle functionality. - */ - platformBundle?: - | boolean - | { - /** - * relative path for location within the package to find the built platform bundles. Defaults to './dist' - * @default "dist" - */ - distPath?: string; - - /** - * prefix for the bundle name. Defaults to 'index' - * @default "index" - */ - bundlePrefix?: string; - }; - /** * Specifies how the kit is bundled. When not defined, the kit cannot be bundled. */ @@ -109,14 +89,6 @@ export type KitConfig = { */ server?: ServerConfig; - /** - * Retrieve the dependencies for the kit, either via: - * - string: A file target to open via require - * - DependencyVersions: An explicit list of versions to treat as part of the kit - * - GetDependencyVerions: A function which will retrieve the dependency versions on demand - */ - dependencies?: string | DependencyVersions | GetDependencyVersions; - /** * Capabilities used by the kit. * @default [] diff --git a/packages/eslint-plugin/README.md b/packages/eslint-plugin/README.md index 3dfadb3c4..3f20107ae 100644 --- a/packages/eslint-plugin/README.md +++ b/packages/eslint-plugin/README.md @@ -1,5 +1,8 @@ # @rnx-kit/eslint-plugin +[![Build](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml) +[![npm version](https://img.shields.io/npm/v/@rnx-kit/eslint-plugin)](https://www.npmjs.com/package/@rnx-kit/eslint-plugin) + `@rnx-kit/eslint-plugin` is a set of rules that can be extended in your own shareable ESLint config. diff --git a/packages/typescript-react-native-compiler/README.md b/packages/typescript-react-native-compiler/README.md index c4151d30b..aadf5b0e9 100644 --- a/packages/typescript-react-native-compiler/README.md +++ b/packages/typescript-react-native-compiler/README.md @@ -3,11 +3,28 @@ [![Build](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml/badge.svg)](https://github.com/microsoft/rnx-kit/actions/workflows/build.yml) [![npm version](https://img.shields.io/npm/v/@rnx-kit/typescript-react-native-compiler)](https://www.npmjs.com/package/@rnx-kit/typescript-react-native-compiler) -`@rnx-kit/typescript-react-native-compiler` is a TypeScript compiler with a -custom module resolver for react-native projects. +`@rnx-kit/typescript-react-native-compiler` is the TypeScript compiler `tsc` +with a custom module resolver for react-native projects. -This package extends TypeScript, adding the concept of a platform. When -resolving modules, it uses the platform to find platform-override files such as -`foo.ios.ts` and `foo.native.ts`. It also uses the platform to map +This package extends TypeScript, adding the concept of a platform to `tsc`. When +resolving modules, the platform is used to find platform-extension files such as +`foo.ios.ts` and `foo.native.ts`. The platform is also used to map `react-native` module references to out-of-tree platforms such as `react-native-windows` and `react-native-macos`. + +This package exports a new command-line tool: `rn-tsc`. It is a drop-in +replacement for `tsc` with a few additional command-line parameters. + +## Example Commands + +```bash +$ yarn run rn-tsc --platform ios --platformExtensions mobile,native + +$ yarn run rn-tsc --platform macos --platformExtensions native --disableReactNativePackageSubstitution + +// Run a normal build without using the custom module resolver +$ yarn run rn-tsc + +// Get a full listing of all command-line parameters +$ yarn run rn-tsc --help +``` From cacce059a783751a726b041dd8624afe3c44dee6 Mon Sep 17 00:00:00 2001 From: Adam Foxman Date: Thu, 31 Mar 2022 10:20:57 -0700 Subject: [PATCH 2/4] docs(changeset): Update READMEs. Remove dead configuration types. --- .changeset/large-geese-share.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .changeset/large-geese-share.md diff --git a/.changeset/large-geese-share.md b/.changeset/large-geese-share.md new file mode 100644 index 000000000..99e456ffd --- /dev/null +++ b/.changeset/large-geese-share.md @@ -0,0 +1,10 @@ +--- +"@rnx-kit/patcher-rnmacos": patch +"@rnx-kit/rn-changelog-generator": patch +"@rnx-kit/cli": patch +"@rnx-kit/config": patch +"@rnx-kit/eslint-plugin": patch +"@rnx-kit/typescript-react-native-compiler": patch +--- + +Update READMEs. Remove dead configuration types. From 4d2722948d6a00974490f80b4d7b329660cfe259 Mon Sep 17 00:00:00 2001 From: Adam Foxman Date: Thu, 31 Mar 2022 10:40:31 -0700 Subject: [PATCH 3/4] Update .changeset/large-geese-share.md Co-authored-by: Tommy Nguyen <4123478+tido64@users.noreply.github.com> --- .changeset/large-geese-share.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.changeset/large-geese-share.md b/.changeset/large-geese-share.md index 99e456ffd..9848b7f81 100644 --- a/.changeset/large-geese-share.md +++ b/.changeset/large-geese-share.md @@ -1,10 +1,5 @@ --- -"@rnx-kit/patcher-rnmacos": patch -"@rnx-kit/rn-changelog-generator": patch -"@rnx-kit/cli": patch "@rnx-kit/config": patch -"@rnx-kit/eslint-plugin": patch -"@rnx-kit/typescript-react-native-compiler": patch --- Update READMEs. Remove dead configuration types. From 27d030f984d6c461c046b0d7dc42e5b271faee10 Mon Sep 17 00:00:00 2001 From: Adam Foxman Date: Thu, 31 Mar 2022 10:46:21 -0700 Subject: [PATCH 4/4] Fix READMEs --- packages/cli/README.md | 16 ++++++++++----- .../README.md | 20 +++++++++++++------ 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index 5ac78716e..915d24d4c 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -21,11 +21,15 @@ and optional command-line overrides. ### Example Commands ```bash -$ yarn react-native rnx-bundle +yarn react-native rnx-bundle +``` -$ yarn react-native rnx-bundle --platform ios --dev false --minify true +```bash +yarn react-native rnx-bundle --platform ios --dev false --minify true +``` -$ yarn react-native rnx-bundle --bundle-prefix test-app --experimental-tree-shake true +```bash +yarn react-native rnx-bundle --bundle-prefix test-app --experimental-tree-shake true ``` ### Example Configuration @@ -89,9 +93,11 @@ and optional command-line overrides. ### Example Commands ```bash -$ yarn react-native rnx-start +yarn react-native rnx-start +``` -$ yarn react-native rnx-start --host localhost --port 8812 +```bash +yarn react-native rnx-start --host localhost --port 8812 ``` ### Example Configuration diff --git a/packages/typescript-react-native-compiler/README.md b/packages/typescript-react-native-compiler/README.md index aadf5b0e9..9eadb5188 100644 --- a/packages/typescript-react-native-compiler/README.md +++ b/packages/typescript-react-native-compiler/README.md @@ -18,13 +18,21 @@ replacement for `tsc` with a few additional command-line parameters. ## Example Commands ```bash -$ yarn run rn-tsc --platform ios --platformExtensions mobile,native +yarn run rn-tsc --platform ios --platformExtensions mobile,native +``` + +```bash +yarn run rn-tsc --platform macos --platformExtensions native --disableReactNativePackageSubstitution +``` -$ yarn run rn-tsc --platform macos --platformExtensions native --disableReactNativePackageSubstitution +Run a normal build without using the custom module resolver: -// Run a normal build without using the custom module resolver -$ yarn run rn-tsc +```bash +yarn run rn-tsc +``` -// Get a full listing of all command-line parameters -$ yarn run rn-tsc --help +Get a full listing of all command-line parameters: + +```bash +yarn run rn-tsc --help ```