https://github.com/addonbone/plugin-remote-config
Remote configuration plugin for Addon Bone that provides cached JSON config fetching with fallback support for browser extensions.
https://github.com/addonbone/plugin-remote-config
api browser chrome chrome-extension config edge firefox opera remote safari
Last synced: 10 months ago
JSON representation
Remote configuration plugin for Addon Bone that provides cached JSON config fetching with fallback support for browser extensions.
- Host: GitHub
- URL: https://github.com/addonbone/plugin-remote-config
- Owner: addonbone
- Created: 2025-06-11T21:04:15.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-14T16:50:45.000Z (10 months ago)
- Last Synced: 2025-08-14T18:33:21.721Z (10 months ago)
- Topics: api, browser, chrome, chrome-extension, config, edge, firefox, opera, remote, safari
- Language: TypeScript
- Homepage:
- Size: 388 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @adnbn/plugin-remote-config
[](https://www.npmjs.com/package/@adnbn/plugin-remote-config)
[](https://www.npmjs.com/package/@adnbn/plugin-remote-config)
Remote configuration plugin for [Addon Bone](https://github.com/addonbone).
## 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 context provider and hook for easy consumption in React apps.
## Installation
Using npm:
```bash
npm install @adnbn/plugin-remote-config
```
Using Yarn:
```bash
yarn add @adnbn/plugin-remote-config
```
## Usage
### Plugin Configuration
In your Addon Bone config (e.g., `adnbn.config.ts`), register the plugin:
```ts
import {defineConfig} from "adnbn";
import remoteConfig from "@adnbn/plugin-remote-config";
export default defineConfig({
plugins: [
remoteConfig({
url: "https://example.com/config.json", // or an env var name
ttl: 60, // cache TTL in minutes (default: 1440)
config: {
// default/fallback config
featureFlag: false,
apiEndpoint: "https://api.example.com",
},
}),
],
});
```
### Accessing Configuration
#### In a content script, background, or any other extension layer
```ts
import {getRemoteConfig} from "@adnbn/plugin-remote-config/api";
async function initialize() {
try {
const config = await getRemoteConfig<{apiEndpoint: string; featureFlag: boolean}>();
console.log("Remote config:", config);
} catch (error) {
console.error("Failed to load remote config:", error);
}
}
```
#### In React
Wrap your application with the `RemoteConfigProvider`, then use the `useRemoteConfig` hook:
```tsx
import React, {FC} from "react";
import ReactDOM from "react-dom";
import {RemoteConfigProvider} from "@adnbn/plugin-remote-config/react";
import App from "./App";
const Popup: FC = () => {
return (
);
};
export default Popup;
```
```tsx
import {useRemoteConfig} from "@adnbn/plugin-remote-config/react";
function FeatureComponent() {
const {featureFlag, apiEndpoint} = useRemoteConfig();
return (
{featureFlag ? New feature enabled!
: Feature disabled.
}
API Endpoint: {apiEndpoint}
);
}
```
## 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:
```typescript
import "@adnbn/plugin-remote-config";
declare module "@adnbn/plugin-remote-config" {
interface RemoteConfig {
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:
```typescript
// No need for generic type parameter anymore
const config = await getRemoteConfig();
console.log(config.featureFlag); // ✅ TypeScript knows this is boolean
console.log(config.apiEndpoint); // ✅ TypeScript knows this is string
console.log(config.theme); // ✅ TypeScript knows this is 'light' | 'dark'
```
```tsx
// In React components
function MyComponent() {
const config = useRemoteConfig();
return (
{config.featureFlag && }
);
}
```
### Configuration Validation
Make sure your default configuration in `adnbn.config.ts` matches your type definitions:
```typescript
export default defineConfig({
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",
},
} satisfies RemoteConfig, // ✅ Type validation
}),
],
});
```
## License
MIT © Addon Bone