feat: add `--help` and `--version` options (#646)

* feat: add `--help` and `--version` options

* chore: update descriptions for feature flags [skip ci]

diff --git a/README.md b/README.md
index be7ad171ea358f9b5df9bd5f0a9b968800d44ab8..075dff142d31c96b57f3eb61a75837c7296bd83c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -17,7 +17,9 @@ npm create vue@latest
 > [!NOTE]
 > (`@latest` or `@legacy`) MUST NOT be omitted, otherwise `npm` may resolve to a cached and outdated version of the package.
 
-Or, if you need to support IE11, you can create a Vue 2 project with:
+By default the command will run in interactive mode, but you can also provide feature flags in the CLI arguments to skip the prompts. Run `npm create vue@latest --help` to see all available options.
+
+If you need to support IE11, you can create a Vue 2 project with:
 
 ```sh
 npm create vue@legacy

diff --git a/index.ts b/index.ts
index bf6031eb5121e70a560e70c293455c2ca090632d..004f97873b587b9c779d48767fefe836878d82ad 100755 (executable)
--- a/index.ts
+++ b/index.ts
@@ -6,7 +6,7 @@ import * as path from 'node:path'
 import { parseArgs } from 'node:util'
 
 import prompts from 'prompts'
-import { red, green, bold } from 'kleur/colors'
+import { red, green, cyan, bold } from 'kleur/colors'
 
 import ejs from 'ejs'
 
@@ -20,6 +20,8 @@ import getLanguage from './utils/getLanguage'
 import renderEslint from './utils/renderEslint'
 import trimBoilerplate from './utils/trimBoilerplate'
 
+import cliPackageJson from './package.json'
+
 function isValidPackageName(projectName) {
   return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(projectName)
 }
@@ -61,33 +63,56 @@ function emptyDir(dir) {
   )
 }
 
-async function init() {
-  console.log()
-  console.log(
-    process.stdout.isTTY && process.stdout.getColorDepth() > 8
-      ? banners.gradientBanner
-      : banners.defaultBanner,
-  )
-  console.log()
+const helpMessage = `\
+Usage: create-vue [FEATURE_FLGAS...] [OPTIONS...] [DIRECTORY]
+
+Create a new Vue.js project.
+Start the CLI in interactive mode when no FEATURE_FLAGS is provided, or if the DIRECTORY argument is not a valid package name.
+
+Options:
+  --force
+    Create the project even if the directory is not empty.
+  --bare
+    Create a barebone project without example code.
+  --help
+    Display this help message.
+  --version
+    Display the version number of this CLI.
+
+Available feature flags:
+  --default
+    Create a project with the default configuration without any additional features.
+  --ts, --typescript
+    Add TypeScript support.
+  --jsx
+    Add JSX support.
+  --router, --vue-router
+    Add Vue Router for SPA development.
+  --pinia
+    Add Pinia for state management.
+  --vitest
+    Add Vitest for unit testing.
+  --cypress
+    Add Cypress for end-to-end testing.
+    If used without ${cyan('--vitest')}, it will also add Cypress Component Testing.
+  --playwright
+    Add Playwright for end-to-end testing.
+  --nightwatch
+    Add Nightwatch for end-to-end testing.
+    If used without ${cyan('--vitest')}, it will also add Nightwatch Component Testing.
+  --eslint
+    Add ESLint for code quality.
+  --eslint-with-prettier
+    Add Prettier for code formatting in addition to ESLint.
+
+Unstable feature flags:
+  --tests, --with-tests
+    Add both unit testing and end-to-end testing support.
+    Currently equivalent to ${cyan('--vitest --cypress')}, but may change in the future.
+`
 
+async function init() {
   const cwd = process.cwd()
-  // possible options:
-  // --default
-  // --typescript / --ts
-  // --jsx
-  // --router / --vue-router
-  // --pinia
-  // --with-tests / --tests (equals to `--vitest --cypress`)
-  // --vitest
-  // --cypress
-  // --nightwatch
-  // --playwright
-  // --eslint
-  // --eslint-with-prettier (only support prettier through eslint for simplicity)
-  // in addition to the feature flags, you can also pass the following options:
-  // --bare (for a barebone template without example code)
-  // --force (for force overwriting without confirming)
-
   const args = process.argv.slice(2)
 
   // alias is not supported by parseArgs
@@ -106,6 +131,16 @@ async function init() {
     strict: false,
   })
 
+  if (argv.help) {
+    console.log(helpMessage)
+    process.exit(0)
+  }
+
+  if (argv.version) {
+    console.log(`${cliPackageJson.name} v${cliPackageJson.version}`)
+    process.exit(0)
+  }
+
   // if any of the feature flags is set, we would skip the feature prompts
   const isFeatureFlagsUsed =
     typeof (
@@ -145,6 +180,14 @@ async function init() {
     needsPrettier?: boolean
   } = {}
 
+  console.log()
+  console.log(
+    process.stdout.isTTY && process.stdout.getColorDepth() > 8
+      ? banners.gradientBanner
+      : banners.defaultBanner,
+  )
+  console.log()
+
   try {
     // Prompts:
     // - Project name: