typed-config-plugins

Type Safety for Your Expo Config Plugins.

Expo config plugins are incredibly powerful, but their configuration lacks the safety net of type checking. typed-config-plugins bridges this gap, bringing the full power of TypeScript to your Expo project's configuration.

✨ Features

• Enhanced Developer Experience: Get autocomplete and type validation directly in your app.config.ts files, making plugin configuration less error-prone and more efficient.
• Pre-built Types: Includes ready-to-use TypeScript definitions for many popular Expo config plugins, generated by analyzing their source code.
• Extensible: Easily add custom types for your own or third-party plugins using TypeScript module augmentation.
• Seamless Integration: Designed to work smoothly with your existing app.config.ts setup. Note: JSON config files are not supported.

📦 Installation

npm i typed-config-plugins

🚀 Usage

Update your app.config.ts file to use the plugin helper from typed-config-plugins.

import { type ConfigContext, type ExpoConfig } from "expo/config";
import { plugin } from "typed-config-plugins";

export default ({ config }: ConfigContext): ExpoConfig => ({
    ...config,
    // ... other config
    plugins: [
        // typed syntax by this package (with type checking/autocompletion):
        plugin("expo-build-properties", { android: { minSdkVersion: 26 } }),
        
        // normal syntax (no type checking/autocompletion):
        ["expo-build-properties", { android: { minSdkVersion: 26 } }],
    ],
});

🤝 Adding Custom Plugin Types

To extend typed-config-plugins with types for your own plugins or plugins not yet covered, you can use TypeScript's module augmentation feature.

Create a new declaration file (e.g., config-plugins.d.ts) in your project's root or src directory with the following content:

// config-plugins.d.ts
import "typed-config-plugins"; // Import the original type declarations

declare module "typed-config-plugins" {
    // Extend the `ThirdPartyPlugins` interface with your custom plugin types
    interface ThirdPartyPlugins {
        // Define options for "demo-package" (as used in the example)
        "demo-package": { bar: string, baz?: number };
        // more packages here...
    }
}

Now, when you use plugin("my-custom-plugin", { /* ... */ }) in your app.config.ts, TypeScript will provide autocompletion and validate the options against the types you've defined.

Releases

This repo uses Changesets.

1. For any user-facing package change, run bun run changeset and commit the generated file in .changeset/.
2. When changesets reach main, GitHub Actions opens or updates a release PR with the version bump and generated changelog.
3. Merge that release PR to publish to npm.