Next.js 15 App Router × Gemini API: The Complete Full-Stack

// src/app/summary/[slug]/page.tsx
import { getModel } from "@/lib/gemini";
import { getArticleContent } from "@/lib/articles";
 
interface Props {
  params: { slug: string };
}
 
// This entire function runs on the server — no API key exposure
async function generateSummary(content: string): Promise<string> {
  const model = getModel("gemini-2.5-flash"); // Flash for cost savings
  const result = await model.generateContent({
    contents: [
      {
        role: "user",
        parts: [
          {
            text: `Summarize the following article in 3–5 concise sentences, highlighting the key takeaways:\n\n${content}`,
          },
        ],
      },
    ],
    generationConfig: {
      maxOutputTokens: 512,
      temperature: 0.3,
    },
  });
  return result.response.text();
}
 
export default async function SummaryPage({ params }: Props) {
  const article = await getArticleContent(params.slug);
  const summary = await generateSummary(article.content);
 
  return (
    <article>
      <h1>{article.title}</h1>
      {/* AI-generated summary */}
      <div className="bg-blue-50 p-4 rounded-lg">
        <h2 className="font-bold text-blue-800 mb-2">AI Summary</h2>
        <p className="text-blue-700">{summary}</p>
      </div>
      <div dangerouslySetInnerHTML={{ __html: article.html }} />
    </article>
  );
}
 
// ISR: regenerate every hour to control costs
export const revalidate = 3600;

// src/app/api/chat/route.ts
import { google } from "@ai-sdk/google";
import { streamText, convertToCoreMessages } from "ai";
import { NextRequest } from "next/server";
 
// Run on the edge for lower latency
export const runtime = "edge";
 
export async function POST(req: NextRequest) {
  const { messages } = await req.json();
 
  const result = await streamText({
    model: google("gemini-2.5-pro"),
    system: `You are a helpful, knowledgeable AI assistant.
Provide accurate, clear answers in the user's language.
When sharing code, always include a brief explanation.`,
    messages: convertToCoreMessages(messages),
    maxTokens: 2048,
    temperature: 0.7,
    onFinish: async ({ usage, finishReason }) => {
      // Log token usage to your database in production
      console.log("Tokens used:", usage.totalTokens);
      console.log("Finish reason:", finishReason);
    },
  });
 
  return result.toDataStreamResponse();
}

// src/app/chat/page.tsx
"use client";
 
import { useChat } from "ai/react";
 
export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } =
    useChat({
      api: "/api/chat",
      onError: (err) => console.error("Chat error:", err),
    });
 
  return (
    <div className="flex flex-col h-screen max-w-2xl mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">Gemini AI Chat</h1>
 
      <div className="flex-1 overflow-y-auto space-y-4 mb-4">
        {messages.map((message) => (
          <div
            key={message.id}
            className={`flex ${
              message.role === "user" ? "justify-end" : "justify-start"
            }`}
          >
            <div
              className={`max-w-[80%] rounded-lg p-3 ${
                message.role === "user"
                  ? "bg-blue-500 text-white"
                  : "bg-gray-100 text-gray-800"
              }`}
            >
              {/* Text updates in real time as the stream arrives */}
              <p className="whitespace-pre-wrap">{message.content}</p>
            </div>
          </div>
        ))}
 
        {isLoading && (
          <div className="flex justify-start">
            <div className="bg-gray-100 rounded-lg p-3">
              <div className="flex space-x-1">
                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" />
                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce delay-100" />
                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce delay-200" />
              </div>
            </div>
          </div>
        )}
      </div>
 
      {error && (
        <div className="bg-red-50 border border-red-200 text-red-700 p-3 rounded-lg mb-4">
          Something went wrong: {error.message}
        </div>
      )}
 
      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Type a message..."
          disabled={isLoading}
          className="flex-1 border border-gray-300 rounded-lg px-4 py-2 focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <button
          type="submit"
          disabled={isLoading || !input.trim()}
          className="bg-blue-500 text-white px-6 py-2 rounded-lg hover:bg-blue-600 disabled:opacity-50"
        >
          Send
        </button>
      </form>
    </div>
  );
}

// src/app/actions/ai.ts
"use server";
 
import { getModel } from "@/lib/gemini";
import { revalidatePath } from "next/cache";
import { z } from "zod";
 
const generateContentSchema = z.object({
  topic: z.string().min(1).max(500),
  style: z.enum(["blog", "tweet", "email", "summary"]),
});
 
