tessl/npm-capacitor--cli

Command-line interface for Capacitor cross-platform native runtime that enables building web apps for iOS, Android, and other platforms

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Validation

Name: tessl/npm-capacitor--cli
Author: tessl

Capacitor CLI provides comprehensive validation tools and diagnostics for project setup, configuration, and development environment.

Capabilities

Core Validation System

Run multiple validation checks and aggregate results.

/**
 * Validation function type - returns error message or null if valid
 */
type CheckFunction = () => Promise<string | null>;

/**
 * Runs multiple validation checks and throws if any fail
 * @param checks - Array of validation functions to execute
 * @throws Throws aggregated error messages if any checks fail
 */
function check(checks: CheckFunction[]): Promise<void>;

Usage Example:

import { check, checkWebDir, checkPackage, checkAppConfig } from "@capacitor/cli";

const config = await loadConfig();

// Run multiple validation checks
await check([
  () => checkPackage(),
  () => checkWebDir(config),
  () => checkAppConfig(config)
]);

Project Structure Validation

Package Validation

Validate that the project has required package configuration.

/**
 * Checks for existence of package.json or valid NX monorepo setup
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkPackage(): Promise<string | null>;

Web Directory Validation

Validate web assets directory and required files.

/**
 * Validates web directory exists and contains required index.html
 * @param config - Capacitor configuration
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkWebDir(config: Config): Promise<string | null>;

App Directory Validation

Validate application directory structure.

/**
 * Validates application directory exists and is accessible
 * @param config - Capacitor configuration
 * @param dir - Directory path to validate
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkAppDir(config: Config, dir: string): Promise<string | null>;

Configuration Validation

App Configuration Validation

Validate core application configuration settings.

/**
 * Validates app configuration including app ID and app name
 * @param config - Capacitor configuration
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkAppConfig(config: Config): Promise<string | null>;

/**
 * Validates app ID format and platform compatibility
 * @param config - Capacitor configuration
 * @param id - App ID to validate
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkAppId(config: Config, id: string): Promise<string | null>;

/**
 * Validates app name format and requirements
 * @param config - Capacitor configuration
 * @param name - App name to validate
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkAppName(config: Config, name: string): Promise<string | null>;

Usage Examples:

import { checkAppConfig, checkAppId, checkAppName } from "@capacitor/cli";

const config = await loadConfig();

// Validate complete app configuration
const appConfigError = await checkAppConfig(config);
if (appConfigError) {
  console.error('App config error:', appConfigError);
}

// Validate specific app ID
const appIdError = await checkAppId(config, 'com.example.myapp');
if (appIdError) {
  console.error('App ID error:', appIdError);
}

Platform Validation

Capacitor Platform Validation

Validate that required Capacitor platform packages are installed.

/**
 * Validates that Capacitor platform package is available
 * @param config - Capacitor configuration
 * @param platform - Platform name to validate ('ios', 'android', etc.)
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkCapacitorPlatform(config: Config, platform: string): Promise<string | null>;

Android Platform Validation

Validate Android development environment and dependencies.

/**
 * Validates Android package availability
 * @param config - Capacitor configuration
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkAndroidPackage(config: Config): Promise<string | null>;

/**
 * Checks Android development environment setup
 * @param config - Capacitor configuration
 */
function doctorAndroid(config: Config): Promise<void>;

iOS Platform Validation

Validate iOS development environment and dependencies.

/**
 * Validates iOS package availability
 * @param config - Capacitor configuration
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkIOSPackage(config: Config): Promise<string | null>;

/**
 * Validates CocoaPods installation and configuration
 * @param config - Capacitor configuration
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkCocoaPods(config: Config): Promise<string | null>;

/**
 * Validates Bundler installation (for CocoaPods)
 * @param config - Capacitor configuration
 * @returns Promise resolving to null if valid, or error message if invalid
 */
function checkBundler(config: Config): Promise<string | null>;

/**
 * Checks iOS development environment setup
 * @param config - Capacitor configuration
 */
function doctorIOS(config: Config): Promise<void>;

Development Environment Diagnostics

Doctor Command

Comprehensive environment validation and diagnostics.

/**
 * Runs comprehensive diagnostics for project setup
 * @param config - Capacitor configuration
 * @param platform - Optional specific platform to check
 */
function doctorCommand(config: Config, platform?: string): Promise<void>;

Usage Examples:

# Check all platforms
npx cap doctor

