Announcable Widget Dev

Architecture

The widget is a self-contained Lit web component application:

1. Entry (main.ts): Registers <announcable-widget> custom element
2. App (app.ts): Root LitElement that orchestrates data fetching and rendering
3. Components: Lit components for UI rendering
4. Controllers: Lit reactive controllers for reusable behavior (toggle, anchors)
5. Tasks: Lit Task pattern for async data fetching from the backend API
6. Lib: Shared utilities, types, and configuration

Build Output

Built as UMD bundle (widget.js) with CSS injected by JS (no separate CSS file). Embedded on customer websites via:

<script src="https://announcable.com/widget?id=ORG_ID"></script>

API Communication

The widget fetches data from the backend API at /api/:

Key Patterns

Base Component

All components extend BaseComponent from lib/base-component.ts which provides shared functionality.

Lit Context

Widget-wide state is shared via Lit contexts defined in lib/contexts.ts. The root app.ts provides context values consumed by child components.

Lit Task Pattern

Data fetching uses Lit's Task class for declarative async operations:

// tasks/release-notes.ts
export const releaseNotesTask = new Task(host, {
  task: async ([orgId]) => {
    const response = await fetch(`${config.backendUrl}/api/release-notes/${orgId}`);
    return response.json();
  },
  args: () => [host.orgId],
});

CSS Namespacing

All widget CSS is namespaced to .announcable-widget to avoid conflicts when embedded on customer websites. Use Shadow DOM encapsulation where possible.

Development Workflow

With Backend

# Terminal 1: Start backend dev services
cd backend && make dev-services

# Terminal 2: Start backend
cd backend && make dev-air

# Terminal 3: Start widget dev server
cd widget && npm run dev

Widget Only

npm run dev              # Dev server with hot-reload
npm run build            # Production UMD bundle
npm run build:test       # Dev/test build
npm run lint             # Lint check

Adding a New Component

1. Create component file in appropriate directory (components/ui/ or components/widget/)
2. Extend BaseComponent or LitElement
3. Use Lit decorators (@customElement, @property, @state)
4. Import and use in parent component

import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('my-component')
export class MyComponent extends LitElement {
  @property() label = '';

  static styles = css`
    :host { display: block; }
  `;

  render() {
    return html`<div>${this.label}</div>`;
  }
}

Adding a New API Task

1. Create task file in src/tasks/
2. Define the fetch logic using Lit Task pattern
3. Wire it into the component that needs the data
4. Handle loading, error, and success states

Completion Checklist

• npm run lint passes
• npm run build succeeds
• Widget renders correctly in browser
• No console errors
• CSS doesn't leak outside widget (Shadow DOM / namespacing)
• API calls work against running backend
• No any types introduced

Anti-Patterns