mida-extension

MIDA Code Extension Pattern

Use this skill before modifying mida-extension. This is a Shopify Extension (Webpack + vanilla JS) that injects session recording, survey, GDPR consent, and heatmap tracking into merchant storefronts.

Read First

find mida-extension -maxdepth 4 -type f | grep -v node_modules | sort
git -C mida-extension status --short

Repo Shape

mida-extension/
├── extensions/
│   ├── theme-app-extension/
│   │   ├── blocks/
│   │   │   └── mida_recorder.liquid   # Theme block entry — injects scripts + global vars
│   │   ├── assets/                    # BUILD OUTPUT (.msr.js, .css) — generated by webpack
│   │   ├── locales/                   # i18n
│   │   └── shopify.extension.toml
│   └── web-pixel/
│       ├── src/index.js               # Web pixel entry (checkout events)
│       ├── dist/web-pixel.js          # Compiled
│       └── shopify.extension.toml
├── scripts/
│   ├── modules/
│   │   ├── recorder/
│   │   │   ├── index.js               # IIFE singleton
│   │   │   ├── load/                  # init.load.js, event.load.js, recorder.load.js, observer.load.js
│   │   │   ├── detect/                # usage.detect.js, mode.detect.js
│   │   │   ├── missing/               # Fallback handling
│   │   │   └── integration/fraud/
│   │   ├── survey/
│   │   │   ├── index.js               # IIFE singleton
│   │   │   └── _event.survey.js
│   │   ├── gdpr/
│   │   │   └── index.js               # IIFE singleton
│   │   └── screenshot/
│   │       └── index.js               # Class-based
│   ├── helpers/
│   │   ├── recorder.helper.js         # Encoding, event batching, ping URLs
│   │   ├── survey.helper.js           # HTML generation
│   │   ├── consent.helper.js          # Consent storage/checks
│   │   ├── session.helper.js          # Session management
│   │   ├── key.helper.js              # UUID/key generation
│   │   ├── event.helper.js            # Custom event dispatching
│   │   └── common.helper.js           # DOM utils, storage
│   ├── constants/
│   │   ├── host.constant.js           # API/ping server URLs
│   │   ├── recorder.constant.js       # Event types, selectors, MSR_* keys
│   │   ├── time.constant.js           # Timeouts (30m, 12h)
│   │   └── survey.constant.js         # Survey templates
│   ├── api-client/                    # API integrations
│   └── rrweb/                         # Customized rrweb fork
├── server/
│   └── index.js                       # Koa static server (port 2003, dev only)
├── webpack.config.js                  # Build config
├── package.json                       # Root scripts
└── pnpm-workspace.yaml                # Monorepo (extensions/web-pixel has own package.json)

Build System

Webpack entries → assets:

scripts/modules/recorder/index.js  →  extensions/theme-app-extension/assets/recorder.msr.js
scripts/modules/survey/index.js    →  extensions/theme-app-extension/assets/survey.msr.js
scripts/modules/gdpr/index.js      →  extensions/theme-app-extension/assets/gdpr.msr.js
scripts/modules/screenshot/index.js → extensions/theme-app-extension/assets/screenshot.msr.js

Build commands:

npm run build-msr    # Webpack: compile JS → assets/
npm run build-watch  # Webpack watch mode
npm run build        # Shopify CLI build
npm run dev          # Shopify CLI dev (watch + hot reload)
npm run deploy       # Deploy to Shopify
npm run start        # Koa static server on port 2003

Build output is committed to git — .msr.js files in assets/ are the deployed artifacts.

Theme Injection (Liquid)

extensions/theme-app-extension/blocks/mida_recorder.liquid is the entry point injected by Shopify into theme templates.

Conditional feature injection:

{% if app.metafields.module.srStatus == 'enable' %}
  {% unless content_for_header contains 'Shopify.designMode' %}
    <script src="{{ 'recorder.msr.js' | asset_url }}" defer="defer"></script>
  {% endunless %}
{% endif %}

Global variables passed to JS:

<script>
  window.msrPageTitle    = {{ page.title | json }};
  window.msrCart         = {{ cart | json }};
  window.msrCustomer     = {{ customer | json }};
  window.msrShopData     = { template: {{ request.page_type | json }}, url: {{ canonical_url | json }} };
  window.msrSetting      = {{ shop.metafields.mida.setting | json }};
  window.msrData         = { proxy: {{ shop.metafields.mida.proxy | json }} };
  window.msrQuota        = {{ shop.metafields.mida.quota | json }};
</script>

Pattern: Read window.msr* variables in JS modules — never make API calls to get shop config.

Module Pattern (IIFE Singleton)

// scripts/modules/recorder/index.js
const initialRecorder = (function() {
    const recordState = {
        block: false,
        events: [],
        sessionKey: null,
        visitorKey: null,
        eventCheck: {},
        // ...
    };

    const init = () => {
        // Read from window.msrShopData, window.msrSetting, etc.
        // Check consent
        // Start rrweb recording
    };

    const getState = () => ({ ...recordState });

    init();
    return { getState };
})();

window.msrRecordState = initialRecorder.getState();

Patterns:

• IIFE for encapsulation and single execution
• State stored in closure (mutable)
• getState() returns a copy via spread
• window.msr[Name]State exposes state globally
• recordState.block = true stops all further processing

Helper Export Pattern

// Named function exports (not default)
export const generateSessionKey = () => {
    return 'sess_' + Math.random().toString(36).substr(2, 9);
};

