Edge Kit

Edge Kit is a comprehensive toolkit for TypeScript projects, designed to accelerate development with high-quality, copy-paste-ready components. Ideal for NextJS and other serverless platforms, Edge Kit prioritizes type safety, minimal dependencies, and architectural best practices.

🚀 Core Philosophy

Edge Kit is built with a "copy-paste-first" philosophy. Instead of installing a monolithic package, you copy exactly what you need into your project.

The MCP server follows the same contract: it returns source bundles that should be copied into the target repository. It is not presenting Edge Kit as an importable runtime package.

Architecture Patterns

• Abstract Base Classes: Services typically define an abstract contract (e.g., AbstractStorageService), allowing you to swap implementations (e.g., S3 vs R2) without changing consuming code.
• Dependency Injection: Services receive their dependencies (loggers, clients) via the constructor, facilitating testing and flexibility.
• Type Safety: Heavy use of generics, conditional types, and utility types to ensure compile-time safety.

🏁 Getting Started

Prerequisites

• Node.js (v18+)
• TypeScript (v5.0+)

Usage Guide

1. Browse: Find the component you need in the src directory.

2. Copy: Copy the file(s) into your project (e.g., src/services/storage/).

3. Install Dependencies: Check the top of the file for required packages and install them.

   npm install @aws-sdk/client-s3 # Example for S3Storage
   

4. Instantiate:

   // Example: Using the S3 Storage Service
   import { S3Storage } from "./services/storage/s3-storage";
   
   const storage = new S3Storage({
     bucket: process.env.AWS_BUCKET_NAME!,
     region: "us-east-1",
     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
   });
   

📦 Features & Services

Billing

• Stripe

Storage

• S3
• Cloudflare R2
• Storage Asset Catalog
• Storage Asset Refs
• Storage Upload Ledger
• Storage Asset Inventory & Lifecycle
• Contextualizer

Key-Value Store

• Upstash Redis
• Ioredis
• In-Memory

Vector Database

• Upstash Vector

RAG (Retrieval)

• RAG Service: End-to-end chunking, indexing, and search.
• Voyage Reranker
• Contextualized Embeddings: (Voyage voyage-context-3)

Logging & Alerting

• Axiom Logger
• Alerting: Axiom, Slack, PagerDuty implementations.
• Internal Error Persistence: KV-backed aggregate and per-actor diagnostics.

Analytics

• PostHog

CRM

• Apollo API

Email Verification

• ZeroBounce

LLM

• AI cache middleware
• Optimistic LLM warm-up
• AI diagnostics
• Deep Research: async Gemini Deep Research agent lifecycle with start, poll, continue, and wait helpers
• Image generation: pure generation, optional storage persistence, optional asset inventory, and inventory-backed preview metadata hooks
• Local Parakeet transcription provider: AI SDK experimental_transcribe support for local Parakeet MLX runtimes

Health

• Health probe helpers

Operations & Coordination

• Task Reconciler: Central registry-based desired-vs-applied reconciliation for reindexing, backfills, cache rebuilds, and similar operational work.
• Service Ingress: Typed internal service-to-service ingress over one shared signed endpoint.
• Incoming Hook: Verified inbound POST handling for Vercel, GitHub, and Stripe webhooks.

Developer Tooling

• Dev Launcher: Manifest-driven local dev launcher for repo and monorepo scripts plus TS-defined developer actions with a plain runner and Ink TUI.
• Git Commit Report: Reusable CLI module for author- and time-bounded git commit context reports.
• Skills CLI: Reusable CLI module for installing, verifying, and removing global Codex skill directories.

Feature Flags & Waitlist

• Client-side Feature Flag
• Key-Value Waitlist

🖥️ Dev Launcher

Edge Kit now includes a generic manifest-driven dev launcher that can supervise local scripts across a single-package repo or PNPM monorepo. Long-running services and one-shot developer actions now live in one shared TS/JS config file, dev-cli.config.ts (or .mts / .js / .mjs).

Run the example repo command:

pnpm cli dev
pnpm cli dev --services tests
pnpm cli dev --no-tui
pnpm cli action list
pnpm cli action list --toon
pnpm cli action run install-deps
pnpm cli action run install-deps --force

Minimal dev-cli.config.ts:

import { installDepsAction } from './src/cli/dev-launcher/actions/install-deps';
import { gitPullAction } from './src/cli/dev-launcher/actions/git-pull';
import { defineDevLauncherConfig } from './src/cli/dev-launcher/config';

export default defineDevLauncherConfig({
  actionsById: {
    'git-pull': gitPullAction,
    'install-deps': installDepsAction,
  },
  packageManager: 'pnpm',
  servicesById: {
    app: {
      label: 'App',
      openUrl: 'http://localhost:3000',
      target: {
        kind: 'root-script',
        script: 'dev',
      },
    },
    api: {
      label: 'API',
      target: {
        kind: 'workspace-script',
        packageName: '@repo/api',
        script: 'dev',
      },
    },
  },
  version: 1,
});

Edge Kit ships gitPullAction and installDepsAction as concrete dev-launcher modules. gitPullAction fetches the tracked remote branch and only becomes available when the current branch can be fast-forward pulled. If you need to customize either action, start from src/cli/dev-launcher/actions/git-pull.ts or src/cli/dev-launcher/actions/install-deps.ts and keep dev-cli.config.ts as your repo-root dev launcher entrypoint.

