DEV Community: mt211211

Your README is a landing page: a 10-minute adoption audit for developer tools

mt211211 — Sun, 14 Jun 2026 15:25:44 +0000

For many developer tools, the GitHub README is the landing page.

A potential user often decides whether to try the product before visiting a separate website. They scan the repository title, the first screen of the README, one example, and the install command. If those pieces do not create a clear path to value, a longer feature catalog will not rescue the conversion.

Here is a ten-minute audit for a public developer-tool launch surface.

1. Run the five-second test

Read only the repository name, tagline, and first paragraph. Can a new visitor answer all four questions?

What is this?
Who is it for?
What outcome does it create?
What should I do next?

"An extensible platform for modern workflows" fails this test. "Block risky AI-generated pull requests before they reach main" is much easier to understand and act on.

2. Put the proof path before the rule catalog

Early READMEs often explain every feature before showing one useful result. Reverse that order.

A stronger first screen usually contains:

a concrete outcome;
one screenshot or short example output;
the shortest safe install path;
the first successful action a user can complete;
the expected result.

The visitor should be able to imagine reaching value before they commit to reading the architecture.

3. Make the first action feel bounded

"Install and configure the platform" sounds expensive. A bounded pilot lowers adoption risk:

Try it on one repository, one workflow, or one sample file in ten minutes. Start in observe mode, then enforce only what proves useful.

This is especially important for security, CI, infrastructure, and agent tools. Users want to know that trying the product will not immediately disrupt their workflow.

4. Translate technical findings into a human decision

A raw finding such as workflow/permission-escalation is useful to an expert, but the conversion moment is the decision it enables.

Needs human decision
Why: this pull request increased workflow permissions.
Recommended next step: review the workflow change before merging.

Lead with the decision. Put technical detail underneath it.

5. Check the CTA against the visitor's stage

A new visitor is rarely ready to "adopt the platform." They may be ready to run a sample, inspect a real report, install in warning mode, compare examples, or try one command. The primary CTA should name that next action rather than use a generic "Get started."

A compact README opening structure

[Concrete outcome for a defined user]

[One sentence explaining how it works and the main trust boundary]

[Real output or screenshot]

Try it in 10 minutes:
1. [small install step]
2. [first action]
3. [expected result]

A developer tool can have excellent engineering and still lose adoption because the first screen makes the value feel harder to reach than it really is.

I am collecting public examples and will give one specific conversion critique on a SaaS homepage or developer-tool README here:
https://github.com/mt211211/saas-homepage-conversion-checklist/discussions/2

I also offer a fixed-scope 24-hour launch-surface review for $49 when a rewritten opening, CTA, and proof-path experiment would be useful:
https://mt211211.github.io/conversion-desk-site/

Which sentence on your SaaS homepage is hardest to write?

mt211211 — Sat, 13 Jun 2026 17:27:59 +0000

For founders and indie developers: which sentence on your current homepage is hardest to write? Paste the public sentence, target customer, and desired action. I will reply with one alternative and explain the tradeoff behind it.

How I audit a SaaS homepage before changing the design

mt211211 — Sat, 13 Jun 2026 17:04:55 +0000

A SaaS homepage usually does not fail because its gradient is wrong.

It fails because the page makes the visitor answer too many questions on their own:

Is this actually for me?
What changes after I use it?
Why should I trust this product?
What happens if I click the button?

Before changing a design, I use the following review sequence.

1. Run the five-second explanation test

Read only the hero, then hide the page.

Can you complete this sentence without guessing?

This helps [specific customer] achieve [specific outcome] by [credible mechanism].

If not, the page has a positioning problem before it has a conversion problem.

A broad headline such as:

The all-in-one platform for modern teams

forces the visitor to translate the product into their own situation.

A more useful version might be:

Turn overdue agency invoices into polite, automatic follow-ups.

It names the buyer, pain, and mechanism.

2. Inspect the primary CTA as a promise

A CTA is not just a button label. It is a promise about what happens next.

Get started is vague. It can mean creating an account, booking a call, entering a credit card, or beginning a complicated setup.

Better CTA copy reduces uncertainty:

See a sample report
Calculate my savings
Start a 14-day trial, no card required
Check my website score

The right CTA depends on how much trust the visitor has at that moment.

3. Move the strongest differentiator earlier

Many pages lead with category-level benefits and bury their most convincing reason to buy.

Look for the sentence that makes a prospect say, "That is different." It may be hidden in an FAQ, feature block, or founder story.

Move that idea close to the hero and support it with evidence.

4. Show an output, not another claim

If the page sells a result, show the result.

For a reporting tool, show a report. For an automation tool, show the automated sequence. For a developer tool, show the command and output. For a service, show an illustrative deliverable and label it honestly.

Concrete outputs reduce the perceived risk of clicking the CTA.

5. Give hesitant visitors a smaller next step

Not every qualified visitor is ready for the primary conversion.

A lower-commitment step can capture intent without forcing a premature decision:

an interactive calculator
a sample output
a short scorecard
a public example
a technical guide

The secondary CTA should build confidence in the primary offer, not distract from it.

