chore: initial docs

Author: pi0

docs/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+.nuxt
+.output
+dist

docs/.npmrc

@@ -0,0 +1,2 @@
+shamefully-hoist=true
+ignore-workspace-root-check=true

docs/content/1.getting-started/1.index.md

@@ -0,0 +1,33 @@
+# Getting Started
+
+CrossWS provides a cross-platform API to define well-typed WebSocket apps that can then be integrated into various WebSocket servers using built-in adapters.
+
+Writing a realtime WebSocket server that can work in different javascript and WebSocket runtimes is challenging because there is no single standard for WebSocket servers. You often need to go into many details of diffrent API implementations and it also makes switching from one runtime costly. CrossWS is a solution to this!
+
+## Installing Package
+
+You can install crossws from [npm](https://npmjs.com/crossws):
+
+::code-group
+
+```sh [auto]
+npx nypm i crossws
+```
+
+```sh [npm]
+npm install crossws
+```
+
+```sh [Yarn]
+yarn add crossws
+```
+
+```sh [pnpm]
+pnpm add crossws
+```
+
+```sh [bun]
+bun add crossws
+```
+
+::

docs/content/1.getting-started/2.hooks.md

@@ -0,0 +1,35 @@
+# WebSocket Hooks
+
+Using WebSocket hooks API, you can define a WebSocket server that works across runtimes with same synax.
+
+CrossWS provides a cross-platform API to define WebSocket servers. An implementation with these hooks works across runtimes without needing you to go into details of any of them (while you always have the power to control low-level hooks). You can only define the life-cycle hooks that you only need and only those will be called on runtime.
+
+```ts
+import { defineWebSocketHooks } from "crossws";
+
+const websocketHooks = defineWebSocketHooks({
+  open(peer) {
+    console.log("[ws] open", peer);
+  },
+
+  message(peer, message) {
+    console.log("[ws] message", peer, message);
+    if (message.text().includes("ping")) {
+      peer.send("pong");
+    }
+  },
+
+  close(peer, event) {
+    console.log("[ws] close", peer, event);
+  },
+
+  error(peer, error) {
+    console.log("[ws] error", peer, error);
+  },
+
+  // ... platform hooks such as bun:drain ...
+});
+```
+
+> [!NOTE]
+> Using `defineWebSocketHooks` to define hooks, we have type support and IDE auto-completion even if not using typescript. This utility does nothing more and you can use a plain object as well if you prefer to.

docs/content/1.getting-started/3.peer.md

@@ -0,0 +1,31 @@
+# WebSocket Peer
+
+Peer object allows easily interacting with connected clients.
+
+Almost all Websocket hooks accept a peer instance as their first argument. You can use peer object to get information about each connected client or a message to them.
+
+> [!TIP]
+> You can safely log a peer instance to the console using `console.log` it will be automatically stringified with useful information including the remote address and connection status!
+
+## API Reference
+
+### `peer.send(message, compress)`
+
+Send a message to the connected client
+
+### `peer.id`
+
+The peer address or unique id (might be `undefined`)
+
+### `peer.readyState`
+
+Client connection status (might be `undefined`)
+
+(read more in [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState))
+
+### `peer.ctx`
+
+`peer.ctx` is an object that holds adapter specific context. It is scoped with `peer.ctx.[name]`.
+
+> [!NOTE]
+> This is an advanced namespace and API changes might happen, so don't rely on it as much aspossible!

docs/content/1.getting-started/4.message.md

@@ -0,0 +1,20 @@
+# WebSocket Message
+
+On `message` hook, you receive a message object containing an incoming message from the client.
+
+> [!TIP]
+> You can safely log `message` object to the console using `console.log` it will be automatically stringified!
+
+## API Reference
+
+### `message.text()`
+
+Get stringified text version of the message
+
+### `message.rawData`
+
+Raw message data
+
+### `message.isBinary`
+
+Indicates if the message is binary (might be `undefined`)

docs/content/1.getting-started/5.client.md

@@ -0,0 +1,14 @@
+# WebSocket Client
+
+Universal WebSocket API to connect to WebSocket servers from clients.
+
+CrossWS exposes [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) in order to connect to the server.
+
+For all runtimes, except Node.js, native implementation is used, and for Node.js, a bundled version of [`ws.WebSocket`](https://www.npmjs.com/package/ws) is bundled.
+
+```js
+import WebSocket from "crossws/websocket";
+```
+
+> [!NOTE]
+> Using export conditions, the correct version will be always used so you don't have to worry about picking the right build!

docs/content/1.getting-started/99.adapters.md

@@ -0,0 +1,11 @@
+# Runtime Adapters
+
+CrossWS allows integrating your WebSocket hooks with different runtimes and platforms using built-in adapters. Each runtime has a specific method of integrating WebSocket. Once integrated, will work consistently even if you change the runtime.
+
+See Adapters section to learn more about all available built-in adapters
+
+## Integration with other runtimes
+
+You can define your custom adapters using `defineWebSocketAdapter` wrapper.
+
+See other adapter implementations in [`src/adapters`](https://github.com/unjs/crossws/tree/main/src/adapters/) to get an idea of how adapters can be implemented and feel free to directly make a Pull Request to support your environment in CrossWS!

docs/content/3.adapters/bun.md

@@ -0,0 +1,39 @@
+# Bun
+
+Integrate CrossWS with Bun.
+
+To integrate CrossWS with your Bun server, you need to check for `server.upgrade` and also pass the `websocket` object returned from the adapter to server options. CrossWS leverages native Bun WebSocket API.
+
+```ts
+import wsAdapter from "./dist/adapters/bun";
+
+const { websocket } = wsAdapter({ message: console.log });
+
+Bun.serve({
+  port: 3000,
+  websocket,
+  fetch(req, server) {
+    if (server.upgrade(req)) {
+      return;
+    }
+    return new Response(
+      `<script>new WebSocket("ws://localhost:3000").addEventListener('open', (e) => e.target.send("Hello from client!"));</script>`,
+      { headers: { "content-type": "text/html" } },
+    );
+  },
+});
+```
+
+## Adapter Hooks
+
+- `bun:message (peer, ws, message)`
+- `bun:open (peer, ws)`
+- `bun:close (peer, ws)`
+- `bun:drain (peer)`
+- `bun:error (peer, ws, error)`
+- `bun:ping (peer, ws, data)`
+- `bun:pong (peer, ws, data)`
+
+## Learn More
+
+See [`playground/bun.ts`](https://github.com/unjs/crossws/tree/main/playground/bun.ts) for demo and [`src/adapters/bun.ts`](https://github.com/unjs/crossws/tree/main/src/adapters/bun.ts) for implementation.

docs/content/3.adapters/cloudflare.md

@@ -0,0 +1,34 @@
+# Cloudflare
+
+Integrate CrossWS with Cloudflare Workers.
+
+To integrate CrossWS with your Cloudflare Workers, you need to check for the `upgrade` header.
+
+```ts
+import wsAdapter from "crossws/adapters/cloudflare";
+
+const { handleUpgrade } = wsAdapter({ message: console.log });
+
+export default {
+  async fetch(request, env, context) {
+    if (request.headers.get("upgrade") === "websocket") {
+      return handleUpgrade(request, env, context);
+    }
+    return new Response(
+      `<script>new WebSocket("ws://localhost:3000").addEventListener("open", (e) => e.target.send("Hello from client!"));</script>`,
+      { headers: { "content-type": "text/html" } },
+    );
+  },
+};
+```
+
+## Adapter Hooks
+
+- `cloudflare:accept (peer)`
+- `cloudflare:message (peer, event)`
+- `cloudflare:error (peer, event)`
+- `cloudflare:close (peer, event)`
+
+## Learn More
+
+See [`playground/cloudflare.ts`](https://github.com/unjs/crossws/tree/main/playground/cloudflare.ts) for demo and [`src/adapters/cloudflare.ts`](https://github.com/unjs/crossws/tree/main/src/adapters/cloudflare.ts) for implementation.