# Check specific platform
npx cap doctor ios
npx cap doctor android

JDK Version Validation

Validate Java Development Kit version for Android development.

/**
 * Checks JDK major version for Android compatibility
 * @returns Promise resolving to JDK major version number
 * @throws Throws if JDK is not found or incompatible
 */
function checkJDKMajorVersion(): Promise<number>;

Platform Version Validation

Validate compatibility between Capacitor core and platform versions.

/**
 * Validates platform version compatibility with Capacitor core
 * @param config - Capacitor configuration
 * @param platform - Platform name to validate
 */
function checkPlatformVersions(config: Config, platform: string): Promise<void>;

/**
 * Gets version of specific Capacitor package
 * @param config - Capacitor configuration
 * @param platform - Platform package name
 * @returns Promise resolving to version string
 */
function getCapacitorPackageVersion(config: Config, platform: string): Promise<string>;

/**
 * Gets Capacitor core version
 * @param config - Capacitor configuration
 * @returns Promise resolving to core version string
 */
function getCoreVersion(config: Config): Promise<string>;

/**
 * Gets Capacitor CLI version
 * @param config - Capacitor configuration
 * @returns Promise resolving to CLI version string
 */
function getCLIVersion(config: Config): Promise<string>;

Package Management Validation

Package Availability

Validate that required Capacitor packages are installed and accessible.

/**
 * Gets Capacitor package information if available
 * @param config - Capacitor configuration
 * @param name - Package name to look up
 * @returns Promise resolving to PackageJson or null if not found
 */
function getCapacitorPackage(config: Config, name: string): Promise<PackageJson | null>;

/**
 * Gets Capacitor package information, throwing if not available
 * @param config - Capacitor configuration
 * @param name - Package name to require
 * @returns Promise resolving to PackageJson
 * @throws Throws if package is not found
 */
function requireCapacitorPackage(config: Config, name: string): Promise<PackageJson>;

Platform Selection and Validation

Platform Selection

Select and validate platforms for operations.

/**
 * Selects platforms to operate on, with validation
 * @param config - Capacitor configuration
 * @param selectedPlatformName - Specific platform name or undefined for all
 * @returns Promise resolving to array of valid platform names
 */
function selectPlatforms(config: Config, selectedPlatformName?: string): Promise<string[]>;

/**
 * Validates that a platform name is supported
 * @param platform - Platform name to validate
 * @returns Promise resolving to true if valid, false otherwise
 */
function isValidPlatform(platform: string): Promise<boolean>;

/**
 * Gets list of known supported platforms
 * @returns Promise resolving to array of platform names
 */
function getKnownPlatforms(): Promise<string[]>;

/**
 * Gets platforms that have been added to the project
 * @param config - Capacitor configuration
 * @returns Promise resolving to array of added platform names
 */
function getAddedPlatforms(config: Config): Promise<string[]>;

Update Validation

Validation checks specific to update operations.

/**
 * Gets validation checks required for update operations
 * @param config - Capacitor configuration
 * @param platforms - Array of platform names to validate
 * @returns Array of validation check functions
 */
function updateChecks(config: Config, platforms: string[]): CheckFunction[];

Validation Error Patterns

Common Validation Errors

The validation system provides detailed error messages for common issues:

Missing Files: Package.json, web directory, index.html
Invalid Configuration: App ID format, app name requirements
Platform Issues: Missing platform packages, version mismatches
Environment Problems: Missing development tools, incorrect versions
Permission Issues: Directory access, file permissions

Error Message Examples

// Web directory validation
"Could not find the web assets directory: /path/to/project/dist"
"The web assets directory must contain an index.html file"

// App configuration validation  
"Missing appId for new platform. Please add it in capacitor.config.json"
"Missing appName for new platform. Please add it in capacitor.config.json"

// Platform validation
"Could not find the ios platform. You must install it first: npm install @capacitor/ios"
"Could not find the android platform. You must install it first: npm install @capacitor/android"

// Package validation
"The Capacitor CLI needs to run at the root of an npm package"

Validation Best Practices

Run Doctor Regularly: Use npx cap doctor to catch environment issues early
Validate Before Operations: Run validation checks before major operations like sync or build
Check Platform Compatibility: Ensure platform versions match Capacitor core version
Verify Web Assets: Confirm web directory exists and contains built assets before copying
Monitor Configuration: Validate configuration changes before committing