A high-performance web framework built on uWebSocket.js, wrapped in a Koa-like interface.
npm install uwebkoashell
npm install uWebKoa
or
yarn add uWebKoa
`
$3
`javascript
import uWebKoa from 'uWebKoa';
const app = new uWebKoa();
// Middleware usage
app.use(async (ctx, next) => {
console.log(Request: ${ctx.method} ${ctx.url});
await next();
});
// Route example
app.get('/', (ctx) => {
ctx.body = 'Hello uWebKoa!';
});
app.get('/user/:id', (ctx) => {
ctx.body = User ID: ${ctx.request.params.id};
});
// Start server
app.listen(3000, () => {
console.log('Server running at http://localhost:3000');
});
`
API Documentation
$3
`javascript
import uWebKoa from 'uWebKoa';
const app = new uWebKoa();
`
Options:
- rootDir: Project root directory (default: process.cwd())
- staticDirs: Static file directory mapping
- ssl: SSL configuration object ({ key_file_name, cert_file_name, passphrase })
$3
`javascript
app.use(async (ctx, next) => {
// Pre-request processing
await next();
// Post-request processing
});
`
$3
Each request creates a ctx object containing:
- ctx.request: Request object
- ctx.response: Response object
- ctx.method: HTTP method
- ctx.url: Request URL
- ctx.query: Query parameters
- ctx.params: Route parameters
- ctx.body: Response body
- ctx.status: HTTP status code
$3
`javascript
app.get('/path', ...handlers);
app.post('/path', ...handlers);
app.put('/path', ...handlers);
app.delete('/path', ...handlers);
app.get('/path/:id',...handlers);
app.get('/path/*',...handlers);
`
Support multiple handlers:
`javascript
app.get('/user',
(ctx, next) => { / Validation / next() },
(ctx) => { / Processing / }
);
`
$3
`javascript
app.serveStatic('/public', './static');
`
$3
- ctx.json(data): Send JSON response
- ctx.sendFile(path): Send file
- ctx.redirect(url): Redirect
- ctx.throw(status, message): Throw error
Advanced Features
$3
`javascript
app.listen(3000, {
cluster: true,
workers: 4 // Optional, uses all CPU cores by default
});
`
$3
`javascript
// Thread mode (multi-threading)
app.listen(3000, {
threads: true,
workers: 8 // 8 worker threads
});
`
Note: Uses handle migration technology. Thread crashes may cause main process termination.
$3
`javascript
const app = new uWebKoa({
ssl: {
key_file_name: 'key.pem',
cert_file_name: 'cert.pem',
passphrase: 'your-passphrase' // Optional
}
});
`
$3
`javascript
app.getUWebSocketApp().ws('/chat', {
open: (ws) => {...},
message: (ws, msg) => {...}
});
`
$3
`javascript
// Create socket.io instance
const io = new Server({
cors: {
origin: '*',
},
});
// Get uWebSocket.js app instance
const uWebSocketApp = app.getUWebSocketApp();
io.attachApp(uWebSocketApp);
app.context.io = io; // Pass socket.io instance to context
app.get('/path/:id', (ctx) => {
ctx.io.to(id).emit("server_notify_update", {});
});
`
Best Practices
1. Middleware Order: Place general middleware before route-specific ones
2. Error Handling: Use try/catch or error handling middleware
3. Static Files: Enable cache for small files, streaming for large files
4. Production: Enable multi-core mode for full CPU utilization
Migration Guide
$3
1. Replace require('koa') with import uWebKoa from 'uwebkoa'
2. Note ctx.res and ctx.req are native uWebSockets.js objects
3. Use ctx.sendFile() instead of ctx.send() for file operations
4. Request body parsing uses await ctx.parseBody() automatically
Example Project
`javascript
import uWebKoa from 'uwebkoa';
const app = new uWebKoa();
// Logger middleware
app.use(async (ctx, next) => {
const start = Date.now();
await next();
const ms = Date.now() - start;
console.log(${ctx.method} ${ctx.url} - ${ms}ms);
});
// API Routes
app.get('/api/users', async (ctx) => {
ctx.body = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
});
app.post('/api/users', async (ctx) => {
await ctx.parseBody();
// User creation logic
ctx.status = 201;
ctx.body = { success: true };
});
// Static Files
app.serveStatic('/public', './assets');
// Error Handling
app.use(async (ctx) => {
ctx.status = 404;
ctx.body = { error: 'Not Found' };
});
// Start Server
app.listen(3000, { cluster: true });
`
FAQ
- Why choose uWebKoa over Koa or Express?
uWebKoa maintains Koa's elegant API while providing significant performance improvements through the uWebSockets.js foundation, making it particularly suitable for high-concurrency scenarios.
- Does it support WebSocket and Socket.io?
The current version primarily focuses on HTTP services, with native WebSocket and Socket.io support planned for future releases.
- How to access the raw request object?
You can access uWebSockets.js' native objects through ctx.req and ctx.res. Additionally, app.getUWebSocketApp() retrieves the native uWebSockets.js application instance.
Contribution
We welcome issues and pull requests. Please ensure:
- Consistent code style
- Passing all tests
- Comprehensive test coverage for new features
For questions or suggestions:
Open an issue on GitHub
1. mail iakuf@163.com with subject line "[uWebKoa] Your Subject"
2. Please include detailed reproduction steps for bug reports and clear rationale for feature requests.
Stress Test
`bash
autocannon -c 100 -d 10 http://localhost:3000/api/users
``