Skip to content

Commit

Permalink
docs(cli): Setup from npm package (#9215)
Browse files Browse the repository at this point in the history
**Docs**
This is designed to cover the new `yarn rw setup package <npm-package>`
command.

---------

Co-authored-by: Dominic Saadi <[email protected]>
  • Loading branch information
Josh-Walker-GM and jtoar committed Sep 20, 2023
1 parent 0362870 commit 1106e92
Showing 1 changed file with 33 additions and 0 deletions.
33 changes: 33 additions & 0 deletions docs/docs/cli-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -1722,6 +1722,7 @@ yarn redwood setup <category>
| `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 |
Expand Down Expand Up @@ -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 <npm-package>
```
| Arguments & Options | Description |
| :------------------ | :----------------------- |
| `--force, -f` | Forgo compatibility checks |
**Usage**
Run the made up `@redwoodjs/setup-example` package:
```bash
~/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 @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 that you wish to continue.
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
Add a `tsconfig.json` to both the web and api sides so you can start using [TypeScript](typescript/index).
Expand Down

0 comments on commit 1106e92

Please sign in to comment.