From 9d9b2ab6ddb126ab9174d5b395652f0ea88a2328 Mon Sep 17 00:00:00 2001 From: Mike Donnalley Date: Wed, 10 Apr 2024 13:36:00 -0600 Subject: [PATCH] feat: improve introduction --- docs/introduction.md | 78 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 4 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index 46f3385d..e2d7760d 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -4,7 +4,7 @@ title: Introduction oclif is a framework for building CLIs in Node. It can be used like a [simple flag parser](https://github.com/oclif/core#usage) but is capable of much more. It's designed to be extensible so that you can easily add plugins such as the [update warning plugin](https://github.com/oclif/plugin-warn-if-update-available) or build your own for users to install at runtime. -The oclif generator creates a CLI project in [TypeScript](https://github.com/oclif/hello-world) to get you started quickly. It requires very few runtime dependencies and has extremely minimal overhead. +The oclif generator creates a CLI project in [TypeScript](https://github.com/oclif/hello-world) to get you started quickly. It requires very few runtime dependencies and has minimal overhead. Everything is customizable in oclif. Even the flag parser and help generation is optional and can be replaced. It's a platform to build upon that provides smart defaults without locking you in to any specific tools or behavior. @@ -13,14 +13,84 @@ Everything is customizable in oclif. Even the flag parser and help generation is Only [LTS Node versions](https://nodejs.org/en/about/previous-releases) are supported. You can add the [node](https://www.npmjs.com/package/node) package to your CLI to ensure users are on a specific Node version. -## Quickstart +## Create oclif project from scratch -Creating a CLI: +To create a new oclif project from scratch, you can run the `oclif generate` command: -```sh-session +``` $ npx oclif generate mynewcli ? npm package name (mynewcli): mynewcli $ cd mynewcli $ ./bin/dev.js hello world hello world! (./src/commands/hello/world.ts) ``` + +This will create a new project based on our [templates](./templates.md). To learn more about what's included in these templates, we encourage you to read over their documentation [here](./templates.md). + +Once `oclif generate` is complete, you can run your CLI using the included [bin scripts](./templates.md#bin-scripts) + +Use `bin/dev.js` to run your CLI in development mode: + +``` +$ ./bin/dev.js hello world +hello world! (./src/commands/hello/world.ts) +``` + +Use `bin/run.js` to run your CLI in production mode: + +``` +$ ./bin/run.js hello world +hello world! (./src/commands/hello/world.ts) +``` + +## Initialize oclif in an existing project + +If you'd like to start using oclif inside an existing project of yours, then you can use the `oclif init` command to add the necessary files, dependencies, and configuration. + +``` +$ npx oclif init +? Command bin name the CLI will export (my-pkg): my-pkg +? Select topic separator: spaces +? Select a module type: CommonJS +? Select a package manager: npm + +Created CLI in my-pkg +``` + +`oclif init` will add the following: +- bin scripts: bin/run.js, bin/run.cmd, bin/dev.js, and bin/dev.cmd. See [bin scripts](./templates.md#bin-scripts) for more. +- oclif section to package.json with bin, dirname, commands, and topicSeparator set. See [Configuring Your CLI](./configuring_your_cli.md) for more. +- `@oclif/core` to dependencies in your package.json (if it's not already there) +- `ts-node` to devDependencies in your package.json (if it's not already there) + +## Next Steps + +### Add commands +Once you've generated an oclif project or initialized it in your existing project, you can begin adding new [commands](./commands.md): + +``` +npx oclif generate command foo:bar +``` + +This will create a new command in `src/commands/foo/bar.ts` that can be customized to do whatever you need it to do. + +The documentation for [flags](./flags.md) and [args](./args.md) covers how to add these to your command and the documentation for [commands](./commands.md) covers the other options you can set on your command. + +### Add hooks + +You can also add [hooks](./hooks.md) to your CLI that allow you to further customize the behavior of your CLI: + +``` +npx oclif generate hook my-hook --event init +``` + +### Further customizations + +- [Configuring Your CLI](./configuring_your_cli.md) +- [Custom Help](./help_classes.md) +- [Use a Base Command Class](./base_class.md) +- [Enhance the user experience](./user_experience.md) + +## Other Tutorials + +Our friend, [@joshcanhelp](https://github.com/joshcanhelp), wrote a fantastic [tutorial on his blog](https://www.joshcanhelp.com/oclif/) that we encourage you to read as well.