Skip to main content

​
Overview

Capacitor configuration is managed through the capacitor.config.json file at the root of your project. This file defines how Capacitor bridges your web application with native platform functionality.

​
Current Configuration

MediGuide’s Capacitor configuration:
capacitor.config.json
{
  "appId": "com.mediguide.app",
  "appName": "MediGuide",
  "webDir": "dist"
}
This minimal configuration is sufficient for basic Capacitor functionality. Additional options can be added as needed.

​
Configuration Properties

​
App Identity

​
appId
string
required
The unique identifier for your application across platforms.
"appId": "com.mediguide.app"
Changing the appId after publishing will create a new app listing on app stores. This should only be changed before initial release.
​
appName
string
required
The display name of your application.
"appName": "MediGuide"
This name appears:
  • On the device home screen
  • In app store listings (can be overridden)
  • In the app switcher

​
Web Directory

​
webDir
string
required
The directory containing your built web assets.
"webDir": "dist"
For MediGuide, this points to the output directory of the Vite build process (configured in package.json):
package.json
{
  "scripts": {
    "build": "vite build"
  }
}

​
Advanced Configuration Options

​
Server Configuration

Configure development server settings for live reload: 
{
  "appId": "com.mediguide.app",
  "appName": "MediGuide",
  "webDir": "dist",
  "server": {
    "url": "http://192.168.1.100:5173",
    "cleartext": true,
    "androidScheme": "http"
  }
}
​
server.url
string
The URL of your development server. Use your computer’s IP address, not localhost.
​
server.cleartext
boolean
Allow HTTP traffic (required for local development on Android 9+).
​
server.androidScheme
string
The URL scheme for Android. Use "https" for production, "http" for development.
Remove the server configuration before building production releases. Live reload configuration should only be used during development.

​
Android-Specific Configuration

Add Android-specific settings: 
{
  "appId": "com.mediguide.app",
  "appName": "MediGuide",
  "webDir": "dist",
  "android": {
    "buildOptions": {
      "keystorePath": "/path/to/keystore.jks",
      "keystorePassword": "password",
      "keystoreAlias": "alias",
      "keystoreAliasPassword": "password",
      "releaseType": "APK"
    },
    "backgroundColor": "#ffffff",
    "allowMixedContent": false,
    "captureInput": true,
    "webContentsDebuggingEnabled": false
  }
}
​
android.buildOptions
object
Configuration for Android build signing and release type.
Store keystore credentials in environment variables or secure vaults, not in the config file.
​
android.backgroundColor
string
The background color to display while the web content is loading.
​
android.webContentsDebuggingEnabled
boolean
Enable Chrome DevTools debugging. Set to true for development, false for production.

​
iOS-Specific Configuration

{
  "appId": "com.mediguide.app",
  "appName": "MediGuide",
  "webDir": "dist",
  "ios": {
    "contentInset": "automatic",
    "scrollEnabled": true,
    "backgroundColor": "#ffffff",
    "allowsLinkPreview": true,
    "scheme": "MediGuide"
  }
}
​
ios.contentInset
string
How to handle safe area insets. Options: "automatic", "never".
​
ios.scrollEnabled
boolean
Enable or disable scrolling in the web view.
​
ios.scheme
string
Custom URL scheme for the app.

​
Plugin Configuration

Configure Capacitor plugins globally: 
{
  "appId": "com.mediguide.app",
  "appName": "MediGuide",
  "webDir": "dist",
  "plugins": {
    "SplashScreen": {
      "launchShowDuration": 2000,
      "backgroundColor": "#1E40AF",
      "showSpinner": false,
      "androidSpinnerStyle": "large",
      "spinnerColor": "#ffffff"
    },
    "PushNotifications": {
      "presentationOptions": ["badge", "sound", "alert"]
    },
    "LocalNotifications": {
      "smallIcon": "ic_stat_icon_config_sample",
      "iconColor": "#488AFF"
    }
  }
}
Plugin configurations can also be set at runtime using plugin-specific methods in your application code.

​
Configuration File Formats

Capacitor supports multiple configuration file formats: 
{
  "appId": "com.mediguide.app",
  "appName": "MediGuide",
  "webDir": "dist"
}
MediGuide currently uses capacitor.config.json. TypeScript configuration (.ts) provides better type safety and IDE support.

​
Best Practices

​
Security

1

Never Commit Secrets

Don’t store sensitive information like keystore passwords in the config file.Use environment variables instead:
capacitor.config.ts
const config: CapacitorConfig = {
  android: {
    buildOptions: {
      keystorePassword: process.env.KEYSTORE_PASSWORD,
    },
  },
};
2

Disable Debugging in Production

Ensure debugging features are disabled for release builds:
{
  "android": {
    "webContentsDebuggingEnabled": false
  }
}
3

Use HTTPS in Production

Only use HTTP and cleartext settings during development:
{
  "server": {
    "androidScheme": "https"
  }
}

​
Development Workflow

1

Separate Dev and Prod Configs

Consider using environment-specific configurations:
  • capacitor.config.json for production
  • capacitor.config.dev.json for development
Use the --config flag to specify:
npx cap sync --config capacitor.config.dev.json
2

Sync After Configuration Changes

Always sync after modifying the config:
npx cap sync
3

Version Control

Add sensitive config files to .gitignore:
capacitor.config.dev.json
capacitor.config.local.json

​
Syncing Configuration

After making changes to capacitor.config.json, sync the configuration to native projects: 
npx cap sync
The sync command:
  1. Copies web assets to native projects
  2. Updates native configuration based on capacitor.config.json
  3. Installs and updates Capacitor plugins
  4. Generates native project files if needed

​
Integration with Build Process

The configuration ties into MediGuide’s build workflow:
package.json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}
Typical development workflow:
1

Build Web Assets

npm run build
Outputs to the dist directory (as configured in webDir)
2

Sync to Native

npx cap sync
Copies dist contents to Android and iOS projects
3

Run or Build

npx cap run android
Launches the app with updated configuration

​
Environment Variables

You can use environment variables in TypeScript config files:
capacitor.config.ts
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: process.env.APP_ID || 'com.mediguide.app',
  appName: process.env.APP_NAME || 'MediGuide',
  webDir: 'dist',
  server: {
    url: process.env.DEV_SERVER_URL,
    cleartext: process.env.NODE_ENV === 'development',
  },
};

export default config;

​
Troubleshooting

​
Configuration Not Applied

If changes aren’t taking effect: 
npx cap sync
npx cap copy
Or clean and rebuild: 
cd android
./gradlew clean
cd ..
npx cap sync android

​
Invalid Configuration

Validate your configuration: 
npx cap doctor
This checks for common configuration issues.

​
Build Errors After Config Changes

If you encounter build errors:
  1. Verify webDir points to the correct output directory
  2. Ensure the web assets have been built (npm run build)
  3. Check that appId follows reverse-domain naming (e.g., com.company.app)
  4. Sync the configuration: npx cap sync

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us