Capacitor production builds retaining development server.url configuration

The Resolution

To guarantee that server.url and server.cleartext are absent from production builds, migrate from capacitor.config.json to capacitor.config.ts. This allows you to use conditional logic based on environment variables to omit the server configuration entirely during production builds.

Implementation via capacitor.config.ts

Convert your static JSON file to a TypeScript configuration. This approach eliminates the need for duplicate config files or fragile shell scripts in CI/CD pipelines.

import { CapacitorConfig } from '@capacitor/cli';

const isProduction = process.env.NODE_ENV === 'production';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  server: isProduction ? undefined : {
    url: 'http://localhost:8100',
    cleartext: true
  }
};

export default config;

Likely Explanation for Current Behavior

The Capacitor CLI treats the configuration file as a source of truth for the current state of the project. It does not perform "tree-shaking" or property stripping on capacitor.config.json during the copy or sync phases because it assumes the developer has provided the configuration intended for the target build. Since JSON is static, it cannot react to build flags like --prod.

Verification and Validation

To ensure the production build is correctly configured and server.cleartext is disabled, use the following verification steps:

• Asset Inspection: After running your build, inspect the bundled configuration within the native project (e.g., capacitor.config.json generated in the android/ or ios/ folders) to confirm the server key is missing.
• Runtime Test: Launch the production build on a physical device. If the app loads the bundled local assets instead of attempting to connect to localhost, the configuration is correct.
• Log Monitoring: Check Xcode or Android Studio logs. A production build retaining server.url will typically throw a net::ERR_CONNECTION_REFUSED or a WebView load error immediately upon startup.

Operational Assumptions

This solution assumes you are using Capacitor 3.x through 6.x, as capacitor.config.ts support was introduced to solve this exact limitation. It also assumes your CI/CD pipeline sets NODE_ENV=production during the build phase.

Diagnostic Detail Needed: Are you using a custom build wrapper or a specific CI provider (e.g., GitHub Actions, Bitrise) that overrides process.env during the npx cap sync step?