The TUI keeps the dashboard split for overview, but Enter on a selected service opens a focused log mode that renders only that service log so scroll and terminal text selection stay isolated. If a service defines openUrl, the selected row also supports o to open that URL in your default browser.

Configured developer actions are also available inside pnpm cli dev. The TUI shows an action availability summary, and pressing x opens an action picker that displays each action's current available / unavailable state plus the reason when one exists. Press Enter in that picker to run the selected action. Actions may also define an explicit one-character hotkey such as i for install-deps; when present, the TUI can run that action directly from startup, dashboard, focused-log, and action-picker views. Actions with non-parallel impact policies pause managed services first and restore them afterward.

Startup selection is recent-history-driven now. The launcher stores the latest selected service combinations in a user-local state file and renders those choices by service label only, plus a Custom selection escape hatch. That history is local UX state and does not change the repo config.

pnpm cli dev still evaluates only actions with suggestInDev: true for advisory preflight suggestions before the TUI starts, and prints messages such as Action available before starting services: install-deps - run pnpm cli action run install-deps.

Other action patterns can stay fully repo-local. Typical examples include:

• db-push: run a schema push only when generated SQL or migration state indicates it is needed.
• db-migrate: run a migration workflow and report a short summary.
• Custom Node or shell workflows using ctx.exec(...) or ctx.pnpm(...).

Git Commit Report

Edge Kit also includes a reusable git-history reporting command for collecting committed changes by author within an explicit time range. The command shells out to the local git binary, returns per-commit metadata plus line-change stats, detects GitHub-style PR references from local history, and can emit either human-readable text or TOON for LLM-friendly downstream tooling.

Run the example repo command:

pnpm cli commits report --since "2026-03-01" --until "2026-03-19"
pnpm cli commits report --since "2026-03-01" --until "2026-03-19" --author "alice@example.com"
pnpm cli commits report --since "2026-03-01" --until "2026-03-19" --author "alice@example.com" --author "bob@example.com"
pnpm cli commits report --since "2026-03-01" --until "2026-03-19" --toon
pnpm cli commits report --since "2026-03-01" --until "2026-03-19" --author "alice@example.com" --files --body --patch

Each commit entry includes:

• author name and email
• authored timestamp
• subject line
• files changed
• additions and deletions
• optional per-file change rows when --files is passed
• detected PR references for the timeframe when commit history carries them
• optional body and patch output when explicitly requested

Skills CLI

Edge Kit also includes a reusable skills-management command for installing global Codex skill directories from a local skill path or a repository. The command defaults to ~/.codex/skills, tracks provenance plus content hashes in skills-lock.json, and keeps removal safe by refusing to delete untracked skills unless --force is passed.

Run the example repo command:

pnpm cli skills list
pnpm cli skills list --toon
pnpm cli skills install --path /path/to/my-skill
pnpm cli skills install --repo vercel-labs/skills --name find-skills
pnpm cli skills info find-skills
pnpm cli skills verify
pnpm cli skills remove find-skills

🎼 Composers

Composers help structure complex logic in a type-safe way.

Namespace Composer

Manage key-value namespaces (e.g., for Redis) with type safety.

const ns = new NamespaceComposer({
  user: "users",
  session: (id: string) => `session:${id}`,
});
const key = ns.key("session", "123"); // "session:123"

Prompt Composer

Build structured LLM prompts with template substitution and TOON-first data formatting.

import { PromptComposer } from "./src/composers/prompt-composer";

const prompt = PromptComposer.composer(
  `
  Summarize these users:
  {{users}}
  `,
  {
    users: {
      data: [
        { id: 1, name: "Alice", role: "admin" },
        { id: 2, name: "Bob", role: "editor" },
      ],
      converter: (data) => PromptComposer.format(data),
    },
  },
  {}
);

Primitive arrays render compactly:

PromptComposer.format(["alpha", "beta", "gamma"]);
// [3]: alpha,beta,gamma

Uniform object arrays render as TOON tables:

PromptComposer.format([
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" },
]);
// [2]{id,name}:
//   1,Alice
//   2,Bob

Nested objects stay structured without hand-written serializers:

PromptComposer.format({
  team: { name: "Edge", active: true },
  tags: ["prompt", "toon"],
});
// team:
//   name: Edge
//   active: true
// tags[2]: prompt,toon

Use PromptComposer.format(data, { format: "xml" }) when your prompt contract is XML-specific. Use mdSchema() from markdown-utils.ts when you need schema-driven Markdown/XML presentation rather than compact raw data encoding.

🧰 Utilities

High-quality, focused utility functions located in src/utils/.

• Markdown Schema: Render structured data to Markdown/XML for AI prompts.

  import { mdSchema } from "./utils/markdown-utils";
  const schema = mdSchema<User>({
    name: { format: "bold" },
    email: { format: "code" },
  });
  const md = schema.build(user); // "**name**: Alice\n`email`: alice@example.com"
  

• Try/Catch: Go-style error handling.

  const [error, result] = await tryCatch(asyncFn());
  

• Custom Error: Typed error handling.
• Date, String, Array, Crypto, and more.

📣 Starter Kits

Looking for a full-stack starter?

• Create T3 App
• Next.js SaaS Starter