Rust WebSocket

Rust WebSocket is a starter template from Vercel that demonstrates how to deploy a WebSocket server written in Rust on the Vercel platform using the Axum web framework. It is a minimal example that covers the full setup: a WebSocket endpoint, a client page, and the configuration needed to run on Vercel's Rust runtime.

What is Rust WebSocket?

This template is a minimal Axum-based WebSocket server designed to run on Vercel's Rust runtime. It takes incoming HTTP connections at the /ws endpoint, upgrades them to WebSocket, and then simultaneously pushes a tick heartbeat every second and echoes back any message the client sends. The server is published by Vercel and is part of the vercel/examples repository, which contains other Rust templates like rust-axum and rust-hello-world.

Key Features

• WebSocket support on Vercel — The Vercel Rust runtime enables HTTP/1.1 upgrades, so Axum's WebSocketUpgrade extractor works without extra configuration.
• Dual message flow — A single writer task owns the WebSocket sink and is fed by an mpsc channel, allowing both a heartbeat generator and an echo loop to send frames concurrently without sharing the non-clonable sink.
• Interactive test client — index.html provides a live log that renders all server messages tagged with a type field (welcome, echo, tick).
• Simple project structure — The entire app lives in api/websocket.rs, with Cargo.toml for dependencies and vercel.json rewriting all routes to the function.
• Embedded HTML — The client page is embedded via include_str!, keeping the deployment to a single function file.

Who is it for?

• Rust developers wanting to learn how to run stateful WebSocket services on serverless platforms like Vercel.
• Developers building real-time apps (chat, live notifications, dashboards) who need a reference implementation for handling concurrent WebSocket writes in Axum.
• Vercel users who want to test the platform's support for WebSocket upgrades using a small, ready-to-deploy example.

What can you do with Rust WebSocket?

• Build a live demo: Deploy the template to Vercel, connect via the included HTML page, and observe welcome, tick, and echo events in real time.
• Prototype server-push features: Use the heartbeat loop as a pattern for pushing periodic updates from the server to connected clients.
• Learn Axum patterns: Study how the mpsc channel design lets multiple tasks share a single WebSocket sink, a common challenge in async Rust.

How does it work?

The api/websocket.rs file defines an Axum router with two routes: GET / serves the interactive HTML client, and GET /ws handles the WebSocket upgrade. After upgrade, the handler spawns two concurrent tasks — a heartbeat that sends a tick message every second and an echo loop that mirrors client messages — both feeding into a single writer task through an mpsc channel. To run locally, install Rust, clone the repository, and run vc dev.

FAQ

Does Rust WebSocket work on Vercel?

Yes. The template leverages Vercel's Rust runtime for serverless functions, which supports HTTP/1.1 upgrades. This allows Axum's WebSocketUpgrade to function without any extra configuration on the platform.

What messages does the server send?

The server sends three types of JSON messages: welcome when a client connects, tick every second from the heartbeat, and echo that mirrors any text the client sends. All messages include a type field for easy handling on the client side.

How do I run this template locally?

Clone the vercel/examples repository, navigate to the rust/websocket directory, install Rust, and run vc dev (requires Vercel CLI). Open the printed URL, click Connect, and send messages to see the log.

Does the template require a specific Rust version?

The page does not specify a minimum Rust version, but it requires standard tools like Cargo and rustup. The dependencies are defined in Cargo.toml, so building the project resolves them automatically.