bun-dev-server

Set up high-performance development servers with Hot Module Replacement. Use when creating dev servers for web apps, setting up React Fast Refresh, or configuring API servers with live reload.

الانتقال إلى التثبيت

المستودع: involvex/youtube-music-cli
آخر نشاط في المصدر: ١٦ أبريل ٢٠٢٦ في ٢٣:١٢
لغة SKILL.md المكتشفة: الإنجليزية
النجوم: ٤١٤
التفرعات: ٢٤

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.

npx skills add https://github.com/involvex/youtube-music-cli --skill bun-dev-server

يبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.

تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

مستكشف الملفات

2 ملفات

SKILL.md

تعليمات المصدر · معاينة للقراءة فقط

العودة إلى البحث العودة إلى التثبيت

name	bun-dev-server
description	Set up high-performance development servers with Hot Module Replacement. Use when creating dev servers for web apps, setting up React Fast Refresh, or configuring API servers with live reload.
compatibility	Requires Bun 1.0+
allowed-tools	["Bash","Write","Read"]
metadata	{"author":"dale","category":"bun-runtime","tags":["bun","dev-server","hmr","react","hot-reload"]}

Bun Development Server Setup

You are assisting with setting up a high-performance development server using Bun.serve with Hot Module Replacement (HMR) and React Fast Refresh.

Workflow

1. Determine Server Type

Ask the user what type of development server they need:

React/Frontend App: SPA with React Fast Refresh
API Server: REST/GraphQL API with auto-reload
Full-Stack App: Frontend + API combined
Static Server: File server with live reload

2. Check Prerequisites

# Verify Bun installation
bun --version

# Check if project has package.json
ls -la package.json

If no package.json exists, suggest running bun init first.

3. Install Dependencies

For React Apps:

bun add react react-dom
bun add -d @types/react @types/react-dom

For API with Hono (recommended):

bun add hono

For Full-Stack:

bun add react react-dom hono
bun add -d @types/react @types/react-dom

4. Create Server Configuration

React Development Server

Create server.ts in the project root:

import type { ServerWebSocket } from "bun";

const clients = new Set<ServerWebSocket<unknown>>();

const server = Bun.serve({
  port: 3000,

  async fetch(request, server) {
    const url = new URL(request.url);

    // WebSocket for HMR
    if (url.pathname === "/_hmr") {
      const upgraded = server.upgrade(request);
      if (upgraded) return undefined;
      return new Response("WebSocket upgrade failed", { status: 500 });
    }

    // Serve index.html for SPA routing
    if (url.pathname === "/" || !url.pathname.includes(".")) {
      return new Response(
        Bun.file("public/index.html"),
        { headers: { :  } }
      );
    }

    
     filePath = ;
     file = .(filePath);

     ( file.()) {
        (file);
    }

      (, { :  });
  },

  : {
    () {
      clients.(ws);
      .();
    },

    () {
      clients.(ws);
      .();
    },

    () {
      
    },
  },
});

.();


 watcher = ..(.. + , {
  : ,
});

  ( event  watcher) {
   (event. ===  && event..()) {
    .();

    
     ( client  clients) {
      client.(.({ :  }));
    }
  }
}

Create public/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Bun + React App</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/src/index.tsx"></script>

  <!-- HMR Client -->
  <script>
    const ws = new WebSocket('ws://localhost:3000/_hmr');

    ws.addEventListener('message', (event) => {
      const data = JSON.parse(event.data);

      if (data.type === 'reload') {
        console.();
        ..();
      }
    });

    ws.(,  {
      .();
      ( ..(), );
    });

Create src/index.tsx:

import { render } from 'react-dom';
import App from './App';

const root = document.getElementById('root');
render(<App />, root);

Create src/App.tsx:

export default function App() {
  return (
    <div>
      <h1>Welcome to Bun + React!</h1>
      <p>Edit src/App.tsx to see HMR in action</p>
    </div>
  );
}

API Server with Hono

Create server.ts:

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';

const app = new Hono();

// Middleware
app.use('*', cors());
app.use('*', logger());

// Routes
app.get('/', (c) => {
  return c.json({ message: 'Welcome to Bun API' });
});

app.get('/api/health', (c) => {
  return c.json({ status: 'ok', timestamp: Date.now() });
});

// Example POST endpoint
app.post('/api/users', async (c) => {
  const body = await c.req.json();
  return c.json({ created: true, data: body }, );
});


 server = .({
  : process.. || ,
  : app.,
});

.();

Full-Stack Server

Create server.ts:

import { Hono } from 'hono';
import { serveStatic } from 'hono/bun';

const app = new Hono();

// API routes
const api = new Hono();

api.get('/health', (c) => c.json({ status: 'ok' }));
api.get('/users', (c) => c.json({ users: [] }));

app.route('/api', api);

// Serve static files
app.use('/*', serveStatic({ root: './public' }));

// SPA fallback
app.get('*', (c) => c.html(Bun.file('public/index.html')));

const server = Bun.serve({
  port: 3000,
  fetch: app.fetch,
});

console.log(`🚀 Full-stack server at http://localhost:`);

5. Configure React Fast Refresh (Advanced)

For true React Fast Refresh, create hmr-runtime.ts:

// React Fast Refresh runtime
let timeout: Timer | null = null;

export function refresh() {
  if (timeout) clearTimeout(timeout);

  timeout = setTimeout(() => {
    // Re-import the App component
    import('./App.tsx?t=' + Date.now()).then((module) => {
      const { render } = require('react-dom');
      const root = document.getElementById('root');
      render(module.default(), root);
    });
  }, 100);
}

