🦧 The Orangutan Kit

A dead-simple guide to setting up a modern dev toolkit. Next.js · Supabase or Convex · Resend · Mastra · Claude Code

What Is This?

This is a no-fluff setup guide for a full-stack TypeScript project with AI tooling baked in. Every tool here was picked because it's well-documented, has a generous free tier, and plays nicely with the others.

The stack at a glance:

Layer	Tool	One-liner
Frontend + API	Next.js 15	React framework with file-based routing and server rendering
Database	Supabase or Convex	Pick one. Supabase = Postgres + auth. Convex = real-time NoSQL
Email	Resend	Send emails using React components as templates
AI Framework	Mastra	Build AI agents, workflows, and RAG in TypeScript
Coding Agent	Claude Code	AI pair programmer in your terminal and IDE
Glue Layer	MCP Servers	Let Claude talk directly to your database and docs

Before You Start

You need these installed:

Node.js 20+ → nodejs.org
Git → configured with your GitHub account
Cursor IDE (recommended) or VS Code

You need these accounts (all have free tiers):

Supabase → supabase.com (if choosing Supabase)
Convex → convex.dev (if choosing Convex)
Resend → resend.com — grab an API key
Anthropic → console.anthropic.com — need Claude Pro/Max or API credits

Step 1 → Create Your Next.js Project

This is your foundation. Everything else plugs into this.

npx create-next-app@latest orangutan-app

Accept all the defaults (TypeScript, Tailwind, App Router, Turbopack). Then:

cd orangutan-app
npm run dev

Open http://localhost:3000. You should see the welcome page. That's it — you have a working app.

What you need to know:

src/app/page.tsx → your homepage
src/app/layout.tsx → wraps every page (put providers here)
src/app/api/ → your API routes (serverless functions)
.env.local → secrets go here (gitignored automatically)
Components are Server Components by default. Only add "use client" when you need browser stuff (hooks, click handlers, etc.)

Step 2 → Pick Your Database

Option A: Supabase (Postgres, built-in auth)

Best if: you want SQL, row-level security, and built-in authentication.

npm install @supabase/supabase-js @supabase/ssr

Add to .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

(Find these in your Supabase dashboard → Settings → API, or the Connect dialog.)

Create src/lib/supabase/client.ts (for browser/client components):

import { createBrowserClient } from "@supabase/ssr";

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

Create src/lib/supabase/server.ts (for server components and API routes):

import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { cookies: { /* see Supabase SSR docs for cookie handlers */ } }
  );
}

Shortcut: Run npx create-next-app -e with-supabase to get a pre-wired starter with auth, middleware, and both clients already configured.

Option B: Convex (real-time NoSQL, TypeScript-native)

Best if: you want reactive queries, zero SQL, and everything in TypeScript.

npm install convex
npx convex dev

This logs you in via GitHub, creates your project, and generates a convex/ folder. Keep this terminal running — it live-syncs your backend.

Create src/app/ConvexClientProvider.tsx:

"use client";
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export default function ConvexClientProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}

Wrap your app in layout.tsx with this provider. Write queries in convex/ and use them with useQuery() from convex/react.

Step 3 → Email with Resend

npm install resend @react-email/components

Add to .env.local:

RESEND_API_KEY=re_your_api_key_here

Create a template — src/components/email-template.tsx:

export function WelcomeEmail({ name }: { name: string }) {
  return (
    <div>
      <h1>Welcome, {name}!</h1>
      <p>Thanks for joining.</p>
    </div>
  );
}

Create an API route — src/app/api/send/route.ts:

import { Resend } from "resend";
import { WelcomeEmail } from "@/components/email-template";

const resend = new Resend(process.env.RESEND_API_KEY);

export async function POST() {
  const { data, error } = await resend.emails.send({
    from: "Orangutan Kit <onboarding@resend.dev>",
    to: ["your@email.com"],
    subject: "Welcome!",
    react: WelcomeEmail({ name: "Friend" }),
  });
  if (error) return Response.json({ error }, { status: 500 });
  return Response.json(data);
}

Note: On the free tier, you can send to your own email from onboarding@resend.dev — no domain setup needed for testing.

Step 4 → AI with Mastra

Mastra is a TypeScript framework for AI agents. Built on Vercel's AI SDK, supports 40+ providers.

Standalone project:

npm create mastra@latest

Or add to your existing Next.js app:

npm install @mastra/core @ai-sdk/anthropic

Create your first agent — src/mastra/agents/index.ts:

import { Agent } from "@mastra/core/agent";
import { anthropic } from "@ai-sdk/anthropic";

export const myAgent = new Agent({
  name: "Orangutan Assistant",
  instructions: "You are a helpful assistant for the Orangutan Kit project.",
  model: anthropic("claude-sonnet-4-20250514"),
});

Test it locally:

npx mastra dev

