HelpDock

A drop-in help desk widget. Bring your own backend.

HelpDock is a lightweight, self-hosted help desk widget built as a TypeScript library. It provides an embeddable knowledge base and contact form that sits in the corner of any web page. Uses native Web Components with no React/Vue/Angular dependencies.

Features

• Knowledge Base: Searchable articles with categories and tags
• Contact Form: Configurable support ticket submission with file attachments
• Mobile Responsive: Adapts to desktop floating panel or mobile full-screen overlay
• Self-Hosted: Bring your own backend and datastore
• TypeScript Support: Full type definitions included
• Analytics: Track user interactions and events

Installation

npm install helpdock

Quick Start

import { HelpDock, type AnalyticsEvent } from 'helpdock';

HelpDock.init({
  articles: {
    fetch: async () => ({
      articles: [
        {
          id: "getting-started",
          title: "Getting Started",
          description: "Learn how to use HelpDock and integrate it into your application",
          content: "# Getting Started\n\nWelcome to HelpDock!",
          contentType: "markdown",
          category: "Guide",
          tags: ["introduction", "setup"],
        },
        {
          id: "api-reference",
          title: "API Reference",
          description: "Complete API documentation for HelpDock configuration options",
          content: "# API Reference\n\n## Configuration Options\n\n...",
          contentType: "markdown",
          category: "Documentation",
          tags: ["api", "reference"],
        },
      ],
      hasMore: false, // set to true + provide nextCursor for pagination
    }),
  },

  contact: {
    title: "How can we help?",
    subtitle: "We usually respond in a few hours",
    fields: [
      {
        type: "text",
        name: "name",
        label: "Name",
        required: true,
        placeholder: "Enter your name",
      },
      {
        type: "email",
        name: "email",
        label: "Email",
        required: true,
        placeholder: "[email protected]",
      },
      {
        type: "select",
        name: "topic",
        label: "Topic",
        required: true,
        options: [
          { value: "bug", label: "Bug Report" },
          { value: "feature", label: "Feature Request" },
          { value: "question", label: "Question" },
          { value: "other", label: "Other" },
        ],
      },
      {
        type: "textarea",
        name: "message",
        label: "Message",
        required: true,
        placeholder: "How can we help you?",
        rows: 5,
      },
    ],

    attachments: {
      mode: "inline",
      maxFiles: 3,
      maxSizeMB: 5,
      accept: "image/*,.pdf,.doc,.docx",
    },

    submit: {
      type: "function",
      handler: async ({ fields, attachments }) => {
        // Send to your backend
        const response = await fetch('/api/contact', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ fields, attachments }),
        });

        if (!response.ok) {
          return {
            success: false,
            message: "Failed to send message. Please try again.",
          };
        }

        return {
          success: true,
          message: "Thank you for contacting us!",
        };
      },
    },
    submitButtonText: "Send message",
  },

  // Search defaults to "clientside" (filters loaded articles in the browser).
  // Use "custom" for server-side search:
  // search: {
  //   type: "custom",
  //   debounceMs: 150, // optional, defaults to 150ms
  //   search: async (query, params) => {
  //     const res = await fetch(`/api/search?q=${query}&cursor=${params?.cursor ?? ""}`, {
  //       signal: params?.signal, // optional, lets HelpDock abort superseded requests
  //     });
  //     return res.json(); // { articles, hasMore, nextCursor }
  //   },
  // },

  analytics: {
    enabled: true,
    onEvent: (event: AnalyticsEvent) => {
      console.log("[HelpDock Analytics]", event.type, event);
    },
  },

  closeOnEscape: true,
});

Script Tag Usage

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App</title>

  <!-- Configure HelpDock before loading the script -->
  <script>
    window.HelpDockConfig = {
      articles: {
        fetch: async () => ({
          articles: [
            {
              id: "getting-started",
              title: "Getting Started",
              description: "Learn how to use HelpDock",
              content: "# Getting Started\n\nWelcome to HelpDock!",
              contentType: "markdown",
              category: "Guide",
              tags: ["introduction", "setup"],
            },
          ],
          hasMore: false,
        }),
      },

      contact: {
        title: "Need help?",
        subtitle: "We're here to assist",
        fields: [
          { type: "text", name: "name", label: "Name", required: true },
          { type: "email", name: "email", label: "Email", required: true },
          {
            type: "textarea",
            name: "message",
            label: "Message",
            required: true,
            rows: 4,
          },
        ],

        submit: {
          type: "function",
          handler: async ({ fields }) => {
            console.log("Contact form submitted:", fields);
            return { success: true, message: "Thank you!" };
          },
        },
      },

      closeOnEscape: true,
    };
  </script>

  <!-- Load HelpDock -->
  <script src="https://unpkg.com/helpdock/dist/helpdock.umd.js"></script>
</head>
<body>
  <h1>My Application</h1>
  <!-- HelpDock will automatically initialize with window.HelpDockConfig -->
</body>
</html>

License

MIT