helpdock
v0.1.3
Published
*A drop-in help desk widget. Bring your own backend.*
Readme
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 helpdockQuick Start
import { HelpDock, type AnalyticsEvent } from 'helpdock';
HelpDock.init({
articles: {
type: "function",
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! This guide will help you get up and running quickly.\n\n## Installation\n\n```bash\nnpm install helpdock\n```\n\n## Basic Setup\n\nImport and initialize the widget with your configuration.",
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- `position`: Widget position ('topLeft', 'topRight', 'bottomLeft', 'bottomRight')\n- `closeOnEscape`: Close widget when Escape key is pressed\n- `analytics`: Track user interactions",
contentType: "markdown",
category: "Documentation",
tags: ["api", "reference"],
},
],
}),
},
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",
},
analytics: {
enabled: true,
onEvent: (event: AnalyticsEvent) => {
console.log("[HelpDock Analytics]", event.type, event);
// Send to your analytics service
// analytics.track(event.type, event);
},
},
closeOnEscape: true,
position: "bottomRight",
});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: {
type: "function",
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! This guide will help you get up and running quickly.\n\n## Installation\n\nInclude the script tag and configure the widget.",
contentType: "markdown",
category: "Guide",
tags: ["introduction", "setup"],
},
{
id: "troubleshooting",
title: "Troubleshooting",
description: "Common issues and how to resolve them",
content: "# Troubleshooting\n\n## Common Issues\n\n- **Widget not appearing**: Check that the script loaded successfully\n- **Articles not loading**: Verify your article data format\n- **Contact form errors**: Check your submit handler",
contentType: "markdown",
category: "Support",
tags: ["troubleshooting", "support"],
},
],
}),
},
contact: {
title: "Need help?",
subtitle: "We're here to assist",
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: "textarea",
name: "message",
label: "Message",
required: true,
placeholder: "How can we help you?",
rows: 4,
},
],
submit: {
type: "function",
handler: async ({ fields }) => {
// Simulate API call
await new Promise(resolve => setTimeout(resolve, 1000));
console.log("Contact form submitted:", fields);
return {
success: true,
message: "Thank you for your message!",
};
},
},
},
closeOnEscape: true,
position: "bottomRight",
};
</script>
<!-- Load HelpDock -->
<script src="https://unpkg.com/helpdock/dist/helpdock.umd.js"></script>
</head>
<body>
<!-- Your app content -->
<h1>My Application</h1>
<!-- HelpDock will automatically initialize with the window.HelpDockConfig -->
</body>
</html>License
MIT