Skip to content

chatfuel-lab/wizard / content/modules/core/skill

playbooks/embed.md

View on GitHub
# Embedding Chatfuel modules into a host project

The wizard copied a self-contained footprint into `src/chatfuel/` of the host
project and installed the skills. Nothing in the host is wired yet — this
playbook walks you (the agent) through every step. Per-module specifics live
in each module's own `playbooks/embed.md` (sibling skill dirs).

## What the wizard copied

```
src/chatfuel/
├── modules/types.ts              # the module contract (ModuleAppProps)
├── modules/<id>/…                # each selected module's source
├── vendor/ui/…                   # design system (Tailwind v4 tokens + components)
├── vendor/api/…                  # typed GraphQL client + generated documents
├── vendor/chatfuel-proxy/…       # the proxy, one file per concern; core.ts assembles them
└── client.ts                     # createAppClient() — proxy-mode ModuleClient
```

Everything is vendored (shadcn philosophy): the host owns every line; edit
freely. Module code imports only `react`, `~ui`, `~api` and its own files.

## 1. Dependencies

The wizard printed the exact command. Base set: `graphql`, `graphql-ws`,
`@graphql-typed-document-node/core` (runtime); `ws`, `@types/ws`,
`tailwindcss`, `@tailwindcss/vite` (dev, Vite hosts). A module may add its own,
in which case its playbook says so — today none do. The host must already have
`react` + `react-dom`.

## 2. The `~ui` / `~api` aliases

TypeScript (host TypeScript config — the one that includes `src`; fresh Vite
templates split configs, so that is the app-side tsconfig):

```jsonc
{
  "compilerOptions": {
    "paths": {
      "~ui": ["./src/chatfuel/vendor/ui/index.ts"],
      "~ui/*": ["./src/chatfuel/vendor/ui/*"],
      "~api": ["./src/chatfuel/vendor/api/index.ts"],
      "~api/*": ["./src/chatfuel/vendor/api/*"]
    }
  }
}
```

(`paths` resolve relative to the config file — do NOT add `baseUrl`; recent
TypeScript deprecates it and fresh Vite templates error on it.)

Verified host-template frictions (fresh `npm create vite` react-ts, 2026):
- `erasableSyntaxOnly` is on and rejects the generated `enum`s in
  `vendor/api/generated/` — set it to `false` in both split configs.
- The node-side tsconfig type-checks `vite.config.ts`; the vendored proxy
  uses fetch types, so add `"DOM"` to that config's `lib`.
- `module: "nodenext"` there means the proxy import in `vite.config.ts`
  needs the explicit extension: `./src/chatfuel/vendor/chatfuel-proxy/vite.ts`
  (`allowImportingTsExtensions` is already on in these templates).

Vite (`vite.config.ts`):

```ts
import path from 'node:path';

resolve: {
  alias: [
    { find: /^~ui$/, replacement: path.resolve('src/chatfuel/vendor/ui/index.ts') },
    { find: /^~ui\//, replacement: `${path.resolve('src/chatfuel/vendor/ui')}/` },
    { find: /^~api$/, replacement: path.resolve('src/chatfuel/vendor/api/index.ts') },
    { find: /^~api\//, replacement: `${path.resolve('src/chatfuel/vendor/api')}/` },
  ],
},
```

Next.js: the TypeScript "paths" above are enough (webpack/turbopack honor
them). If the host already uses `~ui`/`~api` for something else, rename the
aliases — they are plain strings in the copied sources (`grep -rl '~ui\|~api'
src/chatfuel` and sed both the sources and the config to e.g. `~cfui`).

## 3. Styles (Tailwind v4)

The components use Tailwind v4 utility classes plus the design tokens in
`src/chatfuel/vendor/ui/styles/tokens.css`. In the host's global CSS:

```css
@import "tailwindcss";
@import "@fontsource-variable/geist";
@import "@fontsource-variable/geist-mono";
@import "@fontsource-variable/manrope";
@import "./chatfuel/vendor/ui/styles/tokens.css";
@source "./chatfuel";
```

