Getting Started

1. Install the package

   npm

   npm i @capgo/capacitor-env

   pnpm

   pnpm add @capgo/capacitor-env

   yarn

   yarn add @capgo/capacitor-env

   bun

   bun add @capgo/capacitor-env

2. Sync native platforms

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Declare configuration values

Add keys to the Capacitor config so they are baked into your native builds. You can create multiple config variants (capacitor.config.prod.ts, capacitor.config.dev.ts, etc.) to swap values per environment.

capacitor.config.ts

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    Env: {
      API_URL: 'https://api.example.com',
      PUBLIC_KEY: 'pk_live_123',
    },
  },
};

export default config;

On native platforms the values are stored inside the generated configuration files (ios/App/App/capacitor.config.json and android/app/src/main/assets/capacitor.config.json). Update those files per flavor if you need tenant-specific values.

Read values in code

import { Env } from '@capgo/capacitor-env';

const apiUrl = await Env.getKey({ key: 'API_URL' }).then((result) => result.value);

if (!apiUrl) {
  throw new Error('Missing API_URL configuration');
}

Provide fallbacks

const loadConfig = async () => {
  const { value: endpoint } = await Env.getKey({ key: 'API_URL' });
  return endpoint || 'https://staging.example.com';
};

Tips

• Use different capacitor.config files per environment and point the CLI to the right one with npx cap run ios --configuration=prod.
• Combine with Capgo updater channels to ship tenant-specific values without publishing new binaries.
• Keep secrets out of source control by substituting them during your CI build before npx cap sync.