Back to Skills

Bun Websocket Server

This skill should be used when the user asks about "WebSocket in Bun", "real-time communication", "Bun.serve websocket", "ws server", "socket connections", "pub/sub", "broadcasting messages", "WebSocket upgrade", or building real-time applications with Bun.

By secondsky
21030Updated 5 days agoTypeScriptMIT

Skill Content

# Bun WebSocket Server

Bun has built-in WebSocket support integrated with `Bun.serve()`.

## Quick Start

```typescript
const server = Bun.serve({
  fetch(req, server) {
    // Upgrade to WebSocket
    if (server.upgrade(req)) {
      return; // Upgraded successfully
    }
    return new Response("Not a WebSocket request", { status: 400 });
  },
  websocket: {
    open(ws) {
      console.log("Client connected");
    },
    message(ws, message) {
      console.log("Received:", message);
      ws.send(`Echo: ${message}`);
    },
    close(ws) {
      console.log("Client disconnected");
    },
  },
});

console.log(`WebSocket server running on ws://localhost:${server.port}`);
```

## WebSocket Handlers

```typescript
Bun.serve({
  fetch(req, server) {
    server.upgrade(req);
  },
  websocket: {
    // Client connected
    open(ws) {
      console.log("New connection");
    },

    // Message received
    message(ws, message) {
      // message is string | Buffer
      if (typeof message === "string") {
        console.log("Text:", message);
      } else {
        console.log("Binary:", message);
      }
    },

    // Connection closed
    close(ws, code, reason) {
      console.log(`Closed: ${code} - ${reason}`);
    },

    // Drain event (buffer flushed)
    drain(ws) {
      console.log("Buffer drained");
    },

    // Ping received
    ping(ws, data) {
      // Pong sent automatically
    },

    // Pong received
    pong(ws, data) {
      console.log("Pong received");
    },
  },
});
```

## Sending Messages

```typescript
websocket: {
  message(ws, message) {
    // Send text
    ws.send("Hello");

    // Send JSON
    ws.send(JSON.stringify({ type: "greeting", data: "Hello" }));

    // Send binary
    ws.send(new Uint8Array([1, 2, 3]));
    ws.send(Buffer.from("binary data"));

    // Send with compression
    ws.send("compressed message", true);

    // Check if buffer is full
    const bufferedAmount = ws.send("data");
    if (bufferedAmount > 1024 * 1024) {
      console.log("Buffer getting full");
    }
  },
}
```

## Attaching Data to Connections

```typescript
interface UserData {
  id: string;
  name: string;
  joinedAt: Date;
}

Bun.serve<UserData>({
  fetch(req, server) {
    const url = new URL(req.url);
    const userId = url.searchParams.get("userId");

    // Attach data during upgrade
    server.upgrade(req, {
      data: {
        id: userId,
        name: "User " + userId,
        joinedAt: new Date(),
      },
    });
  },
  websocket: {
    open(ws) {
      // Access attached data
      console.log(`${ws.data.name} connected`);
    },
    message(ws, message) {
      console.log(`${ws.data.name}: ${message}`);
    },
  },
});
```

## Pub/Sub (Topics)

```typescript
Bun.serve({
  fetch(req, server) {
    const url = new URL(req.url);
    const room = url.searchParams.get("room") || "general";

    server.upgrade(req, {
      data: { room },
    });
  },
  websocket: {
    open(ws) {
      // Subscribe to a topic
      ws.subscribe(ws.data.room);

      // Publish to topic (excludes sender)
      ws.publish(ws.data.room, `User joined ${ws.data.room}`);
    },
    message(ws, message) {
      // Broadcast to all in room (excludes sender)
      ws.publish(ws.data.room, message);
    },
    close(ws) {
      // Unsubscribe (automatic on close)
      ws.unsubscribe(ws.data.room);
      ws.publish(ws.data.room, "User left");
    },
  },
});
```

## Broadcasting to All Clients

```typescript
Bun.serve({
  fetch(req, server) {
    server.upgrade(req);
  },
  websocket: {
    open(ws) {
      // Subscribe to global topic
      ws.subscribe("global");
    },
    message(ws, message) {
      // Broadcast to ALL clients including sender
      server.publish("global", message);
    },
  },
});
```

## Server-Level Publish

```typescript
const server = Bun.serve({
  fetch(req, server) {
    const url = new URL(req.url);

    // HTTP endpoint to publish
    if (url.pathname === "/broadcast") {
      const message = url.searchParams.get("msg");
      server.publish("global", message);
      return new Response("Broadcasted");
    }

    server.upgrade(req);
  },
  websocket: {
    open(ws) {
      ws.subscribe("global");
    },
  },
});