export const buildPingUrl = (proxy, params) => {
    const base = proxy === '2' ? MIDA_PING_URL_2 : MIDA_PING_URL;
    return `${base}/sessions/tracker?${new URLSearchParams(params).toString()}`;
};

Constant Naming

// constants/recorder.constant.js
export const MSR_SESSION_KEY = 'msr_session_key';
export const MSR_EVENT = {
    QUICK_CHECKOUT: 'msr_quick_checkout',
    ADD_TO_CART: 'msr_add_to_cart',
};

// constants/host.constant.js
export const MIDA_API_URL = process.env.MIDA_API_URL;
export const MIDA_PING_URL = process.env.MIDA_PING_URL;

All constants: MSR_ prefix. No magic strings in module code.

CSS Naming (BEM with .Mida- prefix)

.Mida-Survey--root         /* root container */
.Mida-Survey__Card         /* block element */
.Mida-Survey__Button--send /* modifier */
.Mida-GDPR--root           /* another module */

Z-index conventions:

• GDPR: z-index: 999999
• Survey: z-index: 99999999

Event Handling

// Use custom events for cross-module communication
import { MSR_EVENT } from '../constants/recorder.constant.js';

document.dispatchEvent(new Event(MSR_EVENT.ADD_TO_CART));

// Listen:
document.addEventListener(MSR_EVENT.ADD_TO_CART, () => { ... });

// Event bubbling for DOM interactions:
document.addEventListener('click', (event) => {
    if (event.target.matches('.checkout-button')) {
        // handle
    }
}, true);

// Prevent duplicate listeners:
if (!recordState.eventCheck['addToCart']) {
    document.addEventListener('click', handler);
    recordState.eventCheck['addToCart'] = true;
}

Data Sending Patterns

// Batch events in state.events array before sending
recordState.events.push({ type, timestamp, data });

// Send with keepalive on page unload
fetch(pingUrl, {
    method: 'POST',
    body: buildBody(JSON.stringify({ events: recordState.events })),
    keepalive: true,   // survives page navigation
});

// Split large payloads into 32KB chunks
const chunks = encodeSplit(JSON.stringify(bigPayload));
for (const chunk of chunks) await sendChunk(chunk);

Web Pixel Extension

extensions/web-pixel/src/index.js uses Shopify's web pixel API:

import { register } from '@shopify/web-pixels-extension';

register(({ analytics, browser, settings }) => {
    analytics.subscribe('product_viewed', (event) => {
        const { domain, proxy } = settings;  // From shopify.extension.toml schema
        // Track event
    });

    analytics.subscribe('checkout_started', (event) => { ... });
    analytics.subscribe('payment_info_submitted', (event) => { ... });
    analytics.subscribe('checkout_completed', (event) => { ... });
});

Settings (shopify.extension.toml): domain and proxy are passed from Shopify admin. Runtime: strict mode — limited browser APIs via browser SDK object.

rrweb Integration

// Import custom fork (not npm package)
import rrwebRecord from '../rrweb/record/index.js';

window.rrwebRecord = rrwebRecord;  // Expose globally

rrwebRecord({
    emit(event) {
        recordState.events.push(event);
    },
    blockClass: 'msr-block',
    ignoreClass: 'msr-ignore',
    sampling: { mousemove: 50 },
});

Webpack Config Notes

// webpack.config.js
export default {
    mode: 'production',
    target: ['web', 'es5'],        // Must transpile to ES5
    entry: { recorder: '...', survey: '...', gdpr: '...', screenshot: '...' },
    output: {
        filename: '[name].msr.js',
        path: resolve(__dirname, 'extensions/theme-app-extension/assets'),
    },
    plugins: [new Dotenv()],       // Injects MIDA_API_URL, MIDA_PING_URL, etc.
};

Environment variables injected by Dotenv plugin: MIDA_API_URL, MIDA_PING_URL, MIDA_HM_URL, MIDA_EXTERNAL_URL, and their _2 variants.

Code Quality

• ESLint: env: { browser: true, node: true, es2021: true }
• Prettier: 4-space indent, single quotes, trailing commas (es5), 120 char width
• Husky pre-commit: runs npm run lint && npm run format
• Register window.msr* globals in .eslintrc.cjs as readonly

Add New Module Checklist

1. Create scripts/modules/<name>/index.js with IIFE pattern
2. Expose state: window.msr<Name>State = initialModule.getState()
3. Add webpack entry in webpack.config.js
4. Create helpers: scripts/helpers/<name>.helper.js
5. Create constants: scripts/constants/<name>.constant.js
6. If needed, inject in liquid: add <script> tag in mida_recorder.liquid

Add New Tracking Event Checklist

1. Define constant: MSR_EVENT.NEW_EVENT = 'msr_new_event' in recorder.constant.js
2. Add listener in scripts/modules/recorder/load/event.load.js
3. Dispatch via: document.dispatchEvent(new Event(MSR_EVENT.NEW_EVENT))
4. Add handler in appropriate helper

Strict Rules

• Do not use React, Vue, or any UI framework in extension modules — vanilla JS only
• Do not make network requests in module initialization before consent check
• Do not modify .msr.js files in assets/ directly — they are build output
• Do not skip recordState.block check in event handlers
• Always check consent before starting recording: if (!checkConsentResult) return
• Always use keepalive: true for fetch calls during page unload
• Always prefix CSS classes with .Mida- to avoid theme conflicts
• Always use MSR_ prefix for constants — no magic strings in module code
• After modifying liquid or JS, run npm run build-msr before deploying

Verification

npm run build-msr       # Build and check for webpack errors
npm run lint            # ESLint check