@mamillastre/capacitor-environment

Capacitor plugin to get JSON based environment specific data

You can support this plugin to integrate the Capacitor Community by adding feedbacks or a 👍 reaction to this proposal.

This plugin takes advantage of the iOS schemes & Android product flavors to provide a JSON configuration to the running web application.
This extra configuration improves your environment management if you followed the Create Environment Specific Configuration guide.

The advantages of using this plugin instead of managing the environment inside the web application:

• One web application build instead of one per environment
• Better development experience in the native IDEs by only switching the scheme/flavor
• On Android, build all the applications with one command (ex: gradlew bundleRelease) instead of one per environment

npm install @mamillastre/capacitor-environment
npx cap sync

This configuration guide conciders that you already followed the Create Environment Specific Configuration guide and created the Android product flavors & the iOS schemes.

Add your environment information in the Capacitor configuration of the plugin.

Example in capacitor.config.ts:

/// <reference types="@mamillastre/capacitor-environment" />

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

const config: CapacitorConfig = {
  plugins: {
    Environment: {
      environments: {
        default: { path: 'path/to/my/environment.production.json' },
        otherEnvironmentName: { path: 'path/to/an/other/environment.json' },
      },
    },
  },
};

export default config;

Add the environment configuration files copy to you package.json scripts:

"scripts": {
  "capacitor:copy:after": "npx capacitor-environment copy"
}

Run:

npx cap copy

Open up the Capacitor application’s iOS project in Xcode by running npx cap open ios.
Right-click the App group (under the App target) and select New Group from the context menu. Name this new group environment.

In the Finder, open the ios/App/App/environment folder.
It contains all the copied configuration sorted into named folders.
For each of the environment.json files in this folder:

• Drag & drop the file into the new created group environment in Xcode.
• In the add to the project options (automatically displayed by Xcode):
  • Uncheck the "Copy items if needed"
  • Check ONLY the target that corresponds to the environment file
  • Press "Finish"

To allow TypeScript autocompletion, you must override the EnvironmentData interface in your app with your expected data.

Example:

environment.d.ts

import '@mamillastre/capacitor-environment';

declare module '@mamillastre/capacitor-environment' {
  /** My app environment data */
  export interface EnvironmentData {
    /** The environment name */
    name: string;
    /** The environment endpoint URL */
    endpoint: string;
  }
}

An environment.json file must be available at the root your web application.
You must manage this file depending on the environment on your own.

Example on an Angular app:
You must add the asset copy on the wanted Angular configurations

"assets": [
  {
    "glob": "environment.json",
    "input": "path/to/my/environment",
    "output": "/"
  }
]

import { Environment } from '@mamillastre/capacitor-environment';

const printEnvironmentData = async () => {
  // Setting the environment version may be optional depending the cache
  // configuration you applied to the 'environment.json' file
  if (Capacitor.getPlatform() === 'web') {
    await Environment.setVersion({ version: '1.0.0' });
  }

  // Get the environment data
  const env = await Environment.get();
  console.log('Environment data:', env);
};

• get(...)
• setVersion(...)
• Interfaces

get(options?: GetEnvironmentOptions | undefined) => Promise<EnvironmentData>

Returns the environment configuration.

Returns: Promise<EnvironmentData>

setVersion(options: SetVersionOptions) => Promise<void>

Set the app version.

Only available on web.

Allow to force the environment.json refresh when the file is cached by the browser.

The environment data as a JSON object.

To enable the autocompletion, this interface must be extended.