{"id":20571942,"url":"https://github.com/chef-js/uws","last_synced_at":"2025-04-14T17:08:14.261Z","repository":{"id":57197711,"uuid":"457876075","full_name":"chef-js/uws","owner":"chef-js","description":"Command Line Interface Static Files Server written in TypeScript for Single Page Applications serving in Node with Microwebsockets","archived":false,"fork":false,"pushed_at":"2024-09-05T14:11:29.000Z","size":528,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-14T17:08:01.690Z","etag":null,"topics":["chat","cli","http-server","javascript","nodejs","nodejs-server","realtime","ssl","typescript","uwebsocketsjs","websocket","websocket-client","websocket-server","websockets"],"latest_commit_sha":null,"homepage":"https://chef-js-uws.herokuapp.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chef-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-10T17:17:39.000Z","updated_at":"2024-09-05T14:11:32.000Z","dependencies_parsed_at":"2024-11-16T05:28:01.310Z","dependency_job_id":null,"html_url":"https://github.com/chef-js/uws","commit_stats":{"total_commits":73,"total_committers":4,"mean_commits":18.25,"dds":0.1095890410958904,"last_synced_commit":"fa126c970e72ec22885444c0b1c0c3645f3d943e"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef-js%2Fuws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef-js%2Fuws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef-js%2Fuws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef-js%2Fuws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chef-js","download_url":"https://codeload.github.com/chef-js/uws/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248923765,"owners_count":21183953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chat","cli","http-server","javascript","nodejs","nodejs-server","realtime","ssl","typescript","uwebsocketsjs","websocket","websocket-client","websocket-server","websockets"],"created_at":"2024-11-16T05:17:49.392Z","updated_at":"2025-04-14T17:08:14.245Z","avatar_url":"https://github.com/chef-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chef-uws\n\n\u003cimg style=\"max-width: 100%; float: right;\" src=\"https://raw.githubusercontent.com/chef-js/core/main/chef.svg\" alt=\"kisscc0\" width=\"200\" height=\"200\" /\u003e\n\n\u003ca href=\"https://badge.fury.io/js/chef-uws\"\u003e\u003cimg src=\"https://badge.fury.io/js/chef-uws.svg\" alt=\"npm package version\" /\u003e\u003c/a\u003e \u003ca href=\"https://circleci.com/gh/chef-js/uws\"\u003e\u003cimg src=\"https://circleci.com/gh/chef-js/uws.svg?style=shield\" alt=\"tests status\" /\u003e\u003c/a\u003e\n\n**web-sockets** micro-service manager and **static files server** at the same port,\n\ndesigned for **node** written in **typescript**, with **tests**\n\n- `uWebSockets.js` for serving files and websockets\n\n## Command-Line Running\n\n```bash\n$ npx chef-uws folder [--debug] [--ssl] [--port 443] [--plugin path/to/plugin.js]\n```\n\n## Installation\n\n```bash\n$ yarn add chef-uws\n```\n\n## Minimal Chat Demo\n\nhttps://chef-js-uws.herokuapp.com/\n\n```bash\n$ yarn add chef-uws\n$ yarn chef-uws node_modules/chef-uws/demo --plugin node_modules/chef-core/chat.js\n```\n\nMinimal configuration is specifying folder, then it serves it from http://localhost:4200\n\n```ts\nconst startServer = require(\"chef-uws\");\nconst config = { folder: \"docs\" };\n\nstartServer(config).then((server: uWS.App | uWS.SSLApp) =\u003e {\n  // server api is get, post, any\n  server.any(\"/*\", (res: uWS.HttpResponse, req: uWS.HttpRequest) =\u003e {\n    res.end(\"200 OK\");\n  });\n});\n```\n\n## Configuration\n\nFor more information about config parameters read:\n\n- The default configuration https://github.com/chef-js/core#configuration\n\n- The parameters types https://chef-js.github.io/core/types/Config.html\n\n## Plugins\n\nThe **plugins** are a mighty thing, think of them like **chat rooms**,\n\nafter a client **handshakes** the chat room, his messages start being **forwarded** to that room,\n\nand it is being handled there by the **room's own plugin**.\n\nThis means you can have for example: a **chat** server and other unrelated **websocket services**\n\nat the **same port** as the **files server** too. **One** client may be in **many** rooms.\n\n### STEP 1: Before Connection\n\n- client -\u003e `websocket` connects to `location.origin.replace(/^http/, 'ws')`\n- server -\u003e waits for any incoming `config.join` events\n\n### STEP 2: Connection\n\n- client -\u003e sends `join` event with room name (topic/plugin name)\n- server -\u003e if such plugin is configured joins client to that plugin\n\n### STEP 3: After Connection\n\n- client -\u003e does some actions (emits, receives)\n- server -\u003e plugin responds to websocket actions\n\n### STEP 4: Finish Connection\n\n- client -\u003e disconnects after some time\n- server -\u003e broadcasts to all plugins from room that client left (`config.leave`)\n\n## API\n\n- a plugin is a function `(ws, { id, event, data })` that is called **each time** the frontend websocket emits to server\n- context (`this`) of each plugin is the `server` instance.\n- plugins receive (and send) the data in the format of:\n\n```ts\n{\n  id,    // WebSocket id - this is automatically added\n  event, // event name as string\n  data,  // any data accompanying the event\n}\n```\n\n## Client\n\nfront-end **websocket client** for `uWebSockets.js` with same API as `socket.io-client`:\n\n```html\n\u003cscript src=\"https://unpkg.com/chef-uws@latest/client.js\"\u003e\u003c/script\u003e\n```\n\nyou can use it like this:\n\n```ts\nconst UWebSocket = require(\"chef-uws/client\");\n// will connect to ws:// or wss:// protocol depending on ssl enabled or not\nconst ws = new UWebSocket(location.origin.replace(/^http/, \"ws\"));\n\nws.on(\"connect\", () =\u003e {\n  // after connect, join a plugin (chat) - emit \"/join\" event with data = \"chat\"\n  ws.emit(\"/join\", \"chat\");\n});\nws.on(\"disconnect\", () =\u003e {\n  // your socket got disconnected\n});\nws.on(\"/join\", (id, event, data) =\u003e {\n  // socket with id joined plugin, first join sets your socket's id\n  ws.id = ws.id || id;\n});\nws.on(\"/leave\", (id, event, data) =\u003e {\n  // socket with id left plugin\n});\nws.on(\"example\", (id, event, data) =\u003e {\n  // handle event with \"example\" name\n});\nws.onAny((id, event, data) =\u003e {\n  // handle all incoming messsages\n});\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef-js%2Fuws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchef-js%2Fuws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef-js%2Fuws/lists"}