// Can also publish from outside fetch
setInterval(() => {
  server.publish("global", `Server time: ${new Date().toISOString()}`);
}, 5000);
```

## WebSocket Options

```typescript
Bun.serve({
  websocket: {
    // Max message size (default 16MB)
    maxPayloadLength: 1024 * 1024, // 1MB

    // Idle timeout in seconds (default 120)
    idleTimeout: 60,

    // Backpressure limit
    backpressureLimit: 1024 * 1024,

    // Enable compression
    perMessageDeflate: true,
    // Or with options
    perMessageDeflate: {
      compress: "shared",
      decompress: "shared",
    },

    // Send/receive pings
    sendPings: true,

    // Handlers
    open(ws) {},
    message(ws, message) {},
    close(ws) {},
  },
});
```

## Client-Side Connection

```javascript
// Browser
const ws = new WebSocket("ws://localhost:3000");

ws.onopen = () => {
  ws.send("Hello Server!");
};

ws.onmessage = (event) => {
  console.log("Received:", event.data);
};

ws.onclose = () => {
  console.log("Disconnected");
};
```

## Authentication

```typescript
Bun.serve({
  fetch(req, server) {
    // Verify auth before upgrade
    const token = req.headers.get("Authorization");

    if (!verifyToken(token)) {
      return new Response("Unauthorized", { status: 401 });
    }

    const user = decodeToken(token);
    server.upgrade(req, {
      data: { userId: user.id },
    });
  },
  websocket: {
    open(ws) {
      console.log(`Authenticated user ${ws.data.userId} connected`);
    },
  },
});
```

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Upgrade failed` | Invalid request | Check upgrade headers |
| `Connection closed` | Client disconnect | Handle in close handler |
| `Message too large` | Exceeds maxPayloadLength | Increase limit or chunk data |
| `Backpressure` | Slow client | Check buffer, wait for drain |

## Common Patterns

### Chat Room

```typescript
Bun.serve({
  fetch(req, server) {
    const url = new URL(req.url);
    const username = url.searchParams.get("user") || "Anonymous";

    server.upgrade(req, {
      data: { username },
    });
  },
  websocket: {
    open(ws) {
      ws.subscribe("chat");
      ws.publish("chat", `${ws.data.username} joined`);
    },
    message(ws, message) {
      ws.publish("chat", `${ws.data.username}: ${message}`);
    },
    close(ws) {
      ws.publish("chat", `${ws.data.username} left`);
    },
  },
});
```

## When to Load References

Load `references/compression.md` when:
- perMessageDeflate configuration
- Compression tuning
- Binary message handling

Load `references/scaling.md` when:
- Multiple server instances
- Redis pub/sub integration
- Horizontal scaling

How to use

  1. Copy the skill content above
  2. Create a .claude/skills/claude-skills-bun-websocket-server directory in your project (or ~/.claude/skills/claude-skills-bun-websocket-server to use it in every project)
  3. Save the content as .claude/skills/claude-skills-bun-websocket-server/SKILL.md
  4. Claude Code loads it automatically when the task matches, or run /claude-skills-bun-websocket-server to invoke it directly

README

View on GitHub

Claude Code Skills Collection

142 production-ready skills for Claude Code CLI

Version 3.6.3 | Last Updated: 2026-08-06

<div align="center">

šŸ”Œ Platform / Harness Support

These plugins ship as Claude Code marketplace plugins (.claude-plugin/ manifests) and Codex CLI plugins (.codex-plugin/ manifests). Other harnesses consume the same skills via skills.sh ā€” the cross-harness bridge.

HarnessMarketplace supportHow to install
Claude Codeāœ… Native (federated)/plugin marketplace add secondsky/claude-skills, then /plugin install <name>@claude-skills
ZCodeāœ… Native (reads .claude-plugin/ manifests)Add this repo as a marketplace in the ZCode GUI
Codex CLIāœ… Native (federated)codex plugin marketplace add secondsky/claude-skills, then /plugins in the Codex TUI
Cursorāš ļø Adaptation neededCursor has an official marketplace, but expects .cursor-plugin/plugin.json (UI "Add to Cursor") this repo does not generate yet. Use skills.sh.
opencodeāŒ No marketplacenpm plugins only (opencode.json plugin[]). Use skills.sh or vendor manually.
Gemini CLIāŒ No marketplacegemini extensions install <url> only. Use skills.sh or vendor manually.
</div>

A curated collection of battle-tested skills for building modern web applications with Cloudflare, AI integrations, React, Tailwind, and more.

Quick Start

Marketplace Installation (Recommended)

# Add the marketplace
/plugin marketplace add https://github.com/secondsky/claude-skills

# Install individual skills as needed
/plugin install cloudflare-d1@claude-skills
/plugin install tailwind-v4-shadcn@claude-skills
/plugin install gemini-cli@claude-skills