type GenerateContentInput = z.infer<typeof generateContentSchema>;
 
export async function generateContent(input: GenerateContentInput) {
  const validated = generateContentSchema.safeParse(input);
  if (!validated.success) {
    return { error: "Invalid input", details: validated.error.flatten() };
  }
 
  const { topic, style } = validated.data;
 
  const prompts: Record<string, string> = {
    blog: `Write an informative 800-word blog post about: "${topic}". Include a clear introduction, main points with subheadings, and a conclusion.`,
    tweet: `Write three engaging tweets (max 280 chars each) about: "${topic}". Make each one distinct in angle and tone.`,
    email: `Write a professional business email about: "${topic}". Include a subject line and a clear, courteous body.`,
    summary: `Summarize the following topic in under 100 words: "${topic}".`,
  };
 
  try {
    const model = getModel("gemini-2.5-pro");
    const result = await model.generateContent(prompts[style]);
    const content = result.response.text();
    revalidatePath("/dashboard");
    return { success: true, content };
  } catch (error) {
    console.error("Gemini API error:", error);
    return { error: "Content generation failed. Please try again." };
  }
}

// src/app/generate/page.tsx
"use client";
 
import { generateContent } from "@/app/actions/ai";
import { useState, useTransition } from "react";
 
export default function GeneratePage() {
  const [isPending, startTransition] = useTransition();
  const [result, setResult] = useState<string>("");
  const [error, setError] = useState<string>("");
 
  async function handleSubmit(formData: FormData) {
    startTransition(async () => {
      const response = await generateContent({
        topic: formData.get("topic") as string,
        style: formData.get("style") as "blog" | "tweet" | "email" | "summary",
      });
 
      if (response.error) {
        setError(response.error);
      } else {
        setResult(response.content ?? "");
        setError("");
      }
    });
  }
 
  return (
    <div className="max-w-2xl mx-auto p-8">
      <h1 className="text-2xl font-bold mb-6">AI Content Generator</h1>
 
      <form action={handleSubmit} className="space-y-4">
        <div>
          <label className="block font-medium mb-1">Topic</label>
          <input
            name="topic"
            required
            placeholder="e.g. Next.js 15 new features"
            className="w-full border rounded-lg px-4 py-2"
          />
        </div>
 
        <div>
          <label className="block font-medium mb-1">Content Style</label>
          <select name="style" className="w-full border rounded-lg px-4 py-2">
            <option value="blog">Blog Post</option>
            <option value="tweet">Twitter / X Posts</option>
            <option value="email">Business Email</option>
            <option value="summary">Summary</option>
          </select>
        </div>
 
        <button
          type="submit"
          disabled={isPending}
          className="w-full bg-blue-500 text-white py-2 rounded-lg hover:bg-blue-600 disabled:opacity-50"
        >
          {isPending ? "Generating..." : "Generate Content"}
        </button>
      </form>
 
      {error && (
        <div className="mt-4 bg-red-50 text-red-700 p-4 rounded-lg">{error}</div>
      )}
 
      {result && (
        <div className="mt-6">
          <h2 className="font-bold mb-2">Generated Content:</h2>
          <div className="bg-gray-50 p-4 rounded-lg whitespace-pre-wrap">{result}</div>
        </div>
      )}
    </div>
  );
}

// src/lib/rag.ts
import { geminiClient } from "@/lib/gemini";
 
const embeddingModel = geminiClient.getGenerativeModel({
  model: "text-embedding-004",
});
 
export async function embedText(text: string): Promise<number[]> {
  const result = await embeddingModel.embedContent({
    content: { parts: [{ text }], role: "user" },
    taskType: "RETRIEVAL_DOCUMENT",
  });
  return result.embedding.values;
}
 
export async function embedQuery(query: string): Promise<number[]> {
  const result = await embeddingModel.embedContent({
    content: { parts: [{ text: query }], role: "user" },
    taskType: "RETRIEVAL_QUERY",
  });
  return result.embedding.values;
}
 
export function cosineSimilarity(a: number[], b: number[]): number {
  const dot = a.reduce((sum, v, i) => sum + v * b[i], 0);
  const magA = Math.sqrt(a.reduce((s, v) => s + v * v, 0));
  const magB = Math.sqrt(b.reduce((s, v) => s + v * v, 0));
  return dot / (magA * magB);
}
 
