synphony

The synphony between HTTP and WebSocket, written in TypeScript. A unified, modular, and frictionless framework.

Synphony is a TypeScript framework for creating HTTP and WebSocket servers under a single API. Designed to be lightweight, modular, and expressive, Synphony doesn’t hide complexity — it organizes it.

Its architecture lets you extend, replace, or create modules without breaking the simplicity of the design. Total control, natural performance, and a modern developer experience.

Philosophy

Synphony doesn’t try to hide complexity — it arranges it. It doesn’t lock you into its structure — it lets you compose your own. Every module, every request, every connection… flows to the same rhythm.

Minimalism without limits. Efficiency without friction. Freedom without compromise.

Installation

Install Synphony using npm:

npm install synphony

Requires Node.js v18 or higher.

Features

• Unified HTTP + WS: handle requests and sockets under one API and context.
• Modular architecture: every part of the system can be extended, replaced, or disabled.
• Native plugins: extend the core without losing performance.
• Total control: direct access to the core, routes, connections, and low-level events.
• Shared context: HTTP and WS can interact and share data seamlessly.
• Lightweight and expressive: no unnecessary configuration or redundant layers.
• Written in TypeScript: strong typing, modern DX, and full ESM compatibility.
• Efficiency by design: optimized performance from the core, without hacks or heavy dependencies.

Quick Start

You can find more examples in examples.

Unified example (HTTP + WS)

import { Server } from 'synphony/http';

const app = new Server();

app.get('/', (req, res) => {
  res.send('Hello from HTTP!');
});

app.ws('/chat', (socket) => {
  socket.send('Welcome to the chat!');
  socket.on('message', (msg) => socket.send(`Echo: ${msg}`));
});

app.listen(3000, () => {
  console.log(`Server running at ${app.address.url}`);
});

Simple HTTP server

import { Server } from 'synphony/http';

const server = new Server();

server.get('/', (req, res) => {
  res.send('Hello, World!');
});

server.listen(3000, () => {
  console.log(`Server running on ${server.address.url}`);
});

Simple WebSocket server

import { WebSocketServer } from 'synphony/ws';

const wss = new WebSocketServer();

wss.on('connection', (socket) => {
  socket.send('Hello, World!');
  socket.on('message', () => socket.send('I got your message!'));
});

wss.listen(8080, () => {
  console.log(`WebSocket server running on ${wss.address.url}`);
});

Contributing

Got ideas, improvements, or found a bug? Contributions are welcome! Here’s how to get started:

• Check the open issues.

• Fork the repository.

• Create a branch for your change:

  git checkout -b feature/my-change
  

• Make your changes and commit them:

  git commit -m "feat: add new feature"
  

• Push and open a Pull Request.

See the contribution guide for more details.

Contributors

Thanks to these amazing people:

License

This project is licensed under the MIT License.

Manifesto

Read the Synphony Manifesto and discover the philosophy behind the code.