khotan-dataalpha
View as Markdown
Get Started

Introduction

khotan-data is an opinionated toolkit for building data movement, webhook, and operational tooling inside a Next.js app.

It is designed for TypeScript, Drizzle, and Postgres, and it scaffolds code into your repo instead of hiding the runtime behind a hosted service.

Think "shadcn for data plumbing". You install the package, run khotan commands, and get generated files for plugs, flows, wires, webhook handlers, dashboard components, and ready-made route blocks. The package also ships built-in agent skills so coding agents can understand how to work with khotan in a real app.

What you get

  • Plug for HTTP clients with auth, retry, pagination, vars, hooks, and typed endpoints.
  • Wire, Catch, and Pass for webhook registration, verification, durable processing, and forwarding.
  • Inflow, Outflow, and Relay for scheduled or manual data movement.
  • Hub, Runs, Logs, and Plug Debugger for operational UI and debugging.
  • Blocks like config-page-1, graph, logs-page-1, and debug-page-1.
  • Agent skills installed into detected agent directories so Cursor, Claude Code, Codex, Copilot, Kiro, and Roo can use khotan more effectively.

The model

  • a factory config at src/khotan/khotan.ts or khotan/khotan.ts
  • a catch-all route at app/api/khotan/[...all]/route.ts or src/app/api/khotan/[...all]/route.ts
  • standard Drizzle tables for plugs, resources, flows, wires, webhook handlers, webhook events, runs, and mappings

Everything else plugs into that surface.

Fast start

terminal
$ npm install khotan-data
$ npx khotan init --yes
$ npx khotan add schema --yes
$ npx khotan migrate
$ npx khotan add plug --yes
$ npx khotan add inflow --yes
$ npx khotan add hub --yes

Then:

  • register your plug, flows, wires, and webhook handlers in khotan.ts
  • run your app
  • use the CLI and the dashboard against /api/khotan/*

Built for humans and agents

The docs site is intentionally dual-format:

  • every major doc page has a rendered page under /docs/...
  • the same content is also available as raw markdown under /docs/... .md

That makes it easy for humans to browse and easy for agents, scripts, and LLM tooling to crawl and ingest the exact documentation source.

If you are an agent, start here:

  • read /docs/agents
  • read the project-root AGENTS.md after khotan init --yes or after skills are installed
  • prefer the .md routes when you want raw content

Stack

  • Next.js App Router
  • TypeScript
  • Drizzle ORM
  • Postgres
  • Vercel Workflow for durable flow and webhook execution

Skills are included

terminal
$ npx khotan add skill-build
$ npx khotan add skill-setup
$ npx khotan add skill-plug
$ npx khotan add agent-skill
$ npx khotan add skill-flow
$ npx khotan add skill-webhook
$ npx khotan add skill-cache
$ npx khotan add skill-mappings
$ npx khotan add skill-frontend

These teach agents how to:

  • run the end-to-end integration workflow (the khotan-build orchestrator)
  • set up khotan in a new project
  • build and debug plugs
  • build flows (inflow, outflow, relay)
  • connect wires and implement webhook flows
  • add caching and cross-service mappings
  • suggest frontend components and blocks
  • use the khotan plug CLI effectively

Next steps

  • Installation for the end-to-end setup order.
  • Basic Usage for a realistic plug + flow + webhook example.
  • Components for every installable component and its command.
  • Blocks for ready-made routes.
  • Agent Guide for the built-in skills and the most crawlable paths.