From b7188adc57053b3b5d79811ee8b0db448c8dad0a Mon Sep 17 00:00:00 2001 From: Josh GM Walker <56300765+Josh-Walker-GM@users.noreply.github.com> Date: Wed, 20 Sep 2023 22:24:25 +0100 Subject: [PATCH 1/2] initial doc entry --- docs/docs/cli-commands.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/docs/cli-commands.md b/docs/docs/cli-commands.md index c6fa2b18688c..a531b31b05cc 100644 --- a/docs/docs/cli-commands.md +++ b/docs/docs/cli-commands.md @@ -1722,6 +1722,7 @@ yarn redwood setup | `deploy` | Set up a deployment configuration for a provider | | `generator` | Copy default Redwood generator templates locally for customization | | `i18n` | Set up i18n | +| `package` | Peform setup actions by running a third party npm package | | `tsconfig` | Add relevant tsconfig so you can start using TypeScript | | `ui` | Set up a UI design or style library | | `webpack` | Set up a webpack config file in your project so you can add custom config | @@ -1903,6 +1904,38 @@ In order to use [Netlify Dev](https://www.netlify.com/products/dev/) you need to > Note: To detect the RedwoodJS framework, please use netlify-cli v3.34.0 or greater. +### setup package + +This command takes a published npm package that you specify, performs some compatibility checks, and then executes it's bin script. This allows you to use third-party packages that can provide you with an easy-to-use setup command for the particular functionality they provide. + +This command behaves similarly to `yarn dlx` but will attempt to confirm compatibility between the package you are attempting to run and the current version of Redwood you are running. You can bypass this check by passing the `--force` flag if you feel you understand any potential compatibility issues. + +``` +yarn redwood setup package +``` + +| Arguments & Options | Description | +| :------------------ | :----------------------- | +| `--force, -f` | Overwrite existing files | + +**Usage** + +Run the made up `@bluewoodjs/rw-setup` package: +```bash +~/redwood-app$ yarn rw setup package @bluewoodjs/rw-setup +``` + +Run the same package but using a particular npm tag and avoiding any compatibility checks: +```bash +~/redwood-app$ yarn rw setup package @bluewoodjs/rw-setup@beta --force +``` + +**Compatibility Checks** + +We perform a simple compatibility check in an attempt to make you aware of potential compatibility issues with setup packages you might wish to run. This works by examining the version of `@redwoodjs/core` you are using within your root `package.json`. We compare this value with a compatibility range the npm package specifies in the `engines.redwoodjs` field of its own `package.json`. If the version of `@redwoodjs/core` you are using falls outside of the compatibility range specified by the package you are attempting to run, we will warn you and ask you to confirm you wish to continue. + +It's the responsibility of the authors of those npm packages to specify the correct range of compatibility so you should always research the packages you use with this command. Especially since they will be executing code on your machine! + ### setup tsconfig Add a `tsconfig.json` to both the web and api sides so you can start using [TypeScript](typescript/index). From d230d9ee4be33f307583305d9814353880c818b9 Mon Sep 17 00:00:00 2001 From: Dominic Saadi Date: Wed, 20 Sep 2023 16:33:11 -0700 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/docs/cli-commands.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/docs/cli-commands.md b/docs/docs/cli-commands.md index a531b31b05cc..d5812429b664 100644 --- a/docs/docs/cli-commands.md +++ b/docs/docs/cli-commands.md @@ -1722,7 +1722,7 @@ yarn redwood setup | `deploy` | Set up a deployment configuration for a provider | | `generator` | Copy default Redwood generator templates locally for customization | | `i18n` | Set up i18n | -| `package` | Peform setup actions by running a third party npm package | +| `package` | Peform setup actions by running a third-party npm package | | `tsconfig` | Add relevant tsconfig so you can start using TypeScript | | `ui` | Set up a UI design or style library | | `webpack` | Set up a webpack config file in your project so you can add custom config | @@ -1916,25 +1916,25 @@ yarn redwood setup package | Arguments & Options | Description | | :------------------ | :----------------------- | -| `--force, -f` | Overwrite existing files | +| `--force, -f` | Forgo compatibility checks | **Usage** -Run the made up `@bluewoodjs/rw-setup` package: +Run the made up `@redwoodjs/setup-example` package: ```bash -~/redwood-app$ yarn rw setup package @bluewoodjs/rw-setup +~/redwood-app$ yarn rw setup package @redwoodjs/setup-example ``` Run the same package but using a particular npm tag and avoiding any compatibility checks: ```bash -~/redwood-app$ yarn rw setup package @bluewoodjs/rw-setup@beta --force +~/redwood-app$ yarn rw setup package @redwoodjs/setup-example@beta --force ``` **Compatibility Checks** -We perform a simple compatibility check in an attempt to make you aware of potential compatibility issues with setup packages you might wish to run. This works by examining the version of `@redwoodjs/core` you are using within your root `package.json`. We compare this value with a compatibility range the npm package specifies in the `engines.redwoodjs` field of its own `package.json`. If the version of `@redwoodjs/core` you are using falls outside of the compatibility range specified by the package you are attempting to run, we will warn you and ask you to confirm you wish to continue. +We perform a simple compatibility check in an attempt to make you aware of potential compatibility issues with setup packages you might wish to run. This works by examining the version of `@redwoodjs/core` you are using within your root `package.json`. We compare this value with a compatibility range the npm package specifies in the `engines.redwoodjs` field of its own `package.json`. If the version of `@redwoodjs/core` you are using falls outside of the compatibility range specified by the package you are attempting to run, we will warn you and ask you to confirm that you wish to continue. -It's the responsibility of the authors of those npm packages to specify the correct range of compatibility so you should always research the packages you use with this command. Especially since they will be executing code on your machine! +It's the author of the npm package's responsibility to specify the correct compatibility range, so **you should always research the packages you use with this command**. Especially since they will be executing code on your machine! ### setup tsconfig