refactor to use tree shaking (#136)

Author: JannikStreek

docs/client-packages-react.md

@@ -4,15 +4,13 @@ This guide covers React-specific integration. For component properties and event
 
 ## Installation
 
-Ensure the GitHub package registry is configured (see [Registry Setup](./client-packages.md#registry-setup)), then install the React package:
+Ensure the GitHub package registry is configured (see [Registry Setup](./client-packages.md#registry-setup)), then install both packages:
 
 ```bash
-pnpm add @edufeed-org/oer-finder-plugin-react
+pnpm add @edufeed-org/oer-finder-plugin @edufeed-org/oer-finder-plugin-react
 ```
 
-The base plugin (`@edufeed-org/oer-finder-plugin`) is installed automatically as a dependency — you do not need to install it separately. All necessary imports (components, types, and adapter registration) are available directly from this React package.
-
-> **Important:** Do not install `@edufeed-org/oer-finder-plugin` as a direct dependency alongside the React package. Doing so can result in two separate copies on disk, each with its own adapter registry. Adapters registered via one copy would be invisible to components from the other, causing searches to silently return zero results. Always import from `@edufeed-org/oer-finder-plugin-react` instead.
+The base plugin is a peer dependency of the React package. Both packages must be installed — the React package provides the React component wrappers, while the base plugin provides the Web Components, adapter registry, and adapter entry points.
 
 ## Operating Modes
 
@@ -46,18 +44,19 @@ When `apiUrl` is **omitted**, adapters run directly in the browser. No backend s
 - You are prototyping or building a static site
 - You want full client-side control over adapter behavior
 
-You **must register adapters** before the component renders. Call the registration function once at your app's entry point:
+You **must register adapters** before the component renders. Call the registration function once at your app's entry point. Import adapter registration functions directly from `@edufeed-org/oer-finder-plugin`:
 
 ```typescript
 // Register all built-in adapters
-import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin-react/adapters';
+import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
 registerAllBuiltInAdapters();
 ```
 
 Or register only the adapters you need:
 
 ```typescript
-import { registerOpenverseAdapter, registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin-react/adapters';
+import { registerOpenverseAdapter } from '@edufeed-org/oer-finder-plugin/adapter/openverse';
+import { registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin/adapter/arasaac';
 registerOpenverseAdapter();
 registerArasaacAdapter();
 ```
@@ -186,7 +185,8 @@ The component code is identical to the [server-proxy example above](#server-prox
 **1. Register adapters once at your app entry point (e.g., `main.tsx`):**
 
 ```tsx
-import { registerOpenverseAdapter, registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin-react/adapters';
+import { registerOpenverseAdapter } from '@edufeed-org/oer-finder-plugin/adapter/openverse';
+import { registerArasaacAdapter } from '@edufeed-org/oer-finder-plugin/adapter/arasaac';
 registerOpenverseAdapter();
 registerArasaacAdapter();
 ```
@@ -303,22 +303,23 @@ The following built-in adapters are available for direct client mode:
 | `rpi-virtuell` | RPI-Virtuell Materialpool (GraphQL) | German educational resources |
 | `wikimedia` | Wikimedia Commons API | Images |
 
-Register all at once or selectively — all functions are available from a single import path:
+Register all at once or selectively — import adapter registration functions from `@edufeed-org/oer-finder-plugin`:
 
 ```typescript
 // All adapters
-import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin-react/adapters';
+import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
 registerAllBuiltInAdapters();
 
-// Or selectively
-import { registerOpenverseAdapter, registerWikimediaAdapter } from '@edufeed-org/oer-finder-plugin-react/adapters';
+// Or selectively (better for tree-shaking)
+import { registerOpenverseAdapter } from '@edufeed-org/oer-finder-plugin/adapter/openverse';
+import { registerWikimediaAdapter } from '@edufeed-org/oer-finder-plugin/adapter/wikimedia';
 registerOpenverseAdapter();
 registerWikimediaAdapter();
 ```
 
 ## Key Types
 
-All types are importable from `@edufeed-org/oer-finder-plugin-react`:
+React components and UI-related types are importable from `@edufeed-org/oer-finder-plugin-react`:
 
 ```typescript
 import {
@@ -344,19 +345,22 @@ import {
   type SearchParams,           // Search parameter structure
   type SourceOption,           // Source option type for UI display
 
-  // Adapter types
-  type AdapterFactory,         // Factory function type for custom adapters
-
   // Underlying web component types (for advanced use)
   type OerSearchElement,       // <oer-search> element class
   type OerListElement,         // <oer-list> element class
   type OerCardElement,         // <oer-card> element class
   type LoadMoreElement,        // <oer-load-more> element class
+} from '@edufeed-org/oer-finder-plugin-react';
+```
 
-  // Adapter registry API
+Adapter registry API and adapter types are imported from `@edufeed-org/oer-finder-plugin`:
+
+```typescript
+import {
   registerAdapter,             // Register a custom adapter factory
   getAdapterFactory,           // Retrieve a registered adapter factory by ID
-} from '@edufeed-org/oer-finder-plugin-react';
+  type AdapterFactory,         // Factory function type for custom adapters
+} from '@edufeed-org/oer-finder-plugin';
 ```
 
 ### State Typing

docs/client-packages.md

@@ -585,10 +585,10 @@ The `@edufeed-org/oer-finder-plugin-react` package provides React wrapper compon
 Ensure [Registry Setup](#registry-setup) is configured, then:
 
 ```bash
-pnpm add @edufeed-org/oer-finder-plugin-react
+pnpm add @edufeed-org/oer-finder-plugin @edufeed-org/oer-finder-plugin-react
 ```
 
-This package depends on `@edufeed-org/oer-finder-plugin` internally — you do not need to install the base plugin separately. All key types (`OerItem`, `OerMetadata`, `OerListResponse`, `SourceConfig`, `LoadMoreMeta`, `SupportedLanguage`) are re-exported from this package.
+Both packages must be installed — the base plugin is a peer dependency of the React package. Import React components from the React package, and adapter registration functions directly from the base plugin.
 
 For usage details, see the [React guide](./client-packages-react.md).
 

packages/oer-finder-plugin-react-example/AGENTS.md

@@ -28,7 +28,7 @@ pnpm --filter @edufeed-org/oer-finder-plugin-react-example type-check    # tsc -
 - **Dev server:** Vite with `@vitejs/plugin-react`
 - **Test:** No tests
 - **TypeScript:** ES2020, ESNext modules, `jsx: react-jsx`, DOM lib
-- **Dependencies:** `oer-finder-plugin-react` (workspace), `react`, `react-dom` (v19)
+- **Dependencies:** `oer-finder-plugin` (workspace), `oer-finder-plugin-react` (workspace), `react`, `react-dom` (v19)
 
 ## Conventions
 

packages/oer-finder-plugin-react-example/package.json

@@ -18,6 +18,7 @@
     "format": "echo 'Format not configured yet'"
   },
   "dependencies": {
+    "@edufeed-org/oer-finder-plugin": "workspace:*",
     "@edufeed-org/oer-finder-plugin-react": "workspace:*",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

packages/oer-finder-plugin-react-example/src/App.tsx

@@ -10,7 +10,7 @@ import { useState, useCallback } from 'react';
 import './styles.css';
 
 // Register all built-in adapters (required for direct-client mode)
-import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin-react/adapters';
+import { registerAllBuiltInAdapters } from '@edufeed-org/oer-finder-plugin/adapters';
 registerAllBuiltInAdapters();
 
 // Import React components from the plugin-react package

packages/oer-finder-plugin-react/AGENTS.md

@@ -6,14 +6,13 @@ React wrapper components for the OER Finder Plugin Web Components.
 
 - Uses `@lit/react`'s `createComponent()` to wrap all 4 web components as React components: `OerSearch`, `OerList`, `OerCard`, `OerLoadMore`
 - Maps custom event names to React prop callbacks (`onSearchResults`, `onCardClick`, `onLoadMore`, etc.)
-- Re-exports all relevant types and the adapter registry API (`registerAdapter`, `getAdapterFactory`) from `oer-finder-plugin`
-- Provides a separate `./adapters` entry point that re-exports `registerAllBuiltInAdapters` for tree-shakeable adapter registration
-- Peer dependency on React 18 or 19
+- Re-exports relevant UI types from `oer-finder-plugin`
+- Peer dependency on `@edufeed-org/oer-finder-plugin` and React 18 or 19
+- Adapter registration and adapter types are imported directly from `@edufeed-org/oer-finder-plugin` by consumers
 
 ## Key Files
 
-- `src/index.ts` — React component wrappers (via `@lit/react`), type re-exports, and adapter registry API
-- `src/adapters.ts` — Re-exports `registerAllBuiltInAdapters` from the plugin's `adapters` entry point
+- `src/index.ts` — React component wrappers (via `@lit/react`) and type re-exports
 
 ## Build
 
@@ -29,8 +28,8 @@ pnpm --filter @edufeed-org/oer-finder-plugin-react format        # Prettier
 - **Build:** Vite (ESM-only output) + tsc for declarations. Always rebuilds `oer-finder-plugin` first. CJS was dropped to avoid dual-registry issues — `oer-finder-plugin` is ESM-only, so a CJS build would create separate module instances
 - **Test:** No tests
 - **TypeScript:** ES2020, ESNext modules, bundler resolution, `jsx: react-jsx`, DOM lib
-- **Dependencies:** `oer-finder-plugin` (workspace). `@lit/react` is a dev dependency (bundled by Vite)
-- **Peer deps:** `react ^18.0.0 || ^19.0.0`
+- **Dependencies:** `@lit/react` is a dev dependency (bundled by Vite)
+- **Peer deps:** `@edufeed-org/oer-finder-plugin` (workspace), `react ^18.0.0 || ^19.0.0`
 
 ## Conventions
 

packages/oer-finder-plugin-react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edufeed-org/oer-finder-plugin-react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React components for OER Finder Plugin",
   "author": "B310 Digital GmbH",
   "license": "MIT",
@@ -16,10 +16,6 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./adapters": {
-      "types": "./dist/adapters.d.ts",
-      "import": "./dist/adapters.js"
     }
   },
   "files": [
@@ -32,10 +28,8 @@
     "lint": "eslint \"src/**/*.ts\" --fix",
     "format": "prettier --write \"src/**/*.ts\""
   },
-  "dependencies": {
-    "@edufeed-org/oer-finder-plugin": "workspace:*"
-  },
   "peerDependencies": {
+    "@edufeed-org/oer-finder-plugin": "workspace:*",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {

packages/oer-finder-plugin-react/src/adapters.ts

@@ -45,13 +45,6 @@ export type {
   SupportedLanguage,
   SourceConfig,
   LoadMoreMeta,
-  AdapterFactory,
-} from '@edufeed-org/oer-finder-plugin';
-
-// Re-export adapter registry API for React consumers
-export {
-  registerAdapter,
-  getAdapterFactory,
 } from '@edufeed-org/oer-finder-plugin';
 
 /**

packages/oer-finder-plugin-react/src/index.ts

@@ -8,7 +8,6 @@ export default defineConfig({
     lib: {
       entry: {
         index: resolve(__dirname, 'src/index.ts'),
-        adapters: resolve(__dirname, 'src/adapters.ts'),
       },
       formats: ['es'],
       fileName: (_format, entryName) => `${entryName}.js`,