@giveusaproject/addon-kit

The add-on kit for Give Us a Project. Build add-ons that put a card on Home, add a page to the sidebar, give Archie (the app's assistant) a new tool, or run a job on a schedule, and test them on practice data before anyone turns them on.

Most people start with the command-line tool, which creates an add-on folder that already uses this kit:

npx @giveusaproject/addon-cli create my-addon

What's in it

| Import | For | |---|---| | @giveusaproject/addon-kit | defineBundle, defineTool, defineCollection, defineHook, defineSuggestion, defineSettings, defineView and the types they use | | @giveusaproject/addon-kit/server | what server code gets: context types, errors (ValidationError, NotFoundError, …), permission helpers | | @giveusaproject/addon-kit/client | React for views: AddonProvider, useCollection, useTool, useSlotContext, usePreferences, useAnnounce, … | | @giveusaproject/addon-kit/ui | components that look like the app (Card, EmptyState, Stack, …); import @giveusaproject/addon-kit/ui/styles.css once | | @giveusaproject/addon-kit/testing | createTestContext: practice data (empty, small-team, busy-sprint) and the same isolate the app runs add-on code in |

A tool, a view and a test

// server/index.ts
import { defineBundle, defineTool } from "@giveusaproject/addon-kit";
import { z } from "zod";

export const waitingTasks = defineTool({
  id: "waiting_tasks",
  description: "See bundle.md",
  parameters: z.object({ projectId: z.string().uuid() }),
  effect: "read",
  async handler(args, ctx) {
    const page = await ctx.tickets.list({ projectId: args.projectId, limit: 200 });
    return page.items.filter((t) => t.status.category === "blocked").map((t) => t.key);
  },
});

export default defineBundle({ id: "@my-team/waiting", tools: [waitingTasks] });

// ui/main.tsx
import "@giveusaproject/addon-kit/ui/styles.css";
import { AddonProvider, useTool } from "@giveusaproject/addon-kit/client";
import { Card } from "@giveusaproject/addon-kit/ui";

// tests/addon.test.ts
import { createTestContext } from "@giveusaproject/addon-kit/testing";
const ctx = createTestContext({ bundle: addon, permissions: ["tickets:read"], fixtures: "busy-sprint" });

Rules the app enforces

• Server code runs in a locked-down isolate: no Node built-ins, no network, no other packages. It may import this kit, zod and its own files.
• Views run in a sandboxed frame and may import react, react-dom/client, this kit's /client and /ui, and their own files.
• Every permission the code uses must be listed in bundle.md. People see them before they turn the add-on on, and an admin agrees to anything new in a later version.

Run npx @giveusaproject/addon-cli guide for the full guide (folder layout, bundle.md, checks, uploading, AI coding tools).

Licence

MIT