⚡ High-Performance Autocomplete API

Built with Next.js 15, TypeScript, TailwindCSS, Hono, Upstash Redis, and the Edge Runtime

           

Deployed on Vercel via GitHub

---

☁️ Live Demo: https://fast-api-nextjs-hono-redis.vercel.app

This project is a high-performance search engine built with modern technologies. It delivers real-time country autocomplete with millisecond-level response times, powered by a TypeScript-based Next.js 15 application, the lightweight Hono framework, Upstash Redis, and the Edge Runtime. The frontend uses Command UI and TailwindCSS to provide a clean, fast, and responsive interface.

---

🚀 Key Features

⚡ Ultra-Fast Autocomplete API

• Powered by Redis Sorted Sets (ZADD, ZRANK, ZRANGE).
• Typical responses are delivered within milliseconds.
• Perfect for search bars, smart suggestions, and real-time filtering.

✅ Redis-Backed Cache Layer

• Each search query is cached under: search:<QUERY>.
• Cache expiry: 1 hour.
• API responses include: fromCache: true | false.

🌍 Global Edge Runtime + Rate Limiting

• API runs on the Vercel Edge Network for minimal global latency.
• Consistent low-latency performance across all regions.
• Rate limited to 30 requests per minute per IP.
• Implemented using hono-rate-limiter.

🎨 Modern, Responsive UI

• Built with Command UI (cmdk) from shadcn/ui.
• Includes a debounced 20 ms search input to reduce API load.
• Clean, modern design powered by TailwindCSS.
• Component-driven, fully reusable, and optimized for performance.

---

📘 Technology Stack Overview

The following technologies are used in this project:

Layer	Technologies	Description
Frontend (UI Layer)	Next.js 15, React, TailwindCSS, Command UI	Builds the user interface with modern, responsive components.
API Layer	Hono	Handles API routes quickly with a lightweight framework.
Runtime Layer	Edge Runtime	Runs API code at global edge locations for low-latency responses.
Data Layer	Upstash Redis	Stores country data and powers fast autocomplete queries.
Development Tools	TypeScript, Turbopack, ESLint, Vitest	Provides typing, fast builds, linting, and testing.
Deployment	Vercel	Hosts the app with automatic scaling and fast global delivery.
Utilities	TSX, Zod	Used for scripts and environment variable validation.

---

📁 Project Structure

The following project structure is used in this project:

fast-api-nextjs-hono-redis/
├── node_modules/
├── src/
│ ├── app/
│ │ ├── api/[[...route]]/route.ts      # Hono API handler
│ │ ├── global.css
│ │ ├── layout.tsx
│ │ └── page.tsx                       # Frontend UI
│ ├── components/
│ │ ├── ui/                            # Reusable UI components (shadcn/cmdk/etc.)
│ │ └── Footer.tsx
│ ├── hooks/
│ │ └── useDebounce.ts
│ ├── lib/
│ │ ├── db.ts                          # Redis client
│ │ ├── env.ts                         # Zod environment validation
│ │ └── utils.ts
│ └── scripts/
│ │ └── seedCountries.ts               # Seeder for Redis
├── tests/                             # Test files
│ ├── mocks/
│ ├── server/
│ └── api.search.test.ts
├── .env                               # Environment variables (not committed to Git)
├── .gitignore
├── package.json                       # Project metadata and dependencies
└── README.md

---

📦 Getting Started

Follow the steps below to set up and run the project properly:

1. ✅ Clone the Repository:

https://github.com/PAIshanMadusha/fast-api-nextjs-hono-redis.git

2. ✅ Navigate to the Project Directory:

cd fast-api-nextjs-hono-redis

3. ✅ Create the .env File:

Create a .env file in the root directory of the project and include the following values:

UPSTASH_REDIS_REST_URL="your-upstash-url"
UPSTASH_REDIS_REST_TOKEN="your-upstash-token"
NEXT_PUBLIC_API_URL=http://localhost:3000

---

🔐 Environment Variable Details:

Key	Description
UPSTASH_REDIS_REST_URL	After creating a Redis database in Upstash, copy the REST API URL from the dashboard and paste it here.
UPSTASH_REDIS_REST_TOKEN	Copy the REST API token from the same Upstash dashboard and paste it here.
NEXT_PUBLIC_API_URL	The public URL of your application. Use http://localhost:3000 during local development. This value must be updated to the Vercel URL after deployment.

---

4. ✅ Install Dependencies:

npm install

5. 🍥 Redis Seeding (Countries Autocomplete):

The project includes a complete Redis seeding script, Run it with:

npm run seed

6. ✅ Run the App Locally:

npm run dev

7. ⚡ Successful Startup Output:

If everything is configured properly, your terminal should display something like this:

▲ Next.js 15.5.4 (Turbopack)
- Local:        http://localhost:3000
- Network:      http://your-ip-address:3000
- Environments: .env

Your app will be available at: http://localhost:3000

8. 🧪 Run tests:

Execute the API test suite with:

npm run test

9. ✅ Build for Production:

npm run build

---

⭐ Scripts Reference

Use the following commands to run and manage the application in both development and production:

Script	Description
npm run dev	Run local development
npm run build	Production build (Turbopack)
npm run start	Start production
npm run seed	Seed countries into Redis
npm run lint	Run ESLint
npm run test	Run Vitest test suite

📸 System Screenshots

These screenshots illustrate how the system appears on desktop:

---

---

❤️ Author:

Ishan Madhusha
GitHub: PAIshanMadusha

Feel free to explore my work and get in touch if you'd like to collaborate! 🚀

---

📝 License

This project is licensed under the MIT License : See the LICENSE file for details.