Choosing Modules

rex-starter includes rex-core, rex-history, rex-lists, and rex-local-download. That covers the common case of a study that records browsing history and stores data locally. If your study needs something different (more data types, a server backend, AI chatbot collection), you add the appropriate modules.

---

What do you need to collect?

I want to collect…	Module(s) to include
Which sites participants visit (URLs and timestamps)	rex-history + rex-lists
How participants got from page to page, including redirects and new tabs	rex-visit-graph (with rex-history)
Time spent on pages, tab and window focus events	rex-page-events
Search engine results pages participants see	rex-search-mirror
ChatGPT conversation history	rex-spider + rex-spider-chatgpt
Gemini conversation history	rex-spider + rex-spider-gemini
Google Search AI Mode history	rex-spider + rex-spider-google-ai
Perplexity conversation history	rex-spider + rex-spider-perplexity
Live AI chatbot Q&A as it happens	rex-live-mirror
News homepage headlines and discovery feeds	rex-live-mirror
Titles, bylines, and excerpts of pages on allow-listed sites	rex-live-mirror
Store data locally with a download button	rex-local-download
Send data to a server automatically	rex-passive-data-kit
Let participants view and edit their lists	rex-lists-front-end
Let participants review and delete their history before sharing	rex-history-data-table (with rex-history + rex-local-download)
Detect participants’ default search engine	rex-browser-settings
Sanitize sensitive data before storage	rex-content-processing
Block, redirect, or change pages (experimental)	rex-page-manipulation
Change HTTP request headers	rex-headers
Replace the new tab page	rex-default-page
Move participants through study phases or assign conditions	rex-autorunner

Note on rex-lists: rex-lists is required by rex-history. If you include rex-history, you must also include rex-lists.

For a plain-language description of what each module collects and its limitations, see Module Overview.

---

How to add a module

1. Add it to package.json

Open package.json and add the module to the dependencies section:

"dependencies": {
  "@bric/rex-core": "github:bric-digital/rex-core#main",
  "@bric/rex-module-name": "github:bric-digital/rex-module-name#main"
}

Replace rex-module-name with the actual module name, such as rex-page-events or rex-search-mirror.

2. Install it

npm install

3. Import it in each part of the extension it runs in

A module registers itself when it is imported. Each module provides an entry point for each part of the extension it runs in; the exports section of its package.json lists them.

Entry point	Import it in	Runs in
@bric/rex-module-name/service-worker	src/typescript/service-worker.ts	The background service worker
@bric/rex-module-name/browser	src/typescript/browser.ts	Web pages, as a content script
@bric/rex-module-name/extension	src/typescript/extension.ts	The extension’s own pages

For example, rex-page-events has service worker and browser entry points:

src/typescript/service-worker.ts

import pageEventsPlugin from '@bric/rex-page-events/service-worker'

// src/typescript/browser.ts
import pageEventsBrowserPlugin from '@bric/rex-page-events/browser'

4. Add config

Most modules require a section in src/extension/config.json to be enabled. At minimum:

"page_events": {
  "enabled": true
}

The module map lists the config key each module reads.

5. Rebuild

npm run build

---

How to remove a module

1. Remove the "@bric/rex-module-name" entry from package.json dependencies.
2. Remove the module’s imports from src/typescript/service-worker.ts, browser.ts, and extension.ts.
3. Remove the module’s config section from src/extension/config.json.
4. Run npm install to update node_modules, then npm run build.

---

Choosing between rex-local-download and rex-passive-data-kit

These two modules handle data storage and transmission differently, and most studies use one or the other (not both).

rex-local-download stores data inside the extension on the participant’s device. Participants download the data as a JSON file and send it to you. This is simple to set up and requires no server, but depends on participants completing the download step. Good for pilots and small studies.

rex-passive-data-kit sends data to a PDK server automatically as participants browse. No action required from participants. Data is safe on the server even if a participant loses their device or uninstalls the extension. Required for any study at scale. Requires a running PDK server; see Local Backend for local setup and Deploy for production.