Message Queue with AWS ElastiCache and Next.js

Message Queue with AWS ElastiCache and Next.js is a Vercel starter that implements a reliable message queue with Valkey streams, exposed through Next.js API Routes and a two-page Tailwind CSS UI.

What is the Message Queue with AWS ElastiCache and Next.js template?

This is a starter from Vercel's examples collection that demonstrates how to process messages asynchronously using AWS ElastiCache for Valkey (version 7.0+) and Next.js API Routes. It accepts contact-form submissions as input, writes them to a Valkey stream named contact-messages, and exposes one API route with three HTTP methods: POST to produce, GET to consume, and DELETE to acknowledge. The output is JSON plus a browser UI for submitting and reviewing messages. The template runs on Vercel with Next.js and uses Tailwind CSS for styling.

What makes it stand out?

Valkey stream consumer group — A single consumer group named contact-processors prevents duplicate delivery across consumers, and messages idle for more than 60 seconds are automatically reclaimed.

Complete API route — /api/messages implements the full produce-consume-acknowledge cycle in one route, returning stream message IDs and timestamp metadata.

Two UI views — The home page at / contains the contact form; the processing page at /process reads the next message, shows a warning banner when a message was reclaimed, and offers an Acknowledge button.

Local development setup — Run valkey/valkey:latest via Docker and set VALKEY_ENDPOINT=localhost:6379; the README documents curl commands for the full flow.

One-click Vercel deploy — The deploy button clones the repo, sets the VALKEY_ENDPOINT environment variable, and creates a live demo.

Production VPC guidance — The template explains how to connect Vercel Functions to an ElastiCache cluster inside an AWS VPC using Vercel Secure Compute for Enterprise accounts.

Who should use this template?

Full-stack developers wanting a reference implementation of stream-based queues in Next.js to reuse in their own serverless apps.

Teams running AWS ElastiCache looking for a proven message-queue pattern with at-least-once delivery semantics and consumer failure recovery.

Developers learning Valkey who want a concrete example of streams, consumer groups, and the Pending Entries List.

Vercel Enterprise customers who need a working blueprint for private network access to AWS resources via Secure Compute.

What can you do with it?

Store contact form submissions — POST name, email, and message to the stream, then consume and acknowledge them from a reviewer UI without losing data on refresh.

Build a failover demo — Fetch a message but skip the DELETE step, then watch the next GET return it with claimed: true after 60 seconds, illustrating consumer recovery.

Prototype a task queue — Replace the contact form with any job payload (URL, user ID, or JSON) using the same producer, consumer, and acknowledgment endpoints.

How does the message queue flow work?

A visitor submits the form, which calls POST /api/messages and appends an entry to the stream. The processing page then calls GET /api/messages, which reads the next unread entry from the contact-processors consumer group and moves it to the Pending Entries List. Clicking Acknowledge sends DELETE with the streamMessageId, removing the entry from the stream. If a message is never acknowledged, GET automatically reclaims it after 60 seconds of idle time, and the response marks it with claimed: true.

Pros and cons

Pros:

• Small, focused code base ideal for studying a real queue pattern rather than using a managed queue service.
• Includes a local Docker workflow and a clear API contract that can be tested with curl.
• Demonstrates a reliability feature (idle-message reclaim) that most hello-world queue examples omit.

Cons:

• The demo endpoint has no authentication; the README explicitly warns to add auth middleware before production use.
• Production deployment to Vercel requires an Enterprise plan with Secure Compute to reach ElastiCache inside a VPC, so it is not deployable on the free or Pro tier against AWS.

FAQ

Does the template work without AWS?

Yes. Locally you run Valkey with Docker and set VALKEY_ENDPOINT=localhost:6379. The same code works against any Valkey-compatible endpoint; AWS ElastiCache is only needed for production deployments on Vercel.

Is the template free?

The template itself is free and open-source from Vercel examples. Running it requires your own Valkey or ElastiCache instance, and production Vercel connectivity requires an Enterprise plan with Secure Compute.

How does the queue avoid duplicate processing?

A single consumer group ensures each message is delivered to only one consumer. GET moves a message into the Pending Entries List, and only DELETE removes it. Refreshing the page does not return an already-claimed message unless it has been idle over 60 seconds.

What does claimed: true mean?

It indicates the message was previously delivered but not acknowledged and has been recovered from the Pending Entries List after 60 seconds of idle time. This is the automatic reclaim behavior that protects against stuck messages.

How can I reset the queue during testing?

In the Valkey container, run valkey-cli, then DEL contact-messages to delete the stream and its consumer group, or XGROUP DESTROY contact-messages contact-processors to remove only the group. The consumer group is recreated automatically on the next GET request.