EIP-6963 Multi-Injected Provider Discovery Utilities

Common errors

• Property 'detail' does not exist on type 'Event'. Property 'detail' does not exist on type 'CustomEvent<any>'.

  cause Attempting to access `event.detail` from an `eip6963:announceProvider` event without `mipd/window` global type augmentation.
  fix Add `import 'mipd/window';` to your application's entry file to ensure TypeScript recognizes the `EIP6963AnnounceProviderEvent` type for `CustomEvent` dispatched on `window`.

• TypeError: createStore is not a function (in CommonJS environments)

  cause `mipd` is an ESM-first package, and direct `require('mipd')` might not correctly resolve the `createStore` named export in some CommonJS environments without proper transpilation or explicit pathing.
  fix For projects that need to use CommonJS `require`, ensure your build tool correctly handles ESM imports from `node_modules`. Alternatively, if applicable, consider migrating to ESM or using dynamic `import('mipd')` within an `async` context.

• TS2345: Argument of type '(providers: EIP6963ProviderDetail[]) => void' is not assignable to parameter of type 'Listener<EIP6963ProviderDetail[]>'.

  cause Type incompatibility with `mipdStore.subscribe` listener function, often due to an outdated or incorrect `typescript` version, or incorrect type imports.
  fix Verify that your project's `typescript` version meets the `mipd` peer dependency (`>=5.0.4`). Ensure `EIP6963ProviderDetail` is imported as a type (`import type { EIP6963ProviderDetail } from 'mipd';`). Review the `mipd` source or documentation for the exact `Listener` type signature.

Warnings

• breaking As a 0.0.x version package, `mipd` is in early development. Minor and patch releases may introduce breaking changes without adhering to strict semantic versioning, particularly as the EIP-6963 standard itself evolves or as it integrates more deeply with other `wevm` libraries.
  Fix: Refer to the `mipd` GitHub repository for changelogs and migration guides for each new release. Pin exact versions (`"mipd": "0.0.7"`) to avoid unexpected updates.
• gotcha When using `mipd` with TypeScript, ensure you import the global window types via `import 'mipd/window';`. Without this side-effect import, TypeScript may not correctly infer the types for `window.addEventListener` when listening for `eip6963:announceProvider` events, leading to type errors.
  Fix: Add `import 'mipd/window';` at the top-level of your application's entry file (e.g., `main.ts` or `App.tsx`) to globally augment the `Window` interface with the necessary EIP-6963 event types.
• gotcha `mipd` primarily targets modern JavaScript environments and uses ES Modules (ESM). While it provides CommonJS (CJS) bundles, direct `require()` statements might behave differently or require specific bundler configurations, especially in older Node.js environments or complex build setups.
  Fix: Prefer `import` statements for `mipd`. If working in a CJS-only environment, ensure your bundler (e.g., Webpack, Rollup) is configured to correctly handle ESM imports, or explicitly target the CJS bundle if available (e.g., `require('mipd/dist/cjs/index.js')`).
• gotcha The `typescript` peer dependency, listed as `>=5.0.4`, is marked as optional in `mipd`'s `package.json`. While it's not strictly required at runtime, developing with `mipd` without a compatible TypeScript version can lead to compilation errors or incorrect type inferences in your project.
  Fix: Ensure your project explicitly installs a `typescript` version compatible with `mipd` (e.g., `npm install typescript@^5.0.4`). If using a lower version, you might encounter type-related issues.

Install

• npm install mipd npm
• yarn add mipd yarn
• pnpm add mipd pnpm

Imports

• createStore
  wrong:

  const { createStore } = require('mipd');

  correct:

  import { createStore } from 'mipd';

  The primary entry point for creating an EIP-6963 provider store. mipd is an ESM-first library; CommonJS `require` might require bundler configuration or specific import paths (e.g., `mipd/dist/cjs`).
• EIP6963ProviderDetail
  wrong:

  import { EIP6963ProviderDetail } from 'mipd';

  correct:

  import type { EIP6963ProviderDetail } from 'mipd';

  This is a TypeScript type definition. While importing as a value might work in some transpilers, using `import type` is the correct and tree-shakeable way to import types. It defines the structure of announced wallet providers.
• EIP6963AnnounceProviderEvent
  wrong:

  import { EIP6963AnnounceProviderEvent } from 'mipd';

  correct:

  import type { EIP6963AnnounceProviderEvent } from 'mipd';

  This is a TypeScript type definition for the custom DOM event dispatched by EIP-6963 compliant wallets. Use `import type` for proper type-only imports.
• Global Window Types

  import 'mipd/window';

  This is a side-effect import that augments the global `Window` interface with EIP-6963 event types, allowing TypeScript to correctly infer types for `window.addEventListener` for `eip6963:announceProvider` and `eip6963:requestProvider` events. It should be imported early in your application's entry file.

Quickstart

Demonstrates how to initialize the EIP-6963 store, subscribe to provider announcements, retrieve current providers, and includes a conceptual React example using `useSyncExternalStore`.

import { createStore } from 'mipd';
import type { EIP6963ProviderDetail } from 'mipd';
import 'mipd/window'; // Import to augment window types for EIP-6963 events

// Create a new EIP-6963 provider store
const mipdStore = createStore();

// Subscribe to provider changes (e.g., when a wallet announces itself or is removed)
const unsubscribe = mipdStore.subscribe((providers: EIP6963ProviderDetail[]) => {
  console.log('EIP-6963 Providers updated:', providers);
  if (providers.length > 0) {
    console.log('First provider UUID:', providers[0].info.uuid);
    console.log('First provider Name:', providers[0].info.name);
    // You can now use providers[0].provider for interactions if needed
  }
});

// Get current providers immediately
const initialProviders = mipdStore.getProviders();
console.log('Initial EIP-6963 Providers:', initialProviders);

// Example of how you might stop listening after some time (in a real app, this would be on unmount)
setTimeout(() => {
  unsubscribe();
  console.log('Unsubscribed from mipd store updates.');
}, 10000);

// In a React component (using React 18+ useSyncExternalStore):
// import { useSyncExternalStore } from 'react';
// import { createStore } from 'mipd';

// const store = createStore();

// function MyWalletConnector() {
//   const providers = useSyncExternalStore(store.subscribe, store.getProviders);
//   return (
//     <div>
//       <h2>Detected EIP-6963 Wallets:</h2>
//       {providers.length === 0 ? (
//         <p>No EIP-6963 wallets found.</p>
//       ) : (
//         <ul>
//           {providers.map((providerDetail) => (
//             <li key={providerDetail.info.uuid}>
//               <img src={providerDetail.info.icon} alt={providerDetail.info.name} width="24" height="24" />
//               {providerDetail.info.name} ({providerDetail.info.rdns})
//             </li>
//           ))}
//         </ul>
//       )}
//     </div>
//   );
// }