Your AI agent is flying blind
No AGENTS.md, no specs, no conventions. Every prompt starts with “here’s my folder structure…” and ends with wrong-file edits.
Agent-first · Next.js SaaS kit
Isotopekit
Ship production SaaS in weeks.
Orgs, billing, and agent-ready docs — composed from packages, not forked from a starter.
18
@isotopekit packages
4
Package tiers
4
Org types supported
0
Fake checkout plans
Built for founders who ship with AI — and need production infrastructure underneath.
SaaS foundersIndie hackersAgenciesStartup teamsAI-native builders
Sound familiar?
Most SaaS kits are fineuntil you need a real business
The pain points we kept hearing — on Reddit, in support threads, and from our own rebuilds.
Billing tied to users
Your customer has three orgs. The payment plugin bills the person. Accounting sends you a sad emoji.
Vendor lock-in on day one
Inline card forms looked cool in the demo. Switching payment providers now means rewriting half the app.
Org limits in React components
membersPerOrg = 25 hardcoded in a useEffect. Change the plan in admin? Good luck finding every copy.
Isotopekit was built from the docs up — agent-first conventions, org billing, webhook-driven activation, and packages you upgrade instead of re-merging.
Why Isotopekit
Not another login pagewith a Stripe button glued on.
Three ideas behind the monorepo — agent-first docs, production SaaS surfaces, and composable packages.
Agent-first
AGENTS.md, structured docs, and skills so AI tools ship features — not invent folder names.
Production SaaS
Orgs, billing, entitlements, agency mode, and admin — the unglamorous work already done.
Composable core
Versioned @isotopekit/* packages with extension points. Your routes stay yours; the platform stays upgradeable.
Compose, don't fork
Your app stays thin.The platform stays upgradeable.
Config for navigation. Bootstrap for secrets. Packages never import kit env — so you can update without merging a fork.
Navigation
Sidebar and menus from config — no hardcoded demo links in core UI.
@isotopekit/types NavItem · IsotopekitConfig.navigation.main · AppSidebar
Composition root
The app injects logger, db, auth, email, plans, and billing — packages never read kit env.
apps/starter/lib/bootstrap/* · createX / configureX · bootstrapFull() / bootstrapEdge()
API extensions
Mount your own Hono routes on /api/v1 without editing package source.
createV1App({ extensions: [(app) => app.route(...)] }) · lib/adapters/v1-route.ts
Billing catalog
Product-specific plans and add-ons — starter keeps defaults, your app brings its own catalog.
apps/starter/db/seed/catalog.ts · configureBillingOps in lib/bootstrap/full-wire.ts
Database schema
Merge your product tables with platform schema. Migrations stay app-owned.
createDb({ connectionString, schema }) · createDrizzleConfig · apps/starter/db/
Layout shells
User shell in apps/starter; org chrome from @isotopekit/org-ui; admin and agency shells take app { name, userHome }.
lib/app-config.ts · @isotopekit/org-ui · createAdminLayout / createAgencyPanelLayout
Feature flags
Turn billing, admin, or agency surfaces on or off per product.
IsotopekitConfig.features: { billing, admin, agency }
Route files live in your app. Composition-root wires live in lib/bootstrap/*. Reusable server, client, and handler exports live in packages — and stay unit-testable with fakes.
Update packages.Not your entire app.
Bump @isotopekit/* with semver — extension points and your app routes stay stable. No more merging upstream into a forked starter every release.
Semver-stable packages
Update @isotopekit/* with pnpm — minor and patch releases preserve extension contracts.
Your app stays put
Product routes, pages, and isotopekit.config.ts live in apps/starter. Platform code upgrades underneath.
No merge-upstream hell
Consumer apps depend on versioned packages instead of git-pulling an entire starter repo every month.
Everything you need
Batteries included.Baggage not.
Flip a card for the technical layer. Press ⌘K for the rest.
Starter kit
Clone once.Ship product, not plumbing.
apps/starter is a thin composition root — your routes, our packages, wired at lib/bootstrap.
- apps/starter — composition root + thin SaaS app
- isotopekit.config.ts + lib/app-config.ts
- Package wires: lib/bootstrap (logger · db · plans · auth · email · billing · api)
- User, org, billing, admin & agency routes
- Org product UI via @isotopekit/org-ui (switcher, branding, usage)
- Thin API/auth route wrappers in apps/starter/lib/adapters/
- Pricing page + guest checkout flow
- Legal pages, sitemap & robots
- Docker dev environment (isotopekit_core_app)
- 18 composable @isotopekit/* packages (core / domain / modules / transport)
Honest comparison
Other kits teach patience.We teach shipping.
Demos look fine until billing, multi-tenant orgs, and “we’ll add that later” catch up.
Who gets billed?
The user account (good luck with multi-org)
The organization — one subscription per workspace
AI / agent onboarding
Hope ChatGPT guesses your folder structure
AGENTS.md, _docs specs, and Cursor skills included
Payment provider lock-in
Rewrite checkout when you switch vendors
BillingProvider adapter — swap keys in the app wire, keep UI
Checkout state
Fake pending plan rows or metadata hacks
billing_status enum — real plan_id from day one
Entitlements & metered usage
Hardcoded limits in components
JSON catalog + add-ons + credits pool per org
Agency / white-label
Build it yourself (6 months, maybe)
Hub + client accounts + pool distribution built in
Platform updates
Git-merge upstream and pray nothing broke
pnpm update @isotopekit/* — semver + stable extension points
Customizing the kit
Fork the whole repo and merge upstream forever
isotopekit.config.ts + @isotopekit/* packages — extend, don't rewrite
Social login
Custom OAuth spaghetti per provider
Better Auth socialProviders — ~20 min & ~5 files per provider
API portability
Everything tangled in app/ routes
Portable services — split to standalone API later
console.log debugging
grep production logs at 2am
Structured Pino logging with request context
What teams want
Plumbing done right. Product left to you.
Representative voices from founders and teams building B2B SaaS — org billing, upgrades, and agency flows that don’t become weekend projects.
“We stopped rewriting billing every time Stripe hiccuped. Org-level subscriptions just work — webhooks and all.”
“The monorepo finally made sense. We extend through config, bump packages, and our routes never get touched.”
“Agency mode sold our board. One hub, client workspaces, shared pool — we quoted six weeks, shipped in two.”
“Adding Google took one coffee. GitHub was the same pattern. Better Auth did the heavy lifting.”
Portable by design
Packages compose.The app wires them.
18 @isotopekit/* packages in four tiers. The starter is the composition root — it injects options so packages stay env-free and upgradeable.
App wires options into packagesPackages compose — no kit envapps/starter — composition root
Core
cfg
db
types
log
ui
Domain
id
auth
org
bill
plans
user
Modules
admin
agency
org-ui
price
ops
Transport
api
apps/starter
lib/bootstrap wires options
18 packages · 7 wired from the app · core → domain → modules → transport
Env stays in the app
Packages take createX / configureX options. Unit-test with fakes — no .env required.
Composition root
lib/bootstrap wires logger · db · plans · auth · email · billing · api once at boot.
Contracts vs surfaces
organization stays portable; org-ui owns React chrome. billing holds ports; billing-ops owns checkout.
Layer detail
05
apps/starter
Composition root — routes, env, and package wiring
- app/* route segments
- isotopekit.config.ts + lib/app-config.ts
- lib/bootstrap/* — logger · db · plans · auth · email · billing · api
- lib/adapters/* — auth, v1 API, billing webhooks, checkout status
04
packages/modules
Product UI surfaces and billing operations
- @isotopekit/admin — createAdminLayout({ navigation, app })
- @isotopekit/agency — createAgencyPanelLayout({ navigation, app })
- @isotopekit/org-ui — org switcher, branding, plan usage, quotas
- @isotopekit/pricing — catalog UI & checkout dialogs
- @isotopekit/billing-ops — checkout, webhooks, configureBillingOps
03
packages/transport
Portable HTTP — Hono v1, no Next imports
- @isotopekit/api — createV1App({ extensions })
- apps/api — non-Next smoke (@isotopekit/api-app)
- Depends on domain + core only
02
packages/domain
Shared business kernel — auth, org, plans, billing contracts
- @isotopekit/identity, auth, organization, plans, user
- @isotopekit/billing — status, read-models, ports (no provider SDKs)
- Org product UI lives in @isotopekit/org-ui (modules), not organization
- Options via configureAuth / configurePlans — no kit env imports
01
packages/core
Infra primitives — leaf packages with minimal deps
- @isotopekit/config — env presets only (`@isotopekit/config/env`)
- @isotopekit/types — NavItem, IsotopekitConfig, defineProductConfig
- @isotopekit/db createDb · logger createLogger · email createEmailService
- Core must not depend on domain or modules
Unlock Reactor Mode or run “Show Architecture Layers” via ⌘K to reveal implementation paths.
Monorepo packages
18 packages.One coherent product.
Core, domain, modules, and transport — import what you need. The app wires options; packages stay env-free.
Core: Next.js 16 · TypeScript · Zod
Data & auth: PostgreSQL · Drizzle ORM · Better Auth
API & state: Hono · TanStack Query
UI: Tailwind CSS v4 · shadcn/ui · Lucide
Ops: Pino · React Email · Docker · Vercel Workflows
@isotopekit/configEnv presets (core/auth/billing) — app extends via @/env
@isotopekit/typesShared types, NavItem, IsotopekitConfig, defineProductConfig
@isotopekit/dbDrizzle schema, createDb({ connectionString }), queries
@isotopekit/loggerPino createLogger({ level, logFile }) with request context
@isotopekit/emailcreateEmailService + injectable transport for tests
@isotopekit/uishadcn primitives, shared components, progress hooks
@isotopekit/identityAuth options, branding, org-type, session services
@isotopekit/authBetter Auth factory, session guards, createAuthClientForApp
@isotopekit/organizationPortable workspace services, actions, loaders
@isotopekit/billingBilling contracts, org-status, read-models, ports
@isotopekit/plansconfigurePlans / getDefaultPlanId, entitlements math
@isotopekit/userAccount settings, sessions, profile actions
@isotopekit/org-uiOrg switcher, branding chrome, plan usage, member quotas
@isotopekit/billing-opsconfigureBillingOps, checkout, webhooks, Dodo adapter
@isotopekit/pricingPricing page loaders, plan cards, checkout dialogs
@isotopekit/adminPlatform operator shell — layouts take app { name, userHome }
@isotopekit/agencyAgency hub shell, client allocation, white-label
@isotopekit/apiHono v1 routes, portable HTTP transport
Pricing
One kit.Your product on top.
Full monorepo, starter composition root, and semver package updates — so you ship SaaS, not plumbing.
Early access
Full monorepo, starter app, and package updates while we polish launch.
Contact
- All @isotopekit/* packages
- apps/starter composition root
- Agent docs + Cursor skills
- Semver package updates
Team
For startups shipping one product on the kit.
Soon
- Everything in Early access
- Priority support channel
- Upgrade guides per release
- Composition-root wiring help
Agency
White-label and multi-client workflows built in.
Soon
- Agency hub + client accounts
- Branding extension points
- Dedicated onboarding call
- Everything in Team
FAQ
Questions before you clone
Short answers. No sales-deck energy.
Isotopekit
Your SaaS deservesa proper foundation
Stop duct-taping auth, billing, and org limits every weekend. Start from infrastructure built for production B2B.
Social login in ~20 minutes.Same pattern for every provider.
Google ships wired today. GitHub, Microsoft, Apple, LinkedIn, and Discord follow the same Better Auth steps — no custom OAuth layer.
~20 min
per provider (OAuth console + env + bootstrap/auth.ts)
Files touched per provider
packages/core/config/src/env/auth.tsOptional Zod env keys in the auth preset (if kit-wide)
apps/starter/env.tsOr product-only keys via createEnv extends
apps/starter/.envProvider client id + secret
apps/starter/lib/bootstrap/auth.tsAdd entry under socialProviders (+ trustedProviders)
Account linking is enabled for trusted providers. UI buttons render only when credentials are wired in the app's auth options — same pattern as Google today.