or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

android-config.mdandroid-plugins.mdcore-plugin-system.mdindex.mdios-config.mdios-plugins.mdmod-system.mdutilities.md
tile.json

core-plugin-system.mddocs/

Core Plugin System

The core plugin system provides the foundational functionality for creating, composing, and executing configuration plugins in @expo/config-plugins. It handles plugin resolution, execution order, error handling, and caching.

Plugin Execution

withPlugins

Apply multiple plugins to a configuration in sequence.

function withPlugins(
  config: ExpoConfig,
  plugins: (StaticPlugin | ConfigPlugin | string)[]
): ExpoConfig;

Parameters:

  • config: The Expo configuration object to modify
  • plugins: Array of plugins to apply, can be plugin functions, static plugin tuples, or module paths

Usage:

const config = withPlugins(baseConfig, [
  withCustomFeature,
  ["@expo/config-plugins", { option: "value" }],
  "./local-plugin"
]);

withStaticPlugin

Apply a single static plugin with automatic resolution and error handling.

function withStaticPlugin(
  config: ExpoConfig,
  options: { plugin: StaticPlugin | ConfigPlugin | string }
): ExpoConfig;

Parameters:

  • config: The Expo configuration object to modify
  • options.plugin: The plugin to apply - can be a function, static tuple, or module path

Plugin Utilities

createRunOncePlugin

Create a plugin wrapper that ensures the plugin only executes once based on a cache key.

function createRunOncePlugin<T>(
  plugin: ConfigPlugin<T>,
  name: string
): ConfigPlugin<T>;

Parameters:

  • plugin: The plugin function to wrap
  • name: Unique identifier for caching

Usage:

const withOnceOnlyFeature = createRunOncePlugin(
  (config) => {
    // Plugin logic here
    return config;
  },
  "withOnceOnlyFeature"
);

withRunOnce

Apply a plugin only once based on a cache key, with manual cache control.

function withRunOnce(
  config: ExpoConfig,
  options: { plugin: ConfigPlugin; name: string }
): ExpoConfig;

Parameters:

  • config: The Expo configuration object
  • options.plugin: The plugin function to apply
  • options.name: Cache key for run-once behavior

Error Handling

PluginError

Custom error class for plugin-related errors with enhanced debugging information.

class PluginError extends Error {
  constructor(message: string, cause?: string);
}

Usage:

if (invalidConfig) {
  throw new PluginError(
    "Invalid configuration detected",
    "The plugin requires a valid API key"
  );
}

Core Types

type ConfigPlugin<Props = void> = (config: ExpoConfig, props: Props) => ExpoConfig;

type StaticPlugin<T = any> = [string | ConfigPlugin<T>, T];

type PluginParameters<T extends ConfigPlugin<any>> = T extends (
  config: any,
  props: infer P
) => any
  ? P
  : never;

Usage Examples

Basic Plugin Creation

import { ConfigPlugin } from "@expo/config-plugins";

const withCustomSetup: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
  if (!apiKey) {
    throw new Error("API key is required");
  }
  
  // Apply modifications to config
  return config;
};

Complex Plugin Composition

import { withPlugins, createRunOncePlugin } from "@expo/config-plugins";

const withComplexFeature = createRunOncePlugin((config) => {
  return withPlugins(config, [
    withAndroidSetup,
    withiOSSetup,
    ["@expo/config-plugins", { feature: "enabled" }]
  ]);
}, "withComplexFeature");

Conditional Plugin Application

const withConditionalFeature: ConfigPlugin<{ enableFeature?: boolean }> = (
  config, 
  { enableFeature = false } = {}
) => {
  if (!enableFeature) {
    return config;
  }
  
  return withPlugins(config, [
    withFeatureSetup,
    withFeatureConfiguration
  ]);
};