interface Document {
  id: string;
  content: string;
  embedding?: number[];
  metadata?: Record<string, unknown>;
}
 
// In-memory vector store — replace with pgvector or Pinecone in production
class SimpleVectorStore {
  private docs: (Document & { embedding: number[] })[] = [];
 
  async add(doc: Document): Promise<void> {
    const embedding = await embedText(doc.content);
    this.docs.push({ ...doc, embedding });
  }
 
  async search(query: string, topK = 3): Promise<Document[]> {
    const qEmbed = await embedQuery(query);
    return this.docs
      .map((d) => ({ d, score: cosineSimilarity(qEmbed, d.embedding) }))
      .sort((a, b) => b.score - a.score)
      .slice(0, topK)
      .map(({ d }) => d);
  }
}
 
export const vectorStore = new SimpleVectorStore();
 
export async function ragAnswer(
  query: string,
  systemPrompt = "You are a helpful AI assistant. Answer based on the provided context."
): Promise<string> {
  const relevant = await vectorStore.search(query, 3);
 
  if (relevant.length === 0) {
    return "No relevant information found for your query.";
  }
 
  const context = relevant
    .map((doc, i) => `[Document ${i + 1}]\n${doc.content}`)
    .join("\n\n");
 
  const model = geminiClient.getGenerativeModel({ model: "gemini-2.5-pro" });
  const prompt = `${systemPrompt}
 
Use the following context to answer the user's question.
If the answer isn't in the context, say so clearly.
 
Context:
${context}
 
Question: ${query}`;
 
  const result = await model.generateContent(prompt);
  return result.response.text();
}

// src/middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
// Use Upstash Redis in production for distributed rate limiting
const requestCounts = new Map<string, { count: number; resetAt: number }>();
 
function checkRateLimit(ip: string, maxReq = 10, windowMs = 60_000): boolean {
  const now = Date.now();
  const current = requestCounts.get(ip);
 
  if (!current || current.resetAt < now) {
    requestCounts.set(ip, { count: 1, resetAt: now + windowMs });
    return true;
  }
  if (current.count >= maxReq) return false;
  current.count++;
  return true;
}
 
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith("/api/")) {
    const ip =
      request.headers.get("x-forwarded-for")?.split(",")[0] ?? "unknown";
 
    if (!checkRateLimit(ip)) {
      return NextResponse.json(
        { error: "Rate limit exceeded. Please wait a minute and try again." },
        { status: 429, headers: { "Retry-After": "60" } }
      );
    }
  }
  return NextResponse.next();
}
 
export const config = { matcher: "/api/:path*" };

// src/lib/gemini-error-handler.ts
import { NextResponse } from "next/server";
 
type GeminiError = { status?: number; message?: string; code?: string };
 
export function handleGeminiError(error: unknown): NextResponse {
  const err = error as GeminiError;
  console.error("Gemini API Error:", err);
 
  if (err.status === 429 || err.code === "RESOURCE_EXHAUSTED") {
    return NextResponse.json(
      { error: "API rate limit reached. Please try again shortly." },
      { status: 429 }
    );
  }
  if (err.status === 401 || err.code === "UNAUTHENTICATED") {
    // Never expose auth details to the client
    return NextResponse.json(
      { error: "Service configuration error." },
      { status: 500 }
    );
  }
  if (err.status === 400 || err.code === "INVALID_ARGUMENT") {
    return NextResponse.json(
      { error: "Invalid input. Please check your request." },
      { status: 400 }
    );
  }
  if (err.status === 503 || err.code === "UNAVAILABLE") {
    return NextResponse.json(
      { error: "Service temporarily unavailable. Please try again later." },
      { status: 503 }
    );
  }
 
  return NextResponse.json({ error: "An unexpected error occurred." }, { status: 500 });
}

npm i -g vercel
vercel
 
# Set environment variables for production
vercel env add GEMINI_API_KEY production
vercel env add GOOGLE_GENERATIVE_AI_API_KEY production

{
  "functions": {
    "src/app/api/chat/route.ts": {
      "maxDuration": 60
    },
    "src/app/api/generate/route.ts": {
      "maxDuration": 30
    }
  },
  "regions": ["iad1", "hnd1"]
}

npm install @opennextjs/cloudflare wrangler
 
# wrangler.toml
cat > wrangler.toml << 'EOF'
name = "my-gemini-app"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]
main = ".open-next/worker.js"
 
[vars]
NEXT_PUBLIC_BASE_URL = "https://my-gemini-app.example.com"
 
