Widget Setup

This guide walks you through installing the EpicContext Widget in your web application and configuring it for your team.

Prerequisites

• An EpicContext project with an API key (generate one in Settings > General)
• A web application where you want to embed the widget

Installation

Add the widget script to your HTML, just before the closing </body> tag:

<script src="https://your-epicontext-instance.com/widget.js"></script>
<script>
  EpicContext.init({
    projectId: 'your-project-id',
    apiKey: 'your-api-key'
  });
</script>

The widget loads asynchronously and won't block your page rendering.

Configuration Options

EpicContext.init({
  // Required
  projectId: 'your-project-id',

  // Authentication (choose one)
  apiKey: 'your-api-key',          // Direct mode (development only)
  proxyUrl: '/api/epicontext',      // Proxy mode (production)

  // Optional
  theme: 'light',                   // 'light' or 'dark'
  position: 'bottom-right',         // Widget button position
  delay: 300,                       // Hover delay in ms
});

Proxy Mode Setup

In production, use a server-side proxy to keep your API key secure.

Next.js Example

Create an API route that forwards requests to EpicContext:

// app/api/epicontext/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const url = new URL(request.url);
  const blockKey = url.searchParams.get('block');

  const response = await fetch(
    `https://epiccontext.com/api/v1/projects/${process.env.EPICONTEXT_PROJECT_ID}/blocks/${blockKey}`,
    {
      headers: {
        'X-API-Key': process.env.EPICONTEXT_API_KEY!,
      },
    }
  );

  return NextResponse.json(await response.json());
}

Then initialize the widget with proxyUrl instead of apiKey:

EpicContext.init({
  projectId: 'your-project-id',
  proxyUrl: '/api/epicontext'
});

Express Example

app.get('/api/epicontext', async (req, res) => {
  const { block } = req.query;
  const response = await fetch(
    `https://epiccontext.com/api/v1/projects/${process.env.EPICONTEXT_PROJECT_ID}/blocks/${block}`,
    {
      headers: { 'X-API-Key': process.env.EPICONTEXT_API_KEY },
    }
  );
  res.json(await response.json());
});

Adding Context References

Attach product context to parts of your application using data-epicontext attributes:

<section data-epicontext="checkout-flow-feature">
  <!-- Your checkout UI -->
</section>

<nav data-epicontext="navigation-ia-tree">
  <!-- Your navigation -->
</nav>

The attribute value should match a block key in your EpicContext project. When team members activate the widget, they'll see the relevant product context for that part of the application — including the design decisions, user personas, and feature specifications behind it.

Creating User Stories

With the widget active, team members can create user stories directly from the application:

Leaving Feedback

Feedback and comments work similarly to user stories:

1. Activate the widget
2. Click on the relevant part of the application
3. Type your feedback or comment
4. Submit — it syncs to your EpicContext project

Feedback is visible in your project dashboard and can be viewed by your entire team.

Widget Settings in EpicContext

Configure additional widget settings from your project dashboard:

1. Go to Settings > Widget
2. Configure allowed domains (for CORS)
3. Customize the widget appearance
4. Copy the embed code with your settings pre-filled

Technical Details

Next Steps

• Learn about team collaboration workflows with the widget
• Explore the API endpoints the widget uses
• Set up AI Coding Agents for development context