Skip to content
Flagship Code

Plugins

Flagship Code introduces a comprehensive approach to augmenting the customization capabilities of native iOS and Android projects, employing the concept of a plugin system. This innovative framework extends the realm of possibilities, allowing for intricate customization and seamless integration of additional functionalities into your projects.

In the context of Flagship Code, plugins can take the form of either locally stored packages or externally published ones. A notable enhancement introduced with Flagship Code version 13 is the newfound capability to maintain plugins in TypeScript without the necessity of transpiling to JavaScript. This advancement not only streamlines the development process but also fosters leaner plugins, mitigating the risk of overlooking transpilation tasks and ensuring a more seamless integration experience.

Provided Plugins

Flagship Code offers a curated selection of essential plugins designed to cater to the diverse needs of most projects. These included plugins serve as indispensable tools, each addressing specific requirements crucial for robust application development:

Plugin Generation

Local plugins offer a streamlined setup process, benefiting from being included within the parent project and having access to all parent packages. Flagship Code simplifies the process of generating, configuring, and installing a new plugin through a user-friendly command exposed by the @brandingbrand/cli package. Plugin names are required to adhere to package naming standards and should not include any scoping. By specifying the pluginPath in the flagship-code.config.ts configuration file, developers can seamlessly create new plugins using the following command:

Terminal window
yarn flagship-code generate --type plugin --name plugin-vision-camera

Building upon the previously provided guidelines, executing the designated command will result in the creation of the plugin-vision-camera package, located at the specified path ./coderc/plugins/plugin-vision-camera. Upon generation, Flagship Code seamlessly incorporates this newly created package as a linked dependency within your package.json file.

package.json
{
  "name": "my-awesome-app",
  "version": "1.0.0",
  "author": "Your Name <email@example.com>",
  "devDependencies": {
    "plugin-vision-camera": "link:./coderc/plugins/plugin-vision-camera"
  }
}

Furthermore, as part of the process, Flagship Code ensures the integration of the newly generated plugin into your project’s configuration by automatically updating the flagship-code.config.ts file. This seamless synchronization ensures that the plugin is properly configured and readily available for utilization within your project environment.

flagship-code.config.ts
import { defineConfig } from "@brandingbrand/code-cli-kit";


export default defineConfig({
  buildPath: "./coderc/build",
  envPath: "./coderc/env",
  pluginPath: "./coderc/plugins",
  plugins: ["plugin-vision-camera"],
});

Finally, Flagship Code initiates the re-installation of project dependencies to accommodate the changes made to the package.json file resulting from the addition of the newly generated plugin. This step ensures that your project remains in a coherent and fully functional state, with all dependencies properly configured and integrated.

Plugin Configuration

The plugin interface embodies simplicity through a singular entry point, index.ts, which serves the dual purpose of exposing the plugin functionality alongside its associated types. In parallel with other configurations, this interface is further bolstered by a type-guard function dubbed definePlugin. This protective measure empowers developers to tailor entry points for both iOS and Android platforms, thereby streamlining native code adjustments managed by Flagship Code. Crucially, these entry points retain an optional nature, accommodating scenarios where a plugin is designed exclusively for a particular platform, as exemplified by @brandingbrand/code-plugin-target-extension.

The generated index.ts file embodies simplicity and configurability, readily adaptable to the unique requirements of your projects.

index.ts
import {
  definePlugin,
  type BuildConfig,
  type PrebuildOptions,
} from "@brandingbrand/code-cli-kit";


export default definePlugin({
  ios: async function (build, options): Promise<void> {
    // make iOS code changes here
  },
  android: async function (build, options): Promise<void> {
    // make Android code changes here
  },
});

Within these plugins, developers harness the power of the exposed parsers and file-system APIs to manipulate native code and configurations effectively. The provided plugins serve as invaluable sources of inspiration, offering insights into best practices and implementation strategies.

It’s worth noting that plugins often require a configuration object to avoid hard-coding values, which helps maintain flexibility across various build configurations. To achieve this, developers can generate a Plugin Type that extends the build.<mode>.ts configuration. This configuration becomes accessible as part of the build object within the plugin, as demonstrated earlier. Furthermore, Plugin types themselves extend the BuildConfig type, facilitating a plug-and-play experience. Developers can override the native iOS and Android configurations within the plugin type, which are then seamlessly merged with the base configurations. This approach ensures that when a plugin is removed, the additional compartmentalized configuration is also eliminated, thereby aiding in the organization of configurations.

types.ts
export type PluginVisionCamera = {
  /**
   * A plugin object specifying permissions required for a Code Plugin.
   */
  pluginVisionCamera: Plugin<{
    /**
     * Permissions required for the iOS platform.
     */
    ios: {
      someRandomConfigValue: string;
    };
    /**
     * Permissions required for the Android platform.
     */
    android: {
      someRandomConfigValue: string;
    };
  }>;
};

This type can be utilized in your index.ts.

index.ts
import {
  definePlugin,
  type BuildConfig,
  type PrebuildOptions,
} from "@brandingbrand/code-cli-kit";


import { type PluginVisionCamera } from "./types";


export default definePlugin<PluginVisionCamera>({
  ios: async function (build, options): Promise<void> {
    // make iOS code changes here
  },
  android: async function (build, options): Promise<void> {
    // make Android code changes here
  },
});

Additionally, this type can be utilized in your build.internal.ts.

build.internal.ts
import { defineBuild } from "@brandingbrand/code-cli-kit";
import { type PluginVisionCamera } from "plugin-vision-camera";


export default defineBuild<PluginVisionCamera>({
  ios: {
    bundleId: "com.brandingbrand",
    displayName: "Branding Brand",
  },
  android: {
    packageName: "com.brandingbrand",
    displayName: "Branding Brand",
  },
  pluginVisionCamera: {
    ios: {
      deploymentTarget: "15.0",
    },
    android: {
      compileSdkVersion: "35.0.0",
    },
    plugin: {
      ios: {
        someRandomConfigValue: "myIOSValue",
      },
      android: {
        someRandomConfigValue: "myAndroidValue",
      },
    },
  },
});

This capability empowers plugin-vision-camera to extend the fundamental BuildConfig and override native configurations that are exclusive to the functionality provided by the plugin.

Plugin Testing

Generated plugins include a predefined Jest preset designed to facilitate testing of your plugin within real iOS and Android projects. These projects mirror those used by Flagship Code for generating iOS and Android native code and configurations. A unit test for both iOS and Android are included with the generated plugin.

__tests__/index.ts
/**
 * @jest-environment-options {"requireTemplate": true}
 */


/// <reference types="@brandingbrand/code-jest-config" />


import plugin from "../src";


describe("plugin", () => {
  it("ios", async () => {
    await plugin.ios?.({} as any, {} as any);


    expect(true).toBeTruthy();
  });


  it("android", async () => {
    await plugin.android?.({} as any, {} as any);


    expect(true).toBeTruthy();
  });
});

With the provided frontmatter @jest-environment-options, temporary native iOS and Android projects are at your disposal for testing your plugin.