Gemini Chatbot Toolkit

A small, real AI chatbot repository powered by the official Google Gemini API. It is designed to work on its own and to be copied into an existing hackathon project with minimal changes.

What it does

The app provides a responsive chat interface for general-purpose questions, including explanations, coding, math, writing, planning, brainstorming, and everyday questions. It keeps the current conversation in browser memory and sends that history to Gemini for every new turn.

It does not claim to know live information. Current events, live prices, and other time-sensitive questions may require a separate search or tools integration.

Stack and architecture

• Next.js App Router with TypeScript and React.
• app/page.tsx: client-side chat UI and in-session message state.
• app/api/chat/route.ts: server-side API route. It validates the request, reads GEMINI_API_KEY, sends the conversation to Gemini using @google/genai, and returns the model response.
• app/globals.css: dependency-free responsive styling.
• prompts/integration-agent-prompt.md: ready-to-copy instructions for integrating the chatbot into another project.

The browser never receives the API key. The client only calls /api/chat; the server route calls Gemini.

Requirements

• Node.js 18.18 or newer.
• A Gemini API key from Google AI Studio.

Run locally

pnpm install
copy .env.example .env.local

Add your key to .env.local:

GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-3.8-flash
GEMINI_FALLBACK_MODELS=gemini-3.7-flash,gemini-3.6-flash

GEMINI_MODEL and GEMINI_FALLBACK_MODELS are optional. If the primary model is temporarily busy, the server retries the configured fallback models. Keep GEMINI_API_KEY server-only: do not rename it with a NEXT_PUBLIC_ prefix and do not place it in client code.

Start the app:

pnpm dev

Open http://localhost:3000.

Test it

1. Run pnpm lint to run the TypeScript check.
2. Run pnpm build to verify the production build.
3. Run pnpm dev, open the browser, and send a question.
4. Ask a follow-up such as “What was the main point of my last question?” to verify conversation context.
5. Stop the server, remove the key, restart, and confirm the UI shows a helpful configuration error.
6. Check that .env.local is ignored by Git and that no source file contains the key.

Integration into an existing project

Start with the main project. Identify its framework, language, frontend and backend structure, package manager, routing, and environment-variable conventions. Then inspect this repository and choose the smallest compatible strategy.

Next.js / React / TypeScript

Copy or adapt app/api/chat/route.ts into the existing App Router API route structure. Reuse the request validation and GoogleGenAI call. Adapt app/page.tsx and app/globals.css to the existing component and styling conventions. Add GEMINI_API_KEY to the main project's environment file.

React + Vite

Keep the chat component in the Vite client, but do not move the Gemini call into the browser. Add a small server endpoint using the project's existing backend, or add a compatible serverless function. The Vite client should call that endpoint with the message history. Use the project's existing .env convention only for public client values; keep the Gemini key in the server environment.

Vanilla HTML/CSS/JavaScript

Adapt the markup, styles, and browser event logic from app/page.tsx into the existing page. Add a server endpoint in the existing backend or hosting platform's function format. The browser calls that endpoint; it must not call Gemini directly with the secret key.

Node.js / Express

Reuse the validation and Gemini call from app/api/chat/route.ts in an Express POST /api/chat handler. Put GEMINI_API_KEY in the server process environment. Serve or embed the UI using the existing frontend approach.

Other stacks

Preserve the host project's framework and conventions. The portable contract is simple: send { "messages": [{ "role": "user" | "model", "text": "..." }] } to a server-side POST /api/chat endpoint and receive { "message": { "role": "model", "text": "..." } } or { "error": "..." }.

Important integration files are app/api/chat/route.ts for server behavior, app/page.tsx for interaction behavior, app/globals.css for styling, .env.example for configuration, and prompts/integration-agent-prompt.md for the integration workflow.

Vercel deployment

When the integrated project is deployed to Vercel:

1. Open the Vercel project settings.
2. Add GEMINI_API_KEY under Environment Variables for Development, Preview, and Production as appropriate.
3. Optionally add GEMINI_MODEL if a different supported model is needed.
4. Redeploy after adding or changing environment variables when Vercel requires it.

Never commit the key to GitHub, expose it through NEXT_PUBLIC_*, or send it to the browser. Restrict the API key in Google AI Studio where possible.

Customization

The UI is intentionally dependency-free. Change the colors, spacing, typography, and responsive rules in app/globals.css. Change the assistant behavior in the systemInstruction inside app/api/chat/route.ts. Keep the server boundary intact when customizing the UI.

Recommended hackathon-day workflow

1. Give Codex the main project URL and this repository URL.
2. Ask Codex to read prompts/integration-agent-prompt.md and follow it.
3. Let Codex inspect the main project before editing anything.
4. Have it reuse the server route and client behavior using the main project's own framework and package manager.
5. Add GEMINI_API_KEY to the main project's local and deployment environment settings.
6. Test a first question, a context-dependent follow-up, a clear-chat action, and the missing-key error.
7. Run the main project's type check, lint, build, and the smallest practical browser/API smoke test.
8. Review the changed-file list and confirm no secrets were added.

The goal is a working feature with minimal edits during the three-hour window, not a framework migration or a new product subsystem.

Official Gemini reference

This project uses the current @google/genai JavaScript SDK style documented by Google: Generate content with the Gemini API.