See MARKETPLACE.md for complete catalog of all 142 skills.

Codex CLI Installation

This repo generates .codex-plugin/ manifests and a .agents/plugins/marketplace.json for all 142 plugins, so Codex CLI can install them natively:

# Add the marketplace (from GitHub)
codex plugin marketplace add secondsky/claude-skills

# Browse and install plugins in the Codex TUI
#   /plugins          # opens the plugin browser
#   Space             # enable/disable a plugin

Skills are auto-discovered from each plugin's skills/ directory ā€” the same SKILL.md files Claude Code uses. Claude-specific slash commands and subagents are not carried into Codex (use Codex's /import command for that).

Installing with skills.sh

skills.sh is an open agent-skills registry and npx skills CLI (maintained by Vercel) that auto-detects your coding agent ā€” Claude Code, Cursor, Codex, Copilot, Cline, opencode, and 70+ others ā€” and installs each skill into the correct directory for that harness. It is the universal cross-harness path for harnesses without a marketplace (opencode, Gemini CLI) or where this repo's manifest format isn't generated yet (Cursor).

# Install one skill (auto-detects your agent)
npx skills add secondsky/claude-skills --skill cloudflare-d1

# Install several specific skills
npx skills add secondsky/claude-skills --skill cloudflare-d1 --skill tailwind-v4-shadcn

# Try a skill once without installing (pipes its prompt to your agent)
npx skills use secondsky/claude-skills@cloudflare-d1 | claude

# Target a specific agent explicitly
npx skills add secondsky/claude-skills --skill cloudflare-d1 --agent codex

# List what's installed, search, update, remove
npx skills ls -g
npx skills find cloudflare
npx skills update cloudflare-d1
npx skills remove cloudflare-d1

Bulk install note: npx skills add secondsky/claude-skills --all installs every discovered skill at once, but discovery walks skills.sh's standard container directories (skills/, .claude/skills/, ā€¦). This repo nests skills under plugins/<name>/skills/<skill>/, so --all may not pick up everything in one pass ā€” install the skills you need by name with --skill, or run npx skills add secondsky/claude-skills -l to list what it finds.

Security scanning caveat

skills.sh runs every published skill through three scanners (Gen Agent Trust Hub, Socket, Snyk) plus an LLM-based meta-analyzer, and publishes the results at skills.sh/audits. The LLM analysis stage has been publicly shown (Trail of Bits, June 2026) to both miss genuinely malicious skills and flag unfamiliar version pins (e.g. newest dependency versions) as suspicious false positives. Treat skills.sh warnings as advisory, not authoritative ā€” and verify against this repo's own version pins before acting on a warning.

Repository Structure

This repository contains 142 production-tested skills for Claude Code, each focused on a specific technology or capability.

Individual Skills: Each skill is a standalone unit with:

  • SKILL.md - Core knowledge and guidance
  • Templates - Working code examples
  • References - Extended documentation
  • Scripts - Helper utilities

Installation Options:

  1. Marketplace (recommended) - Install individual skills via /plugin install <name>@claude-skills
  2. Cross-harness - Install into any supported agent with npx skills add secondsky/claude-skills --skill <name> (see Installing with skills.sh)

Available Skills (142 Individual Skills)

Each skill is individually installable. Install only the skills you need.

Full Catalog: See MARKETPLACE.md for detailed listings.

Categories

CategorySkillsExamples
tooling24turborepo, plan-interview, code-review
frontend26nuxt-v4, nuxt-v5, tailwind-v4-shadcn, tanstack-query, nuxt-studio, maz-ui, threejs
cloudflare21cloudflare-d1, cloudflare-workers-ai, cloudflare-agents
api16api-design-principles, graphql-implementation
ai7gemini-cli, ml-model-training, tanstack-ai
web10hono-routing, firecrawl-scraper, web-performance
security6csrf-protection, xss-prevention, cybersecurity
mobile5react-native-app, react-native-skills
woocommerce4woocommerce-backend-dev
testing4vitest-testing, playwright-testing
design4design-review, design-system-creation
auth4better-auth
architecture3microservices-patterns, architecture-patterns
data2recommendation-engine, recommendation-system
cms2hugo, wordpress-plugin-core
database1drizzle-orm-d1
seo2seo-optimizer, seo-keyword-cluster-builder
documentation1technical-specification

How It Works

Auto-Discovery

Claude Code automatically checks ~/.claude/skills/ for relevant skills before planning tasks:

User: "Set up a Cloudflare Worker with D1 database"
           ā†“
Claude: [Checks skills automatically]
           ā†“
Claude: "Found cloudflare-d1 skills.
         These prevent 12 documented errors. Use them?"
           ā†“
User: "Yes"
           ā†“
Result: Production-ready setup, zero errors, ~65% token savings

Note: Due to token limits, not all skills may be visible at once. See āš ļø Important: Token Limits below.

Skill Structure

Each plugin is a directory under plugins/<plugin-name>/ containing one or more skills:

plugins/[plugin-name]/
ā”œā”€ā”€ .claude-plugin/
ā”‚   ā””ā”€ā”€ plugin.json       # Plugin manifest (marketplace metadata)
ā”œā”€ā”€ README.md
ā”œā”€ā”€ skills/
ā”‚   ā””ā”€ā”€ [skill-name]/
ā”‚       ā”œā”€ā”€ SKILL.md          # Core knowledge and guidance
ā”‚       ā”œā”€ā”€ templates/        # Ready-to-copy templates
ā”‚       ā”œā”€ā”€ scripts/          # Helper utilities
ā”‚       ā””ā”€ā”€ references/       # Extended documentation
ā””ā”€ā”€ (optional) agents/, commands/, hooks/

Recent Additions

July 2026

Offensive Security (new category):

  • cybersecurity ā€” Unified OSS-only cybersecurity skill with progressive disclosure. Fuses 7 community skills (mukul975 business-logic/XSS/host-header/forced-browsing/open-redirect, rysweet/amplihack cybersecurity-analyst, Aradotso security-detections-mcp) ported to fully open-source tooling (OWASP ZAP, Dalfox, ffuf, Nuclei, mitmproxy, interact.sh, Semgrep, Sigma). Covers threat modeling (STRIDE/PASTA/VAST, MITRE ATT&CK), web-vuln testing, SAST, code audit, AI/LLM-app security, and detection engineering. Live-target testing is gated behind an authorization disclaimer; static analysis, code review, and threat modeling are always available. Cross-references the 5 existing defensive security plugins (csrf-protection, xss-prevention, vulnerability-scanning, security-headers-configuration, defense-in-depth-validation) for remediation. Integrates 20 Aradotso dev-security skills across 5 grouped reference docs.

May 2026

Supply Chain Security (cross-cutting):

  • dependency-upgrade expanded with Socket CLI integration ā€” proactive malicious package detection, typosquatting alerts, and CI/CD security gates. New 418-line reference guide, 2 GitHub Actions templates, and expanded supply chain security comparison (3 tools)
  • 31 skills now include "Secure Installation" guidance ā€” contextually-tailored security sections across all high-risk skill categories (scaffolding, MCP/agent SDKs, multi-provider installs, Docker, CI/CD). Covers 8 Bun skills, 5 Nuxt skills, 6 Cloudflare skills, 4 AI/agent skills, and 8 frontend/tooling skills
  • Supply chain security is now a first-class cross-cutting concern woven into the skill collection ā€” not a standalone topic

February - April 2026

Full-Stack Frameworks:

  • nuxt-v5 (v1.0.0) - Full Nuxt 5 support with 4 skills (core, data, server, production), 3 diagnostic agents, and interactive setup wizard
  • threejs (v1.0.0) - 3D web graphics: scenes, geometries, shaders, animations, post-processing

Infrastructure:

  • JSON schema validation - Automated plugin.json validation with CI support
  • GitHub issue templates - Skill-specific issue templates for bug reports, feature requests, and submissions

Plugin Enhancements:

  • mutation-testing - Added Bun native runner support
  • dependency-upgrade - Added supply chain security content

December 2025 - January 2026

Frontend Expansion:

  • nuxt-studio (v1.0.0) - Visual CMS for Nuxt Content with live preview, OAuth auth, and R2 storage integration
  • maz-ui (v1.0.0) - 50+ Vue/Nuxt components with theming, i18n, form generation, and 14 composables

Developer Workflow:

  • plan-interview (v2.0.0) - Adaptive interview-driven spec generation with autonomous quality review
  • turborepo (v2.8.0) - Updated to official Vercel skill with enhanced monorepo build optimization

Mobile Development:

  • react-native-skills (v1.0.0) - React Native & Expo best practices with performance optimization patterns

Enhanced Authentication:

  • better-auth (v2.2.0) - Expanded to 18 framework integrations with 30+ authentication plugins

āš ļø Important: Token Limits

Skill Visibility Constraint

Claude Code has a 15,000 character limit for the total size of skill descriptions in the system prompt. This limit also applies to commands and agents.

What this means:

  • Not all 142 skills may be visible in Claude's context at once
  • Skills are loaded based on relevance and available token budget
  • You can verify how many skills Claude currently sees by asking: "How many skills do you see in your system prompt?"

Checking Visible Skills

To verify which skills are currently loaded:

# Ask Claude Code directly
"Check what skills/plugins you see in your system prompt"

Claude will report something like: "85 of 142 skills visible due to token limits"

Workaround: Increase Token Budget

You can double the headroom for s

ā€¦

View source on GitHub