or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

asset-management.mdcli-commands.mdconfiguration.mdindex.mdplatform-operations.mdplugin-management.mdvalidation.md
tile.json

configuration.mddocs/

Configuration Management

Capacitor CLI provides comprehensive configuration management with full TypeScript support, enabling loading, validation, and writing of Capacitor project configurations.

Capabilities

Load Configuration

Loads the complete Capacitor configuration, merging all sources including app config, platform configs, and CLI settings.

/**
 * Loads and merges Capacitor configuration from all sources
 * @returns Promise resolving to complete Config object
 */
function loadConfig(): Promise<Config>;

interface Config {
  readonly android: AndroidConfig;
  readonly ios: IOSConfig;
  readonly web: WebConfig;
  readonly cli: CLIConfig;
  readonly app: AppConfig;
  readonly plugins?: PluginsConfig;
}

Usage Example:

import { loadConfig } from "@capacitor/cli";

const config = await loadConfig();

// Access app configuration
console.log(config.app.appId);       // com.example.app
console.log(config.app.appName);     // My App
console.log(config.app.webDir);      // dist

// Access platform paths
console.log(config.android.platformDir);  // android
console.log(config.ios.platformDir);      // ios

// Access CLI information
console.log(config.cli.package.version);  // 7.4.3

Write Configuration

Writes external configuration to the appropriate config file (JSON or TypeScript).

/**
 * Writes external configuration to file
 * @param extConfig - External configuration object to write
 * @param extConfigFilePath - Path to configuration file
 */
function writeConfig(extConfig: ExternalConfig, extConfigFilePath: string): Promise<void>;

type ExternalConfig = DeepReadonly<CapacitorConfig>;

// Configuration file name constants
const CONFIG_FILE_NAME_TS = 'capacitor.config.ts';
const CONFIG_FILE_NAME_JS = 'capacitor.config.js';
const CONFIG_FILE_NAME_JSON = 'capacitor.config.json';

Usage Example:

import { writeConfig } from "@capacitor/cli";

const config = {
  appId: "com.example.newapp",
  appName: "New App",
  webDir: "build",
  bundledWebRuntime: false,
  server: {
    url: "http://localhost:3000"
  }
};

await writeConfig(config, "capacitor.config.json");

Configuration File Constants

Constants for configuration file names used by Capacitor.

const CONFIG_FILE_NAME_TS = 'capacitor.config.ts';
const CONFIG_FILE_NAME_JS = 'capacitor.config.js';
const CONFIG_FILE_NAME_JSON = 'capacitor.config.json';

Configuration Interfaces

App Configuration

interface AppConfig {
  readonly rootDir: string;
  readonly appId: string;
  readonly appName: string;
  readonly webDir: string;
  readonly webDirAbs: string;
  readonly package: PackageJson;
  readonly extConfigType: 'json' | 'js' | 'ts';
  readonly extConfigName: string;
  readonly extConfigFilePath: string;
  readonly extConfig: ExternalConfig;
}

CLI Configuration

interface CLIConfig {
  readonly rootDir: string;
  readonly assetsDir: string;
  readonly assetsDirAbs: string;
  readonly assets: {
    readonly ios: PlatformAssetsConfig;
    readonly android: PlatformAssetsConfig;
  };
  readonly package: PackageJson;
  readonly os: OS;
}

interface PlatformAssetsConfig {
  readonly platformTemplateArchive: string;
  readonly platformTemplateArchiveAbs: string;
  readonly cordovaPluginsTemplateArchive: string;
  readonly cordovaPluginsTemplateArchiveAbs: string;
}

External Configuration Schema

Complete Capacitor configuration schema as defined in capacitor.config files.

interface CapacitorConfig {
  appId?: string;
  appName?: string;
  webDir?: string;
  loggingBehavior?: 'none' | 'debug' | 'production';
  overrideUserAgent?: string;
  appendUserAgent?: string;
  backgroundColor?: string;
  zoomEnabled?: boolean;
  initialFocus?: boolean;
  
  android?: {
    path?: string;
    overrideUserAgent?: string;
    appendUserAgent?: string;
    backgroundColor?: string;
    zoomEnabled?: boolean;
    allowMixedContent?: boolean;
    captureInput?: boolean;
    webContentsDebuggingEnabled?: boolean;
    loggingBehavior?: 'none' | 'debug' | 'production';
    includePlugins?: string[];
    flavor?: string;
    initialFocus?: boolean;
    minWebViewVersion?: number;
    minHuaweiWebViewVersion?: number;
    buildOptions?: {
      keystorePath?: string;
      keystorePassword?: string;
      keystoreAlias?: string;
      keystoreAliasPassword?: string;
      releaseType?: 'AAB' | 'APK';
      signingType?: 'apksigner' | 'jarsigner';
    };
    useLegacyBridge?: boolean;
    resolveServiceWorkerRequests?: boolean;
    adjustMarginsForEdgeToEdge?: 'auto' | 'force' | 'disable';
  };
  
  ios?: {
    path?: string;
    scheme?: string;
    overrideUserAgent?: string;
    appendUserAgent?: string;
    backgroundColor?: string;
    zoomEnabled?: boolean;
    contentInset?: 'automatic' | 'scrollableAxes' | 'never' | 'always';
    scrollEnabled?: boolean;
    cordovaLinkerFlags?: string[];
    allowsLinkPreview?: boolean;
    loggingBehavior?: 'none' | 'debug' | 'production';
    includePlugins?: string[];
    limitsNavigationsToAppBoundDomains?: boolean;
    preferredContentMode?: 'recommended' | 'desktop' | 'mobile';
    handleApplicationNotifications?: boolean;
    webContentsDebuggingEnabled?: boolean;
    initialFocus?: boolean;
    buildOptions?: {
      signingStyle?: 'automatic' | 'manual';
      exportMethod?: string;
      signingCertificate?: string;
      provisioningProfile?: string;
    };
  };
  
  server?: {
    hostname?: string;
    iosScheme?: string;
    androidScheme?: string;
    url?: string;
    cleartext?: boolean;
    allowNavigation?: string[];
    errorPath?: string;
    appStartPath?: string;
  };
  
  cordova?: {
    accessOrigins?: string[];
    preferences?: { [key: string]: string | undefined };
    failOnUninstalledPlugins?: boolean;
  };
  
  plugins?: PluginsConfig;
  includePlugins?: string[];
}

interface PluginsConfig {
  [key: string]: {
    [key: string]: any;
  } | undefined;
  
  CapacitorCookies?: {
    enabled?: boolean;
  };
  
  CapacitorHttp?: {
    enabled?: boolean;
  };
}

Package JSON Interface

interface PackageJson {
  readonly name: string;
  readonly version: string;
  readonly dependencies?: { readonly [key: string]: string | undefined };
  readonly devDependencies?: { readonly [key: string]: string | undefined };
}