@adnbn/plugin-remote-config

Remote configuration plugin for Addon Bone.

Features

• Fetch JSON configuration from a remote endpoint with transparent caching.
• Configurable cache time-to-live (TTL) in minutes.
• Fallback to default configuration on failure.
• Access configuration in background scripts, content scripts, or service workers.
• React hook for easy consumption in React apps.

Installation

npm:

npm install @adnbn/plugin-remote-config

pnpm:

pnpm add @adnbn/plugin-remote-config

yarn:

yarn add @adnbn/plugin-remote-config

Usage

Plugin Configuration

In your Addon Bone config (e.g., adnbn.config.ts), register the plugin:

import{defineConfig}from"adnbn";importremoteConfigfrom"@adnbn/plugin-remote-config";exportdefaultdefineConfig({plugins: [remoteConfig({url: "https://example.com/config.json",// or an env var namettl: 60,// cache TTL in minutes (default: 1440)config: {// default/fallback configfeatureFlag: false,apiEndpoint: "https://api.example.com",},}),],});

Accessing Configuration

In a content script, background, or any other extension layer

import{getRemoteConfig}from"@adnbn/plugin-remote-config/api";asyncfunctioninitialize(){try{constconfig=awaitgetRemoteConfig<{apiEndpoint: string;featureFlag: boolean}>();console.log("Remote config:",config);}catch(error){console.error("Failed to load remote config:",error);}}

In React

Use the useRemoteConfig hook directly inside your components:

import{useRemoteConfig}from"@adnbn/plugin-remote-config/hooks";functionFeatureComponent(){const{featureFlag, apiEndpoint}=useRemoteConfig();return(<div>{featureFlag ? <p>New feature enabled!</p> : <p>Feature disabled.</p>}<p>API Endpoint: {apiEndpoint}</p></div>);}

Options

The plugin accepts the following options:

• url?: string — Remote endpoint URL or an environment variable key resolving to a URL.
• ttl?: number — Cache time-to-live in minutes. Defaults to 1440 (1 day).
• config: RemoteConfig — Default configuration object used as fallback.

TypeScript Configuration

To enable proper TypeScript support and type safety for your configuration, you need to extend the RemoteConfig interface in your project.

Creating Type Definitions

Create a declaration file in your project (e.g., types/config.d.ts or config.d.ts) and extend the RemoteConfig interface:

import"@adnbn/plugin-remote-config";declare module "@adnbn/plugin-remote-config"{interfaceRemoteConfig{featureFlag: boolean;apiEndpoint: string;theme: "light"|"dark";maxRetries: number;endpoints: {auth: string;api: string;};}}

Benefits of Type Definitions

Once you've defined your configuration types, you'll get:

• IntelliSense support - Auto-completion for configuration properties
• Type checking - Compile-time validation of configuration usage
• Refactoring safety - Automatic updates when renaming properties

Usage with Types

After defining your types, you can use the configuration with full type safety:

// No need for generic type parameter anymoreconstconfig=awaitgetRemoteConfig();console.log(config.featureFlag);// ✅ TypeScript knows this is booleanconsole.log(config.apiEndpoint);// ✅ TypeScript knows this is stringconsole.log(config.theme);// ✅ TypeScript knows this is 'light' | 'dark'

// In React componentsfunctionMyComponent(){constconfig=useRemoteConfig();return(<divclassName={config.theme==="dark" ? "dark-theme" : "light-theme"}>{config.featureFlag&&<NewFeature/>}</div>);}

Configuration Validation

Make sure your default configuration in adnbn.config.ts matches your type definitions:

exportdefaultdefineConfig({plugins: [remoteConfig({url: "https://example.com/config.json",ttl: 60,config: {featureFlag: false,apiEndpoint: "https://api.example.com",theme: "light",maxRetries: 3,endpoints: {auth: "https://auth.example.com",api: "https://api.example.com",},}satisfiesRemoteConfig,// ✅ Type validation}),],});