@tanstack/cta-cli 0.37.1 → 0.40.0

package/dist/command-line.js

@@ -1,10 +1,18 @@
 import { resolve } from 'node:path';
 import { DEFAULT_PACKAGE_MANAGER, finalizeAddOns, getFrameworkById, getPackageManager, loadStarter, populateAddOnOptionsDefaults, } from '@tanstack/cta-engine';
+import { validateProjectName } from './utils.js';
 export async function normalizeOptions(cliOptions, forcedMode, forcedAddOns, opts) {
     const projectName = (cliOptions.projectName ?? '').trim();
     if (!projectName && !opts?.disableNameCheck) {
         return undefined;
     }
+    if (projectName) {
+        const { valid, error } = validateProjectName(projectName);
+        if (!valid) {
+            console.error(error);
+            process.exit(1);
+        }
+    }
     let tailwind = !!cliOptions.tailwind;
     let mode = forcedMode ||
         (cliOptions.template === 'file-router' ? 'file-router' : 'code-router');

package/dist/options.js

@@ -1,10 +1,21 @@
 import { intro } from '@clack/prompts';
 import { finalizeAddOns, getFrameworkById, getPackageManager, populateAddOnOptionsDefaults, readConfigFile, } from '@tanstack/cta-engine';
 import { getProjectName, promptForAddOnOptions, selectAddOns, selectGit, selectDeployment, selectPackageManager, selectRouterType, selectTailwind, selectToolchain, selectTypescript, } from './ui-prompts.js';
+import { validateProjectName } from './utils.js';
 export async function promptForCreateOptions(cliOptions, { forcedAddOns = [], forcedMode, showDeploymentOptions = false, }) {
     const options = {};
     options.framework = getFrameworkById(cliOptions.framework || 'react-cra');
-    options.projectName = cliOptions.projectName || (await getProjectName());
+    if (cliOptions.projectName) {
+        const { valid, error } = validateProjectName(cliOptions.projectName);
+        if (!valid) {
+            console.error(error);
+            process.exit(1);
+        }
+        options.projectName = cliOptions.projectName;
+    }
+    else {
+        options.projectName = await getProjectName();
+    }
     // Router type selection
     if (forcedMode) {
         options.mode = forcedMode;

package/dist/types/utils.d.ts

@@ -1,2 +1,6 @@
 import type { TemplateOptions } from './types.js';
 export declare function convertTemplateToMode(template: TemplateOptions): string;
+export declare function validateProjectName(name: string): {
+    valid: boolean;
+    error: string;
+};

package/dist/ui-prompts.js

@@ -1,5 +1,6 @@
-import { cancel, confirm, isCancel, multiselect, select, text, } from '@clack/prompts';
+import { cancel, confirm, isCancel, multiselect, note, select, text, } from '@clack/prompts';
 import { DEFAULT_PACKAGE_MANAGER, SUPPORTED_PACKAGE_MANAGERS, getAllAddOns, } from '@tanstack/cta-engine';
+import { validateProjectName } from './utils.js';
 export async function getProjectName() {
     const value = await text({
         message: 'What would you like to name your project?',
@@ -8,6 +9,10 @@ export async function getProjectName() {
             if (!value) {
                 return 'Please enter a name';
             }
+            const { valid, error } = validateProjectName(value);
+            if (!valid) {
+                return error;
+            }
         },
     });
     if (isCancel(value)) {
@@ -74,12 +79,19 @@ export async function selectPackageManager() {
     }
     return packageManager;
 }
+// Track if we've shown the multiselect help text
+let hasShownMultiselectHelp = false;
 export async function selectAddOns(framework, mode, type, message, forcedAddOns = []) {
     const allAddOns = await getAllAddOns(framework, mode);
     const addOns = allAddOns.filter((addOn) => addOn.type === type);
     if (addOns.length === 0) {
         return [];
     }
+    // Show help text only once
+    if (!hasShownMultiselectHelp) {
+        note('Use ↑/↓ to navigate • Space to select/deselect • Enter to confirm', 'Keyboard Shortcuts');
+        hasShownMultiselectHelp = true;
+    }
     const value = await multiselect({
         message,
         options: addOns

package/dist/utils.js

@@ -1,6 +1,16 @@
+import validatePackageName from 'validate-npm-package-name';
 export function convertTemplateToMode(template) {
     if (template === 'typescript' || template === 'javascript') {
         return 'code-router';
     }
     return 'file-router';
 }
+export function validateProjectName(name) {
+    const { validForNewPackages, validForOldPackages, errors, warnings } = validatePackageName(name);
+    const error = errors?.[0] || warnings?.[0];
+    return {
+        valid: validForNewPackages && validForOldPackages,
+        error: error?.replace(/name/g, 'Project name') ||
+            'Project name does not meet npm package naming requirements',
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cta-cli",
-  "version": "0.37.1",
+  "version": "0.40.0",
   "description": "Tanstack Application Builder CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,15 +29,17 @@
     "commander": "^13.1.0",
     "express": "^4.21.2",
     "semver": "^7.7.2",
+    "validate-npm-package-name": "^7.0.0",
     "zod": "^3.24.2",
-    "@tanstack/cta-engine": "0.37.1",
-    "@tanstack/cta-ui": "0.37.1"
+    "@tanstack/cta-engine": "0.40.0",
+    "@tanstack/cta-ui": "0.40.0"
   },
   "devDependencies": {
     "@tanstack/config": "^0.16.2",
     "@types/express": "^5.0.1",
     "@types/node": "^22.13.4",
     "@types/semver": "^7.7.0",
+    "@types/validate-npm-package-name": "^4.0.2",
     "@vitest/coverage-v8": "3.1.1",
     "eslint": "^9.20.0",
     "typescript": "^5.6.3",

package/src/command-line.ts

@@ -9,6 +9,7 @@ import {
   populateAddOnOptionsDefaults,
 } from '@tanstack/cta-engine'
 
+import { validateProjectName } from './utils.js'
 import type { Options } from '@tanstack/cta-engine'
 
 import type { CliOptions } from './types.js'
@@ -27,6 +28,14 @@ export async function normalizeOptions(
     return undefined
   }
 
+  if (projectName) {
+    const { valid, error } = validateProjectName(projectName)
+    if (!valid) {
+      console.error(error)
+      process.exit(1)
+    }
+  }
+
   let tailwind = !!cliOptions.tailwind
 
   let mode: string =

package/src/options.ts

@@ -21,6 +21,7 @@ import {
   selectTypescript,
 } from './ui-prompts.js'
 
+import { validateProjectName } from './utils.js'
 import type { Options } from '@tanstack/cta-engine'
 
 import type { CliOptions } from './types.js'
@@ -41,7 +42,16 @@ export async function promptForCreateOptions(
 
   options.framework = getFrameworkById(cliOptions.framework || 'react-cra')!
 
-  options.projectName = cliOptions.projectName || (await getProjectName())
+  if (cliOptions.projectName) {
+    const { valid, error } = validateProjectName(cliOptions.projectName)
+    if (!valid) {
+      console.error(error)
+      process.exit(1)
+    }
+    options.projectName = cliOptions.projectName
+  } else {
+    options.projectName = await getProjectName()
+  }
 
   // Router type selection
   if (forcedMode) {

package/src/ui-prompts.ts

@@ -3,6 +3,7 @@ import {
   confirm,
   isCancel,
   multiselect,
+  note,
   select,
   text,
 } from '@clack/prompts'
@@ -13,6 +14,7 @@ import {
   getAllAddOns,
 } from '@tanstack/cta-engine'
 
+import { validateProjectName } from './utils.js'
 import type { AddOn, PackageManager } from '@tanstack/cta-engine'
 
 import type { Framework } from '@tanstack/cta-engine/dist/types/types.js'
@@ -26,6 +28,11 @@ export async function getProjectName(): Promise<string> {
       if (!value) {
         return 'Please enter a name'
       }
+
+      const { valid, error } = validateProjectName(value)
+      if (!valid) {
+        return error
+      }
     },
   })
 
@@ -103,6 +110,9 @@ export async function selectPackageManager(): Promise<PackageManager> {
   return packageManager
 }
 
+// Track if we've shown the multiselect help text
+let hasShownMultiselectHelp = false
+
 export async function selectAddOns(
   framework: Framework,
   mode: string,
@@ -116,6 +126,12 @@ export async function selectAddOns(
     return []
   }
 
+  // Show help text only once
+  if (!hasShownMultiselectHelp) {
+    note('Use ↑/↓ to navigate • Space to select/deselect • Enter to confirm', 'Keyboard Shortcuts')
+    hasShownMultiselectHelp = true
+  }
+
   const value = await multiselect({
     message,
     options: addOns

package/src/utils.ts

@@ -1,3 +1,4 @@
+import validatePackageName from 'validate-npm-package-name'
 import type { TemplateOptions } from './types.js'
 
 export function convertTemplateToMode(template: TemplateOptions): string {
@@ -6,3 +7,16 @@ export function convertTemplateToMode(template: TemplateOptions): string {
   }
   return 'file-router'
 }
+
+export function validateProjectName(name: string) {
+  const { validForNewPackages, validForOldPackages, errors, warnings } =
+    validatePackageName(name)
+  const error = errors?.[0] || warnings?.[0]
+
+  return {
+    valid: validForNewPackages && validForOldPackages,
+    error:
+      error?.replace(/name/g, 'Project name') ||
+      'Project name does not meet npm package naming requirements',
+  }
+}

package/tests/ui-prompts.test.ts

@@ -93,7 +93,8 @@ describe('selectPackageManager', () => {
 })
 
 describe('selectAddOns', () => {
-  it('should select some add-ons', async () => {
+  it('should show keyboard shortcuts help and select add-ons', async () => {
+    const noteSpy = vi.spyOn(clack, 'note').mockImplementation(() => {})
     vi.spyOn(clack, 'multiselect').mockImplementation(async () => ['add-on-1'])
     vi.spyOn(clack, 'isCancel').mockImplementation(() => false)
 
@@ -114,7 +115,12 @@ describe('selectAddOns', () => {
       'add-on',
       'Select add-ons',
     )
+
     expect(packageManager).toEqual(['add-on-1'])
+    expect(noteSpy).toHaveBeenCalledWith(
+      'Use ↑/↓ to navigate • Space to select/deselect • Enter to confirm',
+      'Keyboard Shortcuts',
+    )
   })
 
   it('should exit on cancel', async () => {