Connect Nuxt and Nitro with Native WebSockets over H3 WebSockets and CrossWS

Introduction

Welcome to part two of our WebSocket series. This tutorial will guide you through setting up WebSocket communication in a Nuxt application using the experimental WebSocket support provided by Nitro, leveraging the defineWebSocketHandler API as documented in the Nitro WebSocket Guide. In part one, we covered the same functionality using socket.io-client and socket.io.

✨ Key Features

• Native WebSocket support in Nuxt and Nitro
• Experimental defineWebSocketHandler API
• Real-time communication capabilities
• Integration with CrossWS for enhanced WebSocket functionality

😌 Easy Setup and Installation

Step 1: Install Nuxt via nuxi

Create a new Nuxt project using nuxi:

npx nuxi init nuxt-crossws-experimental

Then navigate to the project directory:

cd nuxt-crossws-experimental

Step 2: Update Nuxt Dependency

Update the nuxt dependency inside package.json:

{
  "devDependencies": {
    "nuxt": "npm:nuxt-nightly@latest"
  }
}

Install the project dependencies:

pnpm i

Step 3: Install CrossWS

Install the crossws package:

pnpm add crossws

Step 4: Enable Experimental WebSocket Feature

Enable the feature in your nuxt.config.ts file:

export default defineNuxtConfig({
  devTools: { enabled: true },
  nitro: {
    experimental: { websocket: true }
  }
})

🛠 Configuration and Implementation

Setting Up Pages in Nuxt

Nuxt uses the file system as the router by default. Create pages/ and layouts/ directories for automatic route generation.

Create the Home Page

Create pages/index.vue:

<template>
  <div>
    <h1>Welcome to Nuxt with native WebSockets</h1>
    <!-- <WebSocketComponent /> -->
  </div>
</template>

<script setup>
// Component import will be added later
</script>

Create the Default Layout

Create layouts/default.vue:

<template>
  <div>
    <header>
      <h1>My Nuxt App</h1>
    </header>
    <main>
      <slot />
    </main>
    <footer>
      <p>&copy; 2024 My Nuxt App</p>
    </footer>
  </div>
</template>

<style scoped>
header, footer {
  background-color: #333;
  color: white;
  padding: 1rem;
}
footer {
  text-align: center;
}
</style>

Update app.vue

Edit app.vue:

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

Setting Up the WebSocket Server

Create server/api/ws.ts:

import { defineWebSocketHandler } from 'nitropack';

export default defineWebSocketHandler({
  open(peer) {
    console.log("[ws] open", peer);
  },
  message(peer, message) {
    console.log("[ws] message", peer, message);
    if (message.text().includes("ping")) {
      peer.send("pong");
    }
  },
  close(peer, event) {
    console.log("[ws] close", peer, event);
  },
  error(peer, error) {
    console.log("[ws] error", peer, error);
  }
});

Running Your Application

Start your Nuxt application:

pnpm dev

Troubleshooting

Networking over ws and wss and CORS

This setup is a basic example of integrating WebSockets with Nuxt 3 and Nitro. For production environments, consider additional configurations for security, including CORS and authentication.

Resources

• CrossWS Documentation
• Nitro WebSocket Guide
• Example Chatbox by pi0

Conclusion

You've now set up native WebSocket communication in your Nuxt application using the experimental WebSocket support provided by Nitro. This approach offers a more integrated and potentially more efficient way to handle real-time communication in your Nuxt projects.