diff --git a/docs/templates.md b/docs/templates.md index 5d5482c5..06326405 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -2,26 +2,28 @@ title: Templates --- -When you run `oclif generate`, it will ask if you'd like to use either CommonJS or ESM for your CLI. Both options produce the same CLI (same tsconfig, bin scripts, example commands, etc). +When you run `oclif generate`, you're prompted whether you want to use either [CommonJS](https://nodejs.org/api/modules.html) or [ESM](https://nodejs.org/api/esm.html) for your CLI. CommonJS modules were the original way to package JavaScript and TypeScript packages for reuse in Node.js; ESM modules are now the official standard format. Both options produce the same CLI, such as the same `tsconfig` file, `bin` scripts, sample commands, and so on. -We'll give you a brief rundown of everything that's included in your newly generated CLI: +Here's a brief rundown of everything that's included in your newly generated CLI. ## Bin Scripts -The templates contains 4 bin scripts that are used for either production or development. -- `bin/run.js` - Run the CLI in production (macos and linux) -- `bin/dev.js` - Run the CLI in development (macos and linux) -- `bin/run.cmd` - Run the CLI in production (windows) -- `bin/dev.cmd` - Run the CLI in development (windows) +The templates contains 4 `bin` scripts that you can use for either production or development. -The `bin` entry in your `package.json` will point to the `bin/run.js` file - this tells `npm` to use that file when installing the CLI. If you create os-specific installers using `oclif pack`, then the appropriate `run` script will be added to the final installer based on the target operating system. +- `bin/run.js` - Run the CLI in production (macOS and Linux) +- `bin/dev.js` - Run the CLI in development (macOS and Linux) +- `bin/run.cmd` - Run the CLI in production (Windows) +- `bin/dev.cmd` - Run the CLI in development (Windows) -We encourage you to use the `dev` scripts for your local development. Doing so will oclif to auto-transpile your typescript at runtime so you don't have to worry about compiling your code before every command execution. The dev scripts will also produce more verbose warnings and errors to make it easier to figure out what went wrong. +The `bin` entry in your `package.json` points to the `bin/run.js` file, which in turn tells `npm` to use that file when installing the CLI. If you create operating system-specific installers using `oclif pack`, then the appropriate `run` script is added to the final installer based on the target operating system. -The `dev.js` that comes with the templates uses `ts-node` as the node runtime. You, however, have options here. You can use any of the following -- [tsx](https://www.npmjs.com/package/tsx) -- [bun](https://bun.sh/) -- `node` - if you use node and ESM, please ensure that you're using a loader that will allow it to use ESM modules (e.g. `--loader ts-node/esm`). See [ESM](esm.md) for more. +We encourage you to use the `dev` scripts for your local development. Doing so causes oclif to auto-transpile your TypeScript at runtime so you don't have to worry about compiling your code before every command execution. The `dev` scripts also produce more verbose warnings and errors, which makes it easier to figure out what went wrong. + +The `dev.js` script uses `ts-node` as the Node.js runtime. However, you can use any of the following if you prefer: + +- [TypeScript Execute (tsx)](https://www.npmjs.com/package/tsx) +- [Bun](https://bun.sh/) +- `node` - If you use `node` and ESM, make sure you're using a loader that allows it to use ESM modules, such as `--loader ts-node/esm`. See [ESM](esm.md) for more information. For any of these you can point the hashbang in the file to a global install (e.g. `ts-node`) or to a locally installed one (`node_modules/.bin/ts-node`).