@makethisbetter/js

The Make This Better Widget SDK — embed user feedback collection in any website.

One script. Click any element. Describe the issue. Done.

Quickstart

Script tag (IIFE)

<script src="https://unpkg.com/@makethisbetter/js/dist/makethisbetter.iife.js"></script>
<script>
  MakeThisBetter.init({ projectKey: 'mtb_proj_YOUR_KEY' });
</script>

npm / ESM

npm install @makethisbetter/js

import { MakeThisBetter } from '@makethisbetter/js';

MakeThisBetter.init({ projectKey: 'mtb_proj_YOUR_KEY' });

Configuration

MakeThisBetter.init({
  projectKey: 'mtb_proj_xxx',    // required — your project API key
  locale: 'zh-CN',               // optional — 'en' (default) or 'zh-CN'
  position: 'right',             // optional — 'right' (default) or 'left'
  theme: 'auto',                 // optional — 'light' | 'dark' | 'auto'
  apiUrl: 'https://...',         // optional — custom API endpoint
  user: {
    id: 'usr_123',               // optional — identify the user
    email: '[email protected]',
    name: 'Alex Chen',
  },
});

How it works

1. A green Feedback tab appears on the right edge of the page
2. Clicking the tab enters Mark up mode — a toolbar appears at the top
3. Hover over any element to highlight it (blue outline + tooltip)
4. Click to place a pin annotation
5. Or drag to draw a free-form highlight
6. A Comment popup appears — describe the issue and hit Submit
7. The SDK captures a screenshot, collects page context (URL, browser, OS, console errors), and sends everything to the Make This Better API
8. Your dashboard shows the structured feedback with AI triage

What gets collected automatically

• Page URL
• Browser and OS
• Screen resolution
• Console errors (captured via window.onerror)
• Target element CSS selector and text content
• Page screenshot (via html-to-image, invisible to the user)
• Annotation coordinates

Conditional loading

The Widget only loads when you call MakeThisBetter.init(). Control who sees it with your own logic:

// Only show to admins
if (currentUser.isAdmin) {
  MakeThisBetter.init({ projectKey: 'mtb_proj_xxx', user: { id: currentUser.id } });
}

# Rails example
<% if current_user&.admin? %>
  <script>
    MakeThisBetter.init({
      projectKey: '<%= Rails.application.credentials.mtb_project_key %>',
      user: { id: '<%= current_user.id %>', email: '<%= current_user.email %>' }
    });
  </script>
<% end %>

Development

npm install
npm run build        # build dist/
open demo/index.html # run the standalone demo
npm run dev          # optional: serve demo at localhost:5173
npm test             # run tests
npm run type-check   # TypeScript check

Bundle size

| Format | Size | gzip | |--------|--------|--------| | IIFE | 42 KB | 13.6 KB | | ESM | 50 KB | 14.7 KB |

License

Business Source License 1.1 — free for non-competitive use, converts to MIT on 2029-01-01.

Free to self-host. Cloud platform at makethisbetter.dev.