(`@source` makes Tailwind scan the copied sources for class names — adjust
the relative paths to where the host's CSS entry lives.)

The three font imports are the faces `tokens.css` names in `--font-sans` and
`--font-display`; drop them and the embedded UI silently falls back to the
host's system stack. They are npm packages, self-hosted, no third-party origin.

There is a fourth file, `vendor/ui/styles/base.css`, and it is deliberately NOT
in the block above. It paints `<body>`, restyles every `h1`–`h6` on the page to
the display face, and claims `::selection` and every scrollbar — right for a
standalone app, and a takeover of somebody else's. Import it only if the host
wants the Chatfuel look for the whole document.

- Host on Tailwind v4 already: just add the token import + `@source`.
- Host on Tailwind v3: v3 cannot read v4 `@theme` tokens. Either upgrade the
  host to v4, or isolate: build a small standalone CSS for the Chatfuel tree
  with the v4 CLI and scope it. Say so honestly to the user before picking.
- No Tailwind: add `@tailwindcss/vite` (or the PostCSS plugin for non-Vite)
  and create a CSS entry with the three lines above.

### Theming inside someone else's app

Three things to decide with the user rather than assume:

1. **Who owns the theme attribute.** By default the dark palette applies on
   `[data-theme='dark']` anywhere — deliberately not `:root`-prefixed — so the
   host can stamp the attribute on the wrapper element that holds the Chatfuel
   tree instead of on `<html>`. `useTheme({ target })` takes that element.
   Pass `persist: false` if the host already owns the user's theme preference
   and localStorage would fight it.
2. **`color-scheme` is not optional.** The `[data-theme='light']` /
   `[data-theme='dark']` blocks set it, and without them native `<select>`
   popups, scrollbars and autofill stay light inside a dark UI. If the host
   scopes the attribute to a wrapper, `color-scheme` scopes with it — which is
   usually what you want.
3. **Do not mount `ThemeToggle` unless the host asked for it.** Two theme
   switchers on one page is a bug. Reading the host's preference and calling
   `useTheme().setPreference` is normally the right integration.

The tokens file must stay a single self-contained import — everything the
components need is in it, and the wizard rewrites that one line. Restyling is
editing token values in place, not layering overrides on top.

## 4. The proxy (token never reaches the browser)

All module traffic goes to same-origin `/chatfuel/graphql` (GraphQL HTTP +
WS) and `/chatfuel/api/*` (REST uploads). `CHATFUEL_TOKEN` lives in `.env`
and must be injected server-side.

- **Vite:** register the vendored plugin —
  ```ts
  import { chatfuelProxy } from './src/chatfuel/vendor/chatfuel-proxy/vite';
  // in plugins: [...]
  chatfuelProxy(),
  ```
  It reads CHATFUEL_TOKEN / CHATFUEL_API_BASE from the env and relays
  WebSockets with its own connection_init. `vite.ts` is the only file in that
  directory importing `vite`; everything else is plain node — `core.ts`
  assembles the proxy from the per-concern files beside it and is what the
  production server (`server.ts`, `createChatfuelServer({ distDir })`) and the
  Vercel function mount too.
- **The REST route is an allowlist:** the five `/filestorage/upload/*`
  endpoints (`references/files-tasks.md`) and nothing else under `/api` —
  anything else answers `403 RestPathNotAllowed`. Uploads are the only REST
  surface this app has; everything else is a GraphQL operation. If a module
  genuinely needs another endpoint, add it to `REST_ALLOWED_PATHS` in the
  vendored `passthrough.ts` and decide there what fences it. On the four
  bot-scoped paths `?botID=` is required — it is the only thing the fence can
  read, so an upload without it answers `400 InvalidRequest` — the method must
  be `POST`, and `useraccount` is refused `403 AccountOperationBlocked` with the
  gate on, because it writes to the Chatfuel account rather than to a bot.
- **The bot fence:** by default the proxy asks Chatfuel which bots the token's
  account owns (every workspace, cached for a minute) and refuses a request
  naming anything else. Pass `allowedBotIds: [...]` to freeze the list instead,
  or `'any'` to turn the check off — for a host that does its own fencing.
- **The auth gate:** if the host sets `VITE_SUPABASE_URL` and
  `VITE_SUPABASE_ANON_KEY` (the `auth` module's env — two names, not three;
  there is no tenant-id setting), the proxy requires the caller's Supabase
  session on every request. Tenant membership is not a config value — the gate
  calls `cf_my_bot_ids` with the caller's own JWT and fences each request
  against the bot ids that session owns, one per Supabase project. Neither var
  set = open mode; one without the other = every request fails closed with
  `ProxyAuthMisconfigured`. Whatever host stack you wire, the browser's
  `Authorization` must never be forwarded upstream.
- **Next.js:** add an HTTP route handler that forwards
  `/chatfuel/graphql` and `/chatfuel/api/*` to `${CHATFUEL_API_BASE}` with
  `Authorization: Bearer ${process.env.CHATFUEL_TOKEN}`. Route handlers
  cannot relay WebSockets — modules that subscribe (livechat, coworker,
  deals, bookings) need the sidecar relay described in
  `references/cors-proxy.md` (shape A). Be honest about this limitation.
- **Anything else:** implement shape A from this skill's `references/cors-proxy.md`.

## 5. Mounting a module

Every module exports one entry component taking `ModuleAppProps`
(`src/chatfuel/modules/types.ts`): `botId`, `client`, `params`, `setParams`,
`view`, `setView` and `navigate`. `view` is the module's own surface (`''` is
its default one) and `navigate` is how it asks to go somewhere else — in an
embed, that is your router's job.

Minimal mount (no deep-link routing):

```tsx
import { useMemo, useState } from 'react';
import { createAppClient } from './chatfuel/client';
import { LivechatApp } from './chatfuel/modules/livechat/LivechatApp';

export function ChatfuelPanel() {
  const client = useMemo(() => createAppClient(), []);
  const [params, setParams] = useState(new URLSearchParams());
  const [view, setView] = useState('');
  return (
    <LivechatApp
      botId={botId /* whichever bot the host app is showing */}
      client={client}
      params={params}
      setParams={setParams}
      view={view}
      setView={(next, nextParams) => {
        setView(next);
        if (nextParams) setParams(nextParams);
      }}
      /* One module and no router of your own: a link into another module has
         nowhere to go. Point this at your router in the variant below. */
      navigate={() => undefined}
    />
  );
}
```

Router-integrated variant: back `params`/`setParams` with the host router's
search params, `view`/`setView` with a segment of your own route, and `navigate`
with your router's own push, so module deep links (e.g. livechat's
`?c=<conversation>`) become shareable URLs. The
exact entry component name and its deep-link params are in each module's
`playbooks/embed.md`.

Next.js note: the modules are client components — mount behind
`'use client'`, and replace `import.meta.env.*` reads with the host's public
env convention (`NEXT_PUBLIC_…`) where you wire `botId`.

## 6. Verify

1. Dev server starts with no missing-module errors (aliases OK).
2. The mounted module renders styled (tokens OK), not unstyled HTML.
3. Network tab: requests go to `/chatfuel/graphql` and get 200s (proxy OK);
   the token appears in NO request the browser makes.
4. For subscription modules: live updates arrive (WS relay OK).
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall