docs: add examples

.eslintrc

@@ -1,3 +1,11 @@
 {
-	"extends": "@so1ve"
+	"extends": "@so1ve",
+	"overrides": [
+		{
+			"files": "./examples/**",
+			"rules": {
+				"no-console": "off"
+			}
+		}
+	]
 }

README.md

@@ -13,6 +13,9 @@
 - [✨ Features](#-features)
 <!-- tocstop -->
 
+> [!NOTE]  
+> This package is ESM-only.
+
 # 🗒 Description
 
 Clerc is a full/featured library (tool set) for building CLI Apps in Node.js, Deno or Bun.
@@ -26,10 +29,46 @@ Clerc is a full/featured library (tool set) for building CLI Apps in Node.js, De
 - **Parses parameters** - No need to read them by yourself.
 - **I18N** - Easy to change different locales.
 
+# 😊 The simplest CLI example
+
+Install clerc, and create a file named `cli.mjs`:
+
+```ts
+import { Clerc } from "clerc";
+
+Clerc.create(
+	"foo", // CLI Name
+	"A foo CLI", // CLI Description
+	"0.0.0", // CLI Version
+)
+	.command(
+		"bar", // Command name
+		"A bar command", // Command description
+	)
+	.on(
+		"bar",
+		(
+			_ctx, // The command context, but we haven't used it yet
+		) => {
+			console.log("Hello, world from Clerc.js!");
+		},
+	)
+	.parse(); // Parse the arguments and run!
+```
+
+Then run: `node cli.mjs bar`. It should log in your shell: `Hello, world from Clerc.js!`
+
 # 📖 Documentation
 
 Please see https://clerc.js.org.
 
+# 🦄 Examples
+
+Check the examples made with `Clerc.js`:
+
+- [Greeting](./examples/greeting) - The example from above
+- [Bumpp](./examples/bumpp) - Reimplementation of [`Bumpp`](https://github.com/antfu/bumpp)'s CLI
+
 # 🤔 More...
 
 ## Why using Clerc?

examples/bumpp/index.mts

@@ -0,0 +1,85 @@
+import { Clerc, Root, helpPlugin, versionPlugin } from "clerc";
+
+Clerc.create(
+	"bumpp",
+	"Interactive CLI that bumps your version numbers and more",
+	"9.2.0",
+)
+	.use(helpPlugin())
+	.use(versionPlugin())
+	.command(Root, "Bump your version numbers", {
+		parameters: ["[files...]"],
+		flags: {
+			preid: {
+				type: String,
+				description: "ID for prerelease",
+			},
+			all: {
+				type: Boolean,
+				description: "Include all files",
+				default: false,
+			},
+			commit: {
+				type: String,
+				alias: "c",
+				description: "Commit message",
+			},
+			noCommit: {
+				type: Boolean,
+				description: "Skip commit",
+				default: true,
+			},
+			tag: {
+				type: String,
+				alias: "t",
+				description: "Tag name",
+			},
+			push: {
+				type: Boolean,
+				alias: "p",
+				description: "Push to remote",
+				default: true,
+			},
+			yes: {
+				type: Boolean,
+				alias: "y",
+				description: "Skip confirmation",
+				default: true,
+			},
+			recursive: {
+				type: Boolean,
+				alias: "r",
+				description: "Bump package.json files recursively",
+				default: false,
+			},
+			noVerify: {
+				type: Boolean,
+				description: "Skip git verification",
+				default: true,
+			},
+			ignoreScripts: {
+				type: Boolean,
+				description: "Ignore scripts",
+				default: false,
+			},
+			quiet: {
+				type: Boolean,
+				description: "Quiet mode",
+				default: false,
+			},
+			version: {
+				type: String,
+				alias: "v",
+				description: "Target version",
+			},
+			execute: {
+				type: String,
+				alias: "x",
+				description: "Commands to execute after version bumps",
+			},
+		},
+	})
+	.on(Root, (ctx) => {
+		console.log(`Bumpping version:\n${JSON.stringify(ctx, null, 2)}`);
+	})
+	.parse();

examples/greeting/index.mts

@@ -0,0 +1,8 @@
+import { Clerc } from "clerc";
+
+Clerc.create("foo", "A foo CLI", "0.0.0")
+	.command("bar", "A bar command")
+	.on("bar", (_ctx) => {
+		console.log("Hello, world from Clerc.js!");
+	})
+	.parse();

package.json

@@ -13,17 +13,18 @@
 		"watch": "pnpm -r --parallel run watch"
 	},
 	"devDependencies": {
-		"@antfu/ni": "^0.21.5",
-		"@so1ve/eslint-config": "^0.119.3",
-		"@so1ve/prettier-config": "^0.119.3",
-		"@types/node": "^18.17.1",
-		"bumpp": "^9.1.1",
-		"eslint": "^8.46.0",
-		"pkgroll": "^1.10.0",
-		"prettier": "^3.0.0",
+		"@antfu/ni": "^0.21.8",
+		"@so1ve/eslint-config": "^0.123.0",
+		"@so1ve/prettier-config": "^0.123.0",
+		"@types/node": "^18.17.18",
+		"bumpp": "^9.2.0",
+		"clerc": "workspace:*",
+		"eslint": "^8.49.0",
+		"pkgroll": "^1.11.0",
+		"prettier": "^3.0.3",
 		"rimraf": "^3.0.2",
-		"typescript": "^5.1.6",
-		"vite": "^4.4.7",
-		"vitest": "^0.34.2"
+		"typescript": "^5.2.2",
+		"vite": "^4.4.9",
+		"vitest": "^0.34.4"
 	}
 }

packages/core/package.json

@@ -55,7 +55,7 @@
 		"defu": "^6.1.2",
 		"is-platform": "^1.0.0",
 		"lite-emit": "^2.3.0",
-		"type-fest": "^4.0.0",
+		"type-fest": "^4.3.1",
 		"type-flag": "^3.0.0"
 	}
 }

packages/plugin-help/package.json

@@ -53,7 +53,7 @@
 	},
 	"dependencies": {
 		"@clerc/utils": "workspace:*",
-		"@types/text-table": "^0.2.2",
+		"@types/text-table": "^0.2.3",
 		"string-width": "^6.1.0",
 		"text-table": "^0.2.0",
 		"yoctocolors": "^1.0.0"

packages/plugin-not-found/package.json

@@ -53,7 +53,7 @@
 	},
 	"dependencies": {
 		"@clerc/utils": "workspace:*",
-		"didyoumean2": "^5.0.0",
+		"didyoumean2": "^6.0.1",
 		"yoctocolors": "^1.0.0"
 	},
 	"peerDependencies": {

packages/plugin-version/src/index.ts

@@ -5,13 +5,13 @@ import { locales } from "./locales";
 
 interface VersionPluginOptions {
 	/**
-	 * Whether to register the help command.
+	 * Whether to register the version command.
 	 *
 	 * @default true
 	 */
 	command?: boolean;
 	/**
-	 * Whether to register the global help flag.
+	 * Whether to register the global version flag.
 	 *
 	 * @default true
 	 */

packages/utils/package.json

@@ -46,7 +46,7 @@
 		"watch": "pkgroll --watch"
 	},
 	"devDependencies": {
-		"type-fest": "^4.0.0"
+		"type-fest": "^4.3.1"
 	},
 	"peerDependencies": {
 		"@clerc/core": "*"