// Listen for HMR events
if (import.meta.hot) {
  import.meta.hot.accept(() => {
    refresh();
  });
}

6. Environment Configuration

Create .env.development:

# Server
PORT=3000
NODE_ENV=development

# API
API_URL=http://localhost:3000/api

# Features
ENABLE_HMR=true

Create .env.production:

# Server
PORT=8080
NODE_ENV=production

# API
API_URL=https://api.example.com

# Features
ENABLE_HMR=false

Load environment in server.ts:

// Environment is loaded automatically by Bun
const isDev = process.env.NODE_ENV === 'development';
const port = process.env.PORT || 3000;

7. Update package.json Scripts

Add development scripts:

{
  "scripts": {
    "dev": "bun run --hot server.ts",
    "dev:watch": "bun run --watch server.ts",
    "start": "NODE_ENV=production bun run server.ts",
    "build": "bun build src/index.tsx --outdir=dist --minify",
    "clean": "rm -rf dist"
  }
}

Script explanations:

dev: Run with hot reload (restarts on file changes)
dev:watch: Watch mode (faster, but doesn't reload on crash)
start: Production mode
build: Build frontend for production

8. Configure TypeScript

Update tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "types": ["bun-types"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions":

9. Create Project Structure

Generate complete project structure:

project/
├── server.ts              # Development server
├── src/
│   ├── index.tsx         # App entry point
│   ├── App.tsx           # Main component
│   ├── components/       # React components
│   └── styles/           # CSS files
├── public/
│   ├── index.html        # HTML template
│   └── assets/           # Static assets
├── .env.development
├── .env.production
├── package.json
├── tsconfig.json
└── README.md

10. Advanced: HTTPS for Local Development

For HTTPS support (needed for some browser APIs):

import { readFileSync } from 'fs';

const server = Bun.serve({
  port: 3000,
  tls: {
    cert: readFileSync('./localhost.pem'),
    key: readFileSync('./localhost-key.pem'),
  },
  fetch: app.fetch,
});

console.log(`🔒 HTTPS server at https://localhost:${server.port}`);

Generate certificates with:

# Install mkcert first: brew install mkcert
mkcert -install
mkcert localhost 127.0.0.1 ::1

11. Proxy Configuration (for existing backends)

If user needs to proxy API requests to another server:

const app = new Hono();

// Proxy /api requests to backend
app.all('/api/*', async (c) => {
  const url = new URL(c.req.url);
  const backendUrl = `http://localhost:8080${url.pathname}${url.search}`;

  const response = await fetch(backendUrl, {
    method: c.req.method,
    headers: c.req.raw.headers,
    body: c.req.method !== 'GET' ? await c.req.raw.text() : undefined,
  });

  return new Response(response.body, {
    status: response.status,
    headers: response.headers,
  });
});

Testing the Setup

After creation, guide user to test:

# 1. Start dev server
bun run dev

# 2. Open browser
open http://localhost:3000

# 3. Make a change to src/App.tsx
# 4. Verify HMR reloads the page

# 5. Test API endpoints
curl http://localhost:3000/api/health

Troubleshooting

HMR not working

// Check if WebSocket connection is established
// Open browser console and look for:
// "HMR client connected"

// If not, verify:
// 1. Port is correct
// 2. No firewall blocking WebSocket
// 3. Server is running with --hot flag

Port already in use

# Find process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

# Or use a different port
PORT=3001 bun run dev

CORS issues

Add CORS headers to server:

app.use('*', cors({
  origin: 'http://localhost:3000',
  credentials: true,
}));

Performance Tips

Use --hot for development: Faster than --watch for most cases
Minimize file watcher scope: Watch only src/ directory
Use HTTP/2: Enable for faster parallel loading
Cache static assets: Add Cache-Control headers

app.use('/assets/*', async (c, next) => {
  await next();
  c.header('Cache-Control', 'public, max-age=31536000');
});

Completion Checklist

✅ Development server created
✅ HMR configured and tested
✅ Environment variables set up
✅ Package.json scripts added
✅ Project structure organized
✅ TypeScript configured
✅ Browser successfully connects
✅ File changes trigger reload

Next Steps

Suggest to the user:

Add error boundaries for better error handling
Set up ESLint and Prettier
Configure path aliases in tsconfig.json
Add development vs production builds
Consider adding bun-test for testing

bun-dev-server

معلومات المصدر

خيارات التثبيت

مراجعة ملفات المصدر

المزيد من هذا المستودع

المزيد من هذا المستودع

Bun Development Server Setup

Workflow

1. Determine Server Type

2. Check Prerequisites

3. Install Dependencies

4. Create Server Configuration

React Development Server

API Server with Hono

Full-Stack Server

5. Configure React Fast Refresh (Advanced)

6. Environment Configuration

7. Update package.json Scripts

8. Configure TypeScript

9. Create Project Structure

10. Advanced: HTTPS for Local Development

11. Proxy Configuration (for existing backends)

Testing the Setup

Troubleshooting

HMR not working

Port already in use

CORS issues

Performance Tips

Completion Checklist

Next Steps

Bun Development Server Setup

Workflow

1. Determine Server Type

2. Check Prerequisites

3. Install Dependencies

4. Create Server Configuration

React Development Server

API Server with Hono

Full-Stack Server

5. Configure React Fast Refresh (Advanced)

6. Environment Configuration

7. Update package.json Scripts

8. Configure TypeScript

9. Create Project Structure

10. Advanced: HTTPS for Local Development

11. Proxy Configuration (for existing backends)

Testing the Setup

Troubleshooting

HMR not working

Port already in use

CORS issues

Performance Tips

Completion Checklist

Next Steps