[build]
command = "npm run build"
EOF
 
npx wrangler deploy

// src/lib/cached-gemini.ts
import { unstable_cache } from "next/cache";
import { getModel } from "@/lib/gemini";
 
// Cache identical inputs for 1 hour — huge savings for repeated queries
export const cachedGenerateSummary = unstable_cache(
  async (content: string): Promise<string> => {
    const model = getModel("gemini-2.5-flash");
    const result = await model.generateContent(
      `Summarize the following in three sentences or fewer:\n\n${content}`
    );
    return result.response.text();
  },
  ["gemini-summary"],
  {
    revalidate: 3600,
    tags: ["gemini-cache"],
  }
);
 
// Usage
const summary = await cachedGenerateSummary(articleContent);

// src/lib/system-prompts.ts
 
// Generic helpful assistant
export const GENERAL_ASSISTANT = `You are a helpful, knowledgeable AI assistant built on Gemini.
- Be concise but thorough — aim for clarity over length
- When you're unsure, say so rather than guessing
- Format code blocks with the appropriate language tag
- Use bullet points and headers to structure long responses`;
 
// Domain-specific: customer support
export const CUSTOMER_SUPPORT = `You are a customer support specialist for Acme Corp.
- Only answer questions related to our product line
- For billing issues, always direct users to support@acme.com
- Never promise refunds or credits without manager approval
- If a user is frustrated, acknowledge their experience before troubleshooting
- Keep responses under 200 words unless technical depth is required`;
 
// Domain-specific: code reviewer
export const CODE_REVIEWER = `You are an expert code reviewer with deep knowledge of TypeScript, React, and Node.js.
- Identify bugs, security vulnerabilities, and performance issues
- Suggest specific, actionable improvements with code examples
- Explain the "why" behind each recommendation
- Prioritize issues by severity: critical > high > medium > low`;

// src/lib/conversation.ts
import { geminiClient } from "@/lib/gemini";
 
interface Message {
  role: "user" | "model";
  content: string;
}
 
const MAX_HISTORY_TOKENS = 30_000; // Conservative limit for Gemini 2.5 Pro
 
// Rough token estimate: ~4 chars per token for English
function estimateTokens(text: string): number {
  return Math.ceil(text.length / 4);
}
 
function truncateHistory(messages: Message[]): Message[] {
  let totalTokens = 0;
  const truncated: Message[] = [];
 
  // Keep most recent messages first
  for (const msg of [...messages].reverse()) {
    const tokens = estimateTokens(msg.content);
    if (totalTokens + tokens > MAX_HISTORY_TOKENS) break;
    truncated.unshift(msg);
    totalTokens += tokens;
  }
 
  return truncated;
}
 
export async function sendMessage(
  userMessage: string,
  history: Message[],
  systemPrompt: string
): Promise<{ response: string; updatedHistory: Message[] }> {
  const model = geminiClient.getGenerativeModel({
    model: "gemini-2.5-pro",
    systemInstruction: systemPrompt,
  });
 
  const truncatedHistory = truncateHistory(history);
 
  const chat = model.startChat({
    history: truncatedHistory.map((msg) => ({
      role: msg.role,
      parts: [{ text: msg.content }],
    })),
  });
 
  const result = await chat.sendMessage(userMessage);
  const responseText = result.response.text();
 
  const updatedHistory: Message[] = [
    ...truncatedHistory,
    { role: "user", content: userMessage },
    { role: "model", content: responseText },
  ];
 
  return { response: responseText, updatedHistory };
}

// src/lib/__tests__/gemini.test.ts
import { jest } from "@jest/globals";
 
// Mock the entire SDK before imports
jest.mock("@google/generative-ai", () => ({
  GoogleGenerativeAI: jest.fn().mockImplementation(() => ({
    getGenerativeModel: jest.fn().mockReturnValue({
      generateContent: jest.fn().mockResolvedValue({
        response: {
          text: () => "Mocked AI response for testing",
        },
      }),
    }),
  })),
}));
 
// Now import your module — it will use the mock
import { getModel } from "@/lib/gemini";
 
describe("Gemini integration", () => {
  it("should call generateContent with the correct prompt", async () => {
    const model = getModel("gemini-2.5-flash");
    const result = await model.generateContent("Test prompt");
    expect(result.response.text()).toBe("Mocked AI response for testing");
  });
});