A practical review order

When reviewing a live homepage, I prioritize issues in this order:

Audience and outcome clarity
Primary CTA clarity
Proof and trust
Objection handling
Lower-commitment next step

That order prevents a common mistake: polishing low-impact sections while the hero still confuses the right buyer.

I built a free SaaS homepage scorecard that applies these questions without requiring signup. There is also an illustrative sample teardown showing the report format.

If you are working on a live B2B SaaS homepage, leave the URL and target customer in the comments. I will reply with the single highest-priority conversion issue I see. Please do not share anything confidential.

Auth.js v5 with Next.js and Drizzle ORM: the complete setup guide

mt211211 — Sat, 13 Jun 2026 07:32:01 +0000

Auth.js v5 with Next.js and Drizzle ORM: the complete setup guide

Auth.js v5 (formerly NextAuth.js) is a significant rewrite. The API is cleaner, but most tutorials still show v4 patterns — which won't work. This guide covers everything from OAuth setup to a Drizzle Postgres adapter, in a way that actually compiles.

What changed in v5

The big shifts:

Single auth.ts config file replaces the scattered [...nextauth] options
auth() is universal — use it in Server Components, Route Handlers, and Proxy (formerly Middleware)
handlers replaces GET/POST export ceremony
The middleware.ts convention is now proxy.ts in Next.js 16+

1. Install

npm install next-auth@beta @auth/drizzle-adapter drizzle-orm @neondatabase/serverless
npm install --save-dev drizzle-kit

2. Drizzle schema for Auth.js

Auth.js needs four tables: users, accounts, sessions, verification_tokens. Define them with Drizzle's pg-core:

// src/lib/db/schema.ts
import {
  boolean, integer, pgTable, primaryKey, text, timestamp,
} from "drizzle-orm/pg-core";
import type { AdapterAccount } from "@auth/core/adapters";

export const users = pgTable("users", {
  id: text("id").primaryKey(),
  name: text("name"),
  email: text("email").unique(),
  emailVerified: timestamp("email_verified", { mode: "date" }),
  image: text("image"),
});

export const accounts = pgTable(
  "accounts",
  {
    userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
    type: text("type").$type<AdapterAccount["type"]>().notNull(),
    provider: text("provider").notNull(),
    providerAccountId: text("provider_account_id").notNull(),
    refresh_token: text("refresh_token"),
    access_token: text("access_token"),
    expires_at: integer("expires_at"),
    token_type: text("token_type"),
    scope: text("scope"),
    id_token: text("id_token"),
    session_state: text("session_state"),
  },
  (account) => [primaryKey({ columns: [account.provider, account.providerAccountId] })]
);

export const sessions = pgTable("sessions", {
  sessionToken: text("session_token").primaryKey(),
  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
  expires: timestamp("expires", { mode: "date" }).notNull(),
});

export const verificationTokens = pgTable(
  "verification_tokens",
  {
    identifier: text("identifier").notNull(),
    token: text("token").notNull(),
    expires: timestamp("expires", { mode: "date" }).notNull(),
  },
  (vt) => [primaryKey({ columns: [vt.identifier, vt.token] })]
);

3. Drizzle client (Neon serverless)

// src/lib/db/index.ts
import { neon } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
import * as schema from "./schema";

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql, { schema });

4. Auth config

// src/auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
import { DrizzleAdapter } from "@auth/drizzle-adapter";
import { db } from "@/lib/db";
import { accounts, sessions, users, verificationTokens } from "@/lib/db/schema";

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: DrizzleAdapter(db, {
    usersTable: users,
    accountsTable: accounts,
    sessionsTable: sessions,
    verificationTokensTable: verificationTokens,
  }),
  providers: [
    GitHub,
    Google,
  ],
  callbacks: {
    // Expose user.id in the session — not available by default
    session({ session, user }) {
      session.user.id = user.id;
      return session;
    },
  },
  pages: {
    signIn: "/sign-in",
  },
});

// Augment the Session type to include id
declare module "next-auth" {
  interface Session {
    user: { id: string; name?: string | null; email?: string | null; image?: string | null; };
  }
}

5. Route handler

// src/app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

One line. That's it.

6. Sign-in page with Server Actions

Auth.js v5 uses Server Actions for sign-in — no client-side JS required:

// src/app/(auth)/sign-in/page.tsx
import { signIn } from "@/auth";

export default function SignInPage({
  searchParams,
}: {
  searchParams: { callbackUrl?: string };
}) {
  return (
    <div>
      <form
        action={async () => {
          "use server";
          await signIn("github", {
            redirectTo: searchParams.callbackUrl ?? "/dashboard",
          });
        }}
      >
        <button type="submit">Continue with GitHub</button>
      </form>

      <form
        action={async () => {
          "use server";
          await signIn("google", {
            redirectTo: searchParams.callbackUrl ?? "/dashboard",
          });
        }}
      >
        <button type="submit">Continue with Google</button>
      </form>
    </div>
  );
}

7. Protecting routes with Proxy (Next.js 16)

In Next.js 16, middleware.ts was renamed to proxy.ts. The export is proxy instead of middleware:

// src/proxy.ts
import { auth } from "@/auth";
import { NextResponse } from "next/server";

export const proxy = auth((req) => {
  const isLoggedIn = !!req.auth;
  const isProtected =
    req.nextUrl.pathname.startsWith("/dashboard") ||
    req.nextUrl.pathname.startsWith("/chat");

  if (isProtected && !isLoggedIn) {
    const signIn = new URL("/sign-in", req.nextUrl.origin);
    signIn.searchParams.set("callbackUrl", req.nextUrl.pathname);
    return NextResponse.redirect(signIn);
  }
});

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

On Next.js 15 and earlier, name this file middleware.ts and export as middleware instead.

8. Reading the session

In any Server Component or Route Handler:

import { auth } from "@/auth";

// Server Component
export default async function DashboardPage() {
  const session = await auth();
  // session.user.id is available (from our callback above)
  return <div>Hello {session?.user?.name}</div>;
}

// Route Handler
export async function GET() {
  const session = await auth();
  if (!session?.user?.id) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
  // ...
}

9. Run migrations

npx drizzle-kit generate
npx drizzle-kit migrate

Environment variables

# .env.local
AUTH_SECRET=       # openssl rand -hex 32
AUTH_GITHUB_ID=    # github.com/settings/applications
AUTH_GITHUB_SECRET=
AUTH_GOOGLE_ID=    # console.cloud.google.com
AUTH_GOOGLE_SECRET=
DATABASE_URL=      # postgresql://...

Auth.js v5 auto-infers AUTH_GITHUB_ID / AUTH_GITHUB_SECRET for the GitHub provider — you don't need to pass them to GitHub({...}).

That's the complete setup

Everything above is production-ready code. The full stack (auth + Stripe billing + Claude AI + MCP server) is in AgentShip, an open-source AI-native SaaS boilerplate — the private repo has the complete implementation if you want to skip the plumbing entirely.

The 5 pieces of AI plumbing every SaaS needs in 2026 (with code)

mt211211 — Fri, 12 Jun 2026 20:49:51 +0000

Every SaaS is adding AI features in 2026. Most teams burn the first two weeks on the same five pieces of plumbing — none of which are the actual product. Here's each one, with working TypeScript for Next.js 15.

1. A streaming endpoint (not a blocking one)

Users won't stare at a spinner for 20 seconds. Stream tokens as they generate with server-sent events:

// app/api/chat/route.ts
const runner = anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  system: SYSTEM_PROMPT,
  tools,
  messages,
  stream: true,
});

const stream = new ReadableStream({
  async start(controller) {
    for await (const messageStream of runner) {
      for await (const event of messageStream) {
        if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
          controller.enqueue(encode(`data: ${JSON.stringify({ text: event.delta.text })}\n\n`));
        }
      }
    }
    controller.close();
  },
});
return new Response(stream, { headers: { "Content-Type": "text/event-stream" } });

2. Typed tool handlers

The difference between a chatbot and a product is tools — the model acting on your data. Define them once with Zod; the SDK's tool runner handles the execution loop:

export const searchOrders = betaZodTool({
  name: "search_orders",
  description: "Look up a customer's orders. Call when the user asks about order status.",
  inputSchema: z.object({ email: z.string().email() }),
  run: async ({ email }) => db.orders.findByEmail(email),
});

No manual agentic loop, no JSON schema by hand, inputs typed end to end.

3. Usage metering (or users will bankrupt you)

One enthusiastic user on your £10/month plan can generate £200 of API costs. Meter every request and weight output tokens (they cost ~5x input):

export function billableUnits(u: Usage): number {
  return u.input_tokens + (u.cache_read_input_tokens ?? 0) / 10 + u.output_tokens * 5;
}
// After each response:
await recordUsage(userId, billableUnits(message.usage));
// Before each request:
if (await getUsage(userId) > planLimit) return quotaExceeded();

4. Prompt caching that actually caches

Prompt caching can cut input costs ~90% — but it's a prefix match. One interpolated timestamp in your system prompt and you pay full price on every request. Rules:

System prompt is a frozen constant. No dates, no user names, no feature flags in it.
Dynamic context goes in the user message, after the cache breakpoint.
Never change the tool list mid-conversation — tools render at position 0 of the prefix.

export const SYSTEM_PROMPT = [{
  type: "text" as const,
  text: STABLE_INSTRUCTIONS,          // never interpolate into this
  cache_control: { type: "ephemeral" as const },
}];

Verify it works: usage.cache_read_input_tokens should be non-zero from the second request on.

5. A chat component that handles streams properly

Parse the SSE buffer across chunk boundaries — the naive split on every chunk drops tokens:

let buffer = "";
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n\n");
  buffer = lines.pop() ?? "";   // keep the partial event for the next chunk
  for (const line of lines) handleEvent(line);
}

Don't want to write the rest?

All five pieces above are open source (MIT) in agentship-lite — copy them into any Next.js app.

If you want the full SaaS around it — Stripe subscriptions, auth, Postgres schema, plan gating wired to the metering — that's AgentShip, currently £49 early access.