Component Loader API Reference

Complete reference for the Patchwork component loader.

Installation

CDN (Recommended)

<script src="https://api.patchwork.run/tapestry/loader.js"></script>

Custom Element

Attributes

Example

<tapestry-component
  component-id="abc-123"
  version="published"
  user-name="John Doe"
  user-email="john@example.com"
>
</tapestry-component>

Template Variables via Attributes

Any HTML attributes you add to the tapestry-component element (except the reserved ones: component-id, version, api-url) are automatically passed as template variables to your component.

Example:

If your component HTML uses Handlebars:

<div class="greeting">
  <h1>Hello, {{userName}}!</h1>
  <p>Email: {{userEmail}}</p>
</div>

You can pass values via HTML attributes:

<tapestry-component
  component-id="greeting-component"
  user-name="Alice"
  user-email="alice@example.com"
>
</tapestry-component>

Note: Attribute names are converted to camelCase for Handlebars (e.g., user-name becomes userName). This happens automatically by the HTML attribute parsing.

JavaScript API

Component Methods

reload()

Reload the component from the server.

const component = document.querySelector("tapestry-component");
component.reload();

getAnalytics()

Get access to the component’s analytics instance.

const component = document.querySelector("tapestry-component");
const analytics = component.getAnalytics();
 
// Send custom event
analytics.sendEvent("button_click", {
  button_id: "signup",
  location: "header",
});
 
// Track form submission
await analytics.submitData({
  email: "user@example.com",
  name: "John Doe",
});

Analytics API

The analytics instance provides methods for tracking user interactions.

See the Analytics API Reference for complete documentation.

Quick Example

const analytics = component.getAnalytics();
 
// Track custom events
analytics.sendEvent("product_view", {
  productId: "123",
  category: "electronics",
  price: 99.99,
});
 
// Track form submissions
await analytics.submitData({
  email: "user@example.com",
  plan: "pro",
  source: "landing_page",
});

Component JavaScript API

Inside your component’s JavaScript code, access the tapestry object passed to the mount function:

export async function mount(tapestry, shadowRoot) {
  // Send events using the tapestry object
  tapestry.sendEvent("component_mounted", {
    timestamp: Date.now(),
  });
 
  // Track user interactions
  shadowRoot.querySelector("button").addEventListener("click", () => {
    tapestry.sendEvent("button_click", {
      button_id: "signup",
    });
  });
 
  // Track form submissions
  shadowRoot.querySelector("form").addEventListener("submit", async (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);
    await tapestry.submitData(Object.fromEntries(formData));
  });
}
 
export async function unmount(shadowRoot) {
  // Cleanup code here
}

Configuration

Configure the loader globally using window.TAPESTRY_CONFIG:

<script>
  window.TAPESTRY_CONFIG = {
    apiBaseUrl: "https://api.patchwork.run",
    debug: true,
    retryAttempts: 3,
    timeout: 10000,
  };
</script>
<script src="https://api.patchwork.run/tapestry/loader.js"></script>

Configuration Options

Shadow DOM

Components render in Shadow DOM with these characteristics:

• ✅ Style Isolation - Component CSS won’t affect page, page CSS won’t affect component
• ✅ DOM Encapsulation - Component DOM is isolated
• ✅ JavaScript Access - Component JavaScript can access the tapestry API
• ⚠️ Font Inheritance - Inherits fonts from page (can be overridden)

Browser Support

• ✅ Chrome 53+ (July 2016)
• ✅ Firefox 63+ (October 2018)
• ✅ Safari 10.1+ (March 2017)
• ✅ Edge 79+ (January 2020)

Coverage: ~98% of global users

Error Handling

When components fail to load, an error message is displayed in the component container. Enable debug mode for detailed error information:

<script>
  window.TAPESTRY_CONFIG = { debug: true };
</script>

Error types:

• NETWORK_ERROR - Failed to fetch component
• PARSE_ERROR - Invalid response data
• RENDER_ERROR - Failed to render
• TIMEOUT_ERROR - Request timed out
• INVALID_COMPONENT - Component not found or invalid ID

Performance

• Bundle size: ~7.5 KB gzipped
• Initial load: 100-200ms
• Cached load: <50ms

Best Practices

1. Load the script once per page
2. Use version="published" for production (enables caching)
3. Keep template variable data simple and small

Support

• 📖 Read the guides
• 💬 Contact support