Asset Management

Capacitor CLI provides comprehensive asset management for copying and synchronizing web assets between web and native projects through command-line interfaces. Asset management functions are handled internally and are not exposed as exportable functions.

Capabilities

Asset Copying

Copy Command

Copy web application build files into native platform projects.

Command:

npx cap copy [platform] [options]

Options:

• --inline - Inline all source maps for easier debugging on mobile devices

Examples:

# Copy to all platforms
npx cap copy

# Copy to specific platform
npx cap copy ios
npx cap copy android

# Copy with inline source maps for debugging
npx cap copy android --inline

What it does:

• Copies web assets from webDir to native platform web directories
• Processes source maps based on inline option
• Updates web asset references in native projects
• Validates web directory and build output

Asset Synchronization

Sync Command

Synchronize web assets and update native dependencies in a single operation (combines copy + update).

Command:

npx cap sync [platform] [options]

Options:

• --deployment - Use deployment option for pod install (iOS)
• --inline - Inline all source maps for easier debugging on mobile devices

Examples:

# Sync all platforms
npx cap sync

# Sync specific platform
npx cap sync ios

# Sync with deployment flag (iOS)
npx cap sync ios --deployment

# Sync with inline source maps
npx cap sync android --inline

What it does:

1. Copy web assets to native projects
2. Update dependencies and plugins
3. Regenerate native configurations
4. Install/update native dependencies (CocoaPods for iOS, Gradle for Android)

Update Dependencies

Update Command

Update native plugins and dependencies based on package.json without copying web assets.

Command:

npx cap update [platform] [options]

Options:

• --deployment - Use deployment option for pod install (iOS)

Examples:

# Update all platforms
npx cap update

# Update specific platform
npx cap update ios

# Update with deployment flag
npx cap update ios --deployment

What it does:

• Updates native dependencies based on package.json
• Regenerates plugin configurations
• Updates Capacitor and Cordova plugin integrations
• Runs platform-specific dependency managers (CocoaPods, Gradle)

Asset Processing Details

Web Directory Processing

The CLI processes the configured web directory (webDir in capacitor.config.ts):

// Example capacitor.config.ts
const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',  // Source directory for web assets
  bundledWebRuntime: false
};

Source Map Handling

Default behavior:

• Source maps are copied as separate files
• Useful for production builds

Inline source maps (--inline flag):

• Source maps are embedded in JavaScript files
• Easier debugging on mobile devices
• Larger file sizes

Platform-Specific Asset Locations

iOS:

• Assets copied to: ios/App/App/public/
• Capacitor configuration: ios/App/App/capacitor.config.json

Android:

• Assets copied to: android/app/src/main/assets/public/
• Capacitor configuration: android/app/src/main/assets/capacitor.config.json

Common Workflows

Development Workflow

1. Build your web app:

   npm run build

2. Sync assets and dependencies:

   npx cap sync

3. Run on device:

   npx cap run ios
   npx cap run android

Live Reload Development

For live reload during development:

# Run with live reload
npx cap run ios --live-reload --host 192.168.1.100 --port 3000
npx cap run android --live-reload --host 192.168.1.100 --port 3000

Production Build Workflow

1. Build optimized web app:

   npm run build

2. Copy assets (no source maps inline):

   npx cap copy

3. Build native apps:

   npx cap build ios
   npx cap build android

Asset Validation

Doctor Command

Check for common asset and configuration issues:

# Check all platforms
npx cap doctor

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

The doctor command validates:

• Web directory exists and contains built assets
• Native platform configurations are correct
• Dependencies are properly installed
• Plugin configurations are valid

Configuration Options

Web Directory Configuration

const config: CapacitorConfig = {
  webDir: 'dist',           // Directory containing built web assets
  bundledWebRuntime: false, // Whether to bundle Capacitor runtime
  server: {                 // Development server configuration
    url: 'http://localhost:3000',
    cleartext: true
  }
};

Asset Exclusions

Configure which files to exclude from copying:

const config: CapacitorConfig = {
  // ... other config
  cordova: {
    preferences: {
      // Cordova preferences that affect asset handling
    }
  }
};

Internal Architecture

Asset management is implemented through internal modules:

• Copy operations are handled by /tasks/copy.ts
• Sync operations are handled by /tasks/sync.ts
• Update operations are handled by /tasks/update.ts
• Source map processing is in /tasks/sourcemaps.ts

These internal functions are called by CLI commands but are not part of the public API.