convex-command-overlay

Command bar globale per app Convex + React + Tailwind: shortcut configurabile, screenshot ad area, salvataggio eventi e webhook.

Installazione (app consumer)

npm install convex-command-overlay

Peer dependencies: convex, react, react-dom.

1. Backend Convex

Copia i file Convex nel tuo progetto:

npx convex-command-overlay-install

Poi unisci lo schema in convex/schema.ts:

import { defineSchema } from "convex/server";
import { overlaySchemaTables } from "./command-overlay/schemaTables";

export default defineSchema({
  ...overlaySchemaTables,
  // ...le tue tabelle
});

Avvia Convex e imposta il secret admin:

npx convex dev
npx convex env set OVERLAY_ADMIN_SECRET "tuo-secret"

2. React

Importa gli stili (obbligatorio per Tailwind del componente):

import "convex-command-overlay/styles.css";

Usa il componente passando il tuo api Convex generato:

import { ConvexProvider, ConvexReactClient } from "convex/react";
import { ConvexCommandOverlay } from "convex-command-overlay";
import { api } from "./convex/_generated/api";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

export function App() {
  return (
    <ConvexProvider client={convex}>
      <YourApp />
      <ConvexCommandOverlay api={api} userId="user-123" />
    </ConvexProvider>
  );
}

Pannello admin (opzionale)

import { OverlayAdmin } from "convex-command-overlay/admin";
import { api } from "./convex/_generated/api";

<OverlayAdmin api={api} />

Salva in UI il token uguale a OVERLAY_ADMIN_SECRET.

API esportate

| Export | Descrizione | |--------|-------------| | convex-command-overlay | ConvexCommandOverlay, tipi, utility shortcut/screenshot | | convex-command-overlay/admin | OverlayAdmin | | convex-command-overlay/styles.css | Foglio di stile Tailwind precompilato |

Payload webhook

{
  "text": "...",
  "screenshotUrl": "https://...",
  "screenshotStorageId": "...",
  "pageUrl": "https://...",
  "userAgent": "...",
  "createdAt": 1710000000000,
  "userId": "user-123"
}

Template personalizzato con {{text}}, {{pageUrl}}, ecc. (config admin).

Sviluppo del pacchetto (questo repo)

npm install
npx convex dev          # terminale 1
npm run dev             # terminale 2 — playground Vite
npm run build           # build libreria → dist/

Pubblicazione su npm

Esegui tu i comandi, ad esempio:

npm run build
npm login
npm publish --access public

Prima della prima publish verifica in package.json: name, version, repository, author.

Licenza

MIT