// src/lib/__tests__/rag.integration.test.ts
// Run with: RECORD_MODE=true npm test to capture real responses
// Then commit the fixtures and run without the flag in CI
 
const FIXTURES_PATH = "__fixtures__/rag-responses.json";
 
async function getOrRecordResponse(
  prompt: string,
  key: string
): Promise<string> {
  if (process.env.RECORD_MODE === "true") {
    const model = getModel("gemini-2.5-flash");
    const result = await model.generateContent(prompt);
    const response = result.response.text();
    // Save to fixtures file (simplified — use proper file handling in practice)
    console.log(`Record: ${key} =`, response);
    return response;
  }
 
  // Load from fixtures in normal mode
  const fixtures = require(FIXTURES_PATH);
  if (!fixtures[key]) throw new Error(`No fixture for key: ${key}`);
  return fixtures[key];
}
 
describe("RAG pipeline", () => {
  it("should return relevant answers from context", async () => {
    const answer = await getOrRecordResponse(
      "What is Next.js App Router?",
      "nextjs-app-router-definition"
    );
    expect(answer.length).toBeGreaterThan(50);
    expect(answer.toLowerCase()).toContain("next");
  });
});

// e2e/chat.spec.ts (Playwright)
import { test, expect } from "@playwright/test";
 
test("chat interface streams a response", async ({ page }) => {
  await page.goto("/chat");
 
  // Type a message
  await page.getByPlaceholder("Type a message...").fill("What is 2 + 2?");
  await page.getByRole("button", { name: "Send" }).click();
 
  // Wait for streaming to complete (AI response appears)
  await expect(page.locator(".bg-gray-100").last()).toContainText("4", {
    timeout: 30_000, // AI responses can take time
  });
 
  // Verify the loading indicator disappears
  await expect(page.locator(".animate-bounce").first()).not.toBeVisible();
});

// src/lib/usage-tracker.ts
interface UsageRecord {
  timestamp: Date;
  model: string;
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  latencyMs: number;
  userId?: string;
}
 
// In production, replace with a database write (Postgres, Planetscale, etc.)
const usageLog: UsageRecord[] = [];
 
export function trackUsage(record: UsageRecord): void {
  usageLog.push(record);
  // Log to your observability platform (Datadog, Grafana, etc.)
  console.log(
    JSON.stringify({
      event: "gemini_api_call",
      ...record,
    })
  );
}
 
// Wrap your API calls with timing
export async function trackedGenerateContent(
  model: ReturnType<typeof import("@/lib/gemini").getModel>,
  prompt: string,
  userId?: string
) {
  const start = Date.now();
 
  try {
    const result = await model.generateContent(prompt);
    const usage = result.response.usageMetadata;
 
    trackUsage({
      timestamp: new Date(),
      model: "gemini-2.5-pro",
      promptTokens: usage?.promptTokenCount ?? 0,
      completionTokens: usage?.candidatesTokenCount ?? 0,
      totalTokens: usage?.totalTokenCount ?? 0,
      latencyMs: Date.now() - start,
      userId,
    });
 
    return result;
  } catch (error) {
    console.error("Gemini API error after", Date.now() - start, "ms:", error);
    throw error;
  }
}

// src/app/api/admin/usage/route.ts
import { NextRequest, NextResponse } from "next/server";
import { getServerSession } from "next-auth";
 
export async function GET(req: NextRequest) {
  // Protect this endpoint — only allow admin users
  const session = await getServerSession();
  if (!session || session.user?.role !== "admin") {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }
 
  // In production, query your database
  // const usage = await db.query("SELECT * FROM usage_log WHERE timestamp > NOW() - INTERVAL '24 hours'");
 
  return NextResponse.json({
    message: "Usage data endpoint — connect to your database here",
    periodHours: 24,
  });
}

// src/app/dashboard/page.tsx
import { Suspense } from "react";
import { AiInsights } from "@/components/AiInsights";
import { StaticHeader } from "@/components/StaticHeader";
 
// Opt into PPR for this route
export const experimental_ppr = true;
 
export default function DashboardPage() {
  return (
    <main>
      {/* Rendered immediately from CDN cache */}
      <StaticHeader />
 
      {/* Streamed in dynamically after initial page load */}
      <Suspense fallback={<div className="animate-pulse h-32 bg-gray-100 rounded" />}>
        <AiInsights />
      </Suspense>
    </main>
  );
}

// next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  experimental: {
    ppr: true,
  },
};
 
export default nextConfig;