This starts a playground at http://localhost:4111 where you can chat with your agent before wiring it into your app.

To use in Next.js: Mastra provides handleChatStream() for API routes and works with Vercel AI SDK's useChat() hook on the frontend.

Step 5 → Install Claude Code

Claude Code is an AI coding agent that lives in your terminal. It reads your codebase, edits files, runs commands, and manages git.

Terminal install

npm install -g @anthropic-ai/claude-code
cd orangutan-app
claude

First run opens a browser to authenticate. After that, you're in.

In Cursor IDE

Easiest way: Open the Extensions panel → search "Claude Code" → install the official Anthropic extension → click the Claude icon to log in.

If that fails: Install manually:

cursor --install-extension ~/.claude/local/node_modules/@anthropic-ai/claude-code/vendor/claude-code.vsix

Or just use the terminal: Open Cursor's integrated terminal and run claude. Type /ide if it doesn't auto-detect Cursor.

Commands you'll actually use

Command	What it does
`/init`	Generate a CLAUDE.md for your project
`/compact`	Compress context when conversation gets long
`/clear`	Hard reset for a new task
`/model`	Switch models (Sonnet, Opus, Haiku)
`/ide`	Connect to your IDE from external terminal
`/cost`	Check token usage

Step 6 → Set Up MCP Servers

MCP (Model Context Protocol) lets Claude talk directly to your tools. Instead of copy-pasting database schemas or reading docs yourself, Claude can just look things up.

Supabase MCP

claude mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF"

It opens a browser for auth. No tokens to manage.

Mastra Docs MCP

claude mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest

Now Claude has Mastra's entire documentation available in every session.

For Cursor / VS Code

Create .cursor/mcp.json (or .mcp.json) in your project root:

{
  "mcpServers": {
    "supabase": {
      "type": "url",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF"
    },
    "mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

⚠️ Only use the Supabase MCP with dev projects. Never connect it to production data.

Step 7 → Write Your CLAUDE.md

This is the single biggest productivity lever. Claude reads this file at the start of every session.

Run /init inside Claude Code to generate a starter, then trim it down to what matters. Here's a template:

# Orangutan Kit
Next.js 15 app with Supabase, Resend email, and Mastra AI agents.

## Commands
- `npm run dev` — dev server (port 3000)
- `npm run build` — production build
- `npm run lint` — ESLint
- `npx mastra dev` — Mastra playground (port 4111)

## Architecture
- /src/app — Pages, layouts, API routes
- /src/components — Reusable React components
- /src/lib/supabase — Supabase client utilities
- /src/mastra — AI agents, tools, workflows

## Code Style
- TypeScript strict, no `any`
- ES module imports
- Tailwind only, no custom CSS files
- Server Components by default

## Rules
- NEVER commit .env.local
- Agent definitions go in /src/mastra/agents/
- Use @supabase/ssr for server-side clients

Keep it under 200 lines. If it's longer, Claude starts ignoring rules uniformly. Put domain-specific knowledge in .claude/skills/ instead.

Quick Reference Links

Tool	Docs
Next.js	nextjs.org/docs
Supabase	supabase.com/docs
Convex	docs.convex.dev
Resend	resend.com/docs
Mastra	mastra.ai/docs
Claude Code	code.claude.com/docs
Supabase MCP	supabase.com/docs/guides/getting-started/mcp
Mastra MCP	mastra.ai/docs/build-with-ai/mcp-docs-server

📋 COPY-PASTE SECTION: Feed This to an AI Agent

Everything below is a self-contained prompt. Copy the entire block and paste it into Claude Code, Cursor, or any AI coding agent to have it set up the Orangutan Kit for you.

You are setting up a project called "The Orangutan Kit" — a full-stack TypeScript development toolkit. Follow these steps exactly. Ask me to choose between Supabase or Convex before starting Step 2.

## STEP 1: SCAFFOLD NEXT.JS

Run:
  npx create-next-app@latest orangutan-app --yes
  cd orangutan-app

This creates a Next.js 15 app with TypeScript, Tailwind CSS, ESLint, App Router, and Turbopack.

Create these folders if they don't exist:
  src/lib/
  src/components/
  src/mastra/agents/

## STEP 2A: IF SUPABASE — Install Database

Run:
  npm install @supabase/supabase-js @supabase/ssr

Create file src/lib/supabase/client.ts:
  import { createBrowserClient } from "@supabase/ssr";
  export function createClient() {
    return createBrowserClient(
      process.env.NEXT_PUBLIC_SUPABASE_URL!,
      process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
    );
  }

Create file src/lib/supabase/server.ts:
  import { createServerClient } from "@supabase/ssr";
  import { cookies } from "next/headers";
  export async function createClient() {
    const cookieStore = await cookies();
    return createServerClient(
      process.env.NEXT_PUBLIC_SUPABASE_URL!,
      process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
      { cookies: { getAll() { return cookieStore.getAll(); }, setAll(cookiesToSet) { cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options)); } } }
    );
  }

Add to .env.local:
  NEXT_PUBLIC_SUPABASE_URL=PLACEHOLDER
  NEXT_PUBLIC_SUPABASE_ANON_KEY=PLACEHOLDER

Tell me to fill in the real values from my Supabase dashboard.

## STEP 2B: IF CONVEX — Install Database

Run:
  npm install convex

Create file src/app/ConvexClientProvider.tsx:
  "use client";
  import { ConvexProvider, ConvexReactClient } from "convex/react";
  const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
  export default function ConvexClientProvider({ children }: { children: React.ReactNode }) {
    return <ConvexProvider client={convex}>{children}</ConvexProvider>;
  }

Wrap the children in src/app/layout.tsx with <ConvexClientProvider>.

Tell me to run `npx convex dev` in a separate terminal to initialize the backend.

## STEP 3: INSTALL EMAIL (RESEND)

Run:
  npm install resend @react-email/components

Create file src/components/email-template.tsx:
  import * as React from "react";
  export function WelcomeEmail({ name }: { name: string }) {
    return (<div><h1>Welcome, {name}!</h1><p>Thanks for joining the Orangutan Kit.</p></div>);
  }

Create file src/app/api/send/route.ts:
  import { Resend } from "resend";
  import { WelcomeEmail } from "@/components/email-template";
  const resend = new Resend(process.env.RESEND_API_KEY);
  export async function POST() {
    const { data, error } = await resend.emails.send({
      from: "Orangutan Kit <onboarding@resend.dev>",
      to: ["delivered@resend.dev"],
      subject: "Welcome!",
      react: WelcomeEmail({ name: "Friend" }),
    });
    if (error) return Response.json({ error }, { status: 500 });
    return Response.json(data);
  }

Add to .env.local:
  RESEND_API_KEY=PLACEHOLDER

Tell me to fill in my Resend API key.

## STEP 4: INSTALL AI (MASTRA)

Run:
  npm install @mastra/core @ai-sdk/anthropic

Create file src/mastra/agents/index.ts:
  import { Agent } from "@mastra/core/agent";
  import { anthropic } from "@ai-sdk/anthropic";
  export const orangutanAgent = new Agent({
    name: "Orangutan Assistant",
    instructions: "You are a helpful AI assistant for the Orangutan Kit project. Help users with their code, answer questions about the stack, and suggest improvements.",
    model: anthropic("claude-sonnet-4-20250514"),
  });

Add to .env.local:
  ANTHROPIC_API_KEY=PLACEHOLDER

## STEP 5: CONFIGURE MCP SERVERS

Create file .mcp.json in the project root:
  {
    "mcpServers": {
      "supabase": {
        "type": "url",
        "url": "https://mcp.supabase.com/mcp?project_ref=PLACEHOLDER"
      },
      "mastra": {
        "command": "npx",
        "args": ["-y", "@mastra/mcp-docs-server@latest"]
      }
    }
  }

If using Convex instead of Supabase, remove the supabase entry from mcpServers.

Also create .cursor/mcp.json with the same content (for Cursor IDE support).

Tell me to run these commands in Claude Code to register the servers:
  claude mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest
  claude mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=PLACEHOLDER"

## STEP 6: CREATE CLAUDE.md

Create file CLAUDE.md in the project root:

  # Orangutan Kit
  Next.js 15 app with [Supabase/Convex], Resend email, and Mastra AI agents.

  ## Commands
  - `npm run dev` — Start dev server (port 3000)
  - `npm run build` — Production build
  - `npm run lint` — ESLint check
  - `npx mastra dev` — Mastra playground (port 4111)

  ## Architecture
  - /src/app — Next.js App Router pages, layouts, API routes
  - /src/components — Reusable React components
  - /src/lib — Utilities (Supabase clients, helpers)
  - /src/mastra — AI agents, tools, workflows
  - /convex — Convex backend functions (if using Convex)

  ## Code Style
  - TypeScript strict mode, no `any` types
  - ES module imports (import/export, not require)
  - Tailwind CSS for all styling, no custom CSS files
  - Server Components by default, add "use client" only when needed
  - Named exports preferred over default exports

  ## Important Rules
  - NEVER commit .env.local
  - All AI agent definitions go in /src/mastra/agents/
  - Use @supabase/ssr for server-side Supabase clients (not @supabase/supabase-js directly)
  - API routes go in /src/app/api/
  - Test email routes with onboarding@resend.dev on free tier

## STEP 7: VERIFY

Run `npm run dev` and confirm the app loads at http://localhost:3000.
List all files created and summarize what was set up.
Remind me of all the PLACEHOLDER values I need to fill in.

That's the whole kit. Go build something. 🦧