Skip to content

Commit

Permalink
docs(reference/recipes): add fastify and adonis examples
Browse files Browse the repository at this point in the history
  • Loading branch information
MatthewWid committed Oct 27, 2024
1 parent 51eb1e3 commit 0332511
Show file tree
Hide file tree
Showing 5 changed files with 57 additions and 36 deletions.
Empty file added docs/public/.gitkeep
Empty file.
4 changes: 1 addition & 3 deletions docs/src/content/docs/guides/channels.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Broadcasting With Channels
title: Broadcasting with channels
description: Learn how to use channels which allow you to broadcast events to many clients at once.
sidebar:
order: 2
Expand All @@ -8,8 +8,6 @@ sidebar:

import {Tabs, TabItem, Code, Aside, Steps, LinkCard} from "@astrojs/starlight/components";

## Introduction

<Aside>
You should read the [Getting Started](/guides/getting-started) guide first if you haven't already.
</Aside>
Expand Down
4 changes: 1 addition & 3 deletions docs/src/content/docs/guides/getting-started.mdx
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
---
title: Getting Started
title: Getting started
description: Get started using Better SSE.
sidebar:
order: 1
---

import {Tabs, TabItem, Code, Aside, Steps, LinkCard} from "@astrojs/starlight/components";

## Introduction

[Server-sent events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) is a standardised protocol that allows web-servers to push data (characterized as _events_) to a client without the client having to request it immediately before.

Using SSE can allow for significant savings in bandwidth and battery life on portable devices and will work with your existing infrastructure as it operates directly over the HTTP protocol without the need for the connection upgrade that [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) and [HTTP/2](https://developer.mozilla.org/en-US/docs/Glossary/HTTP_2) do (but can also be used with HTTP/2!).
Expand Down
8 changes: 6 additions & 2 deletions docs/src/content/docs/reference/comparison.mdx
Original file line number Diff line number Diff line change
@@ -1,17 +1,21 @@
---
title: Comparison With Other Tools
title: Comparison with other tools
description: Compare the features of Better SSE with other similar Node SSE libraries.
sidebar:
order: 2
---

import {Aside} from "@astrojs/starlight/components";

This section compares Better SSE with other server-sent events libraries for Node.

Better SSE was designed to be the easiest and most powerful library for using server-sent events, better than all other existing solutions.

## Features

TL/DR: Better SSE supports all\* the features that other competing libraries do and much more. It is TypeScript-first (but obviously can be used with JavaScript), very well tested, easier to scale and much more flexible than others whilst *still* having a simpler programming interface for both simple and complex use cases.
<Aside title="TL/DR" type="tip">
Better SSE supports all\* the features that other competing libraries do and much more. It is TypeScript-first (but obviously can be used with JavaScript), very well tested, easier to scale and much more flexible than others whilst *still* having a simpler programming interface for both simple and complex use cases.
</Aside>

|Feature|[`better-sse`](https://www.npmjs.com/package/better-sse)|[`sse-channel`](https://www.npmjs.com/package/sse-channel)|[`sse`](https://www.npmjs.com/package/sse)|[`express-sse`](https://www.npmjs.com/package/express-sse)|[`sse-stream`](https://www.npmjs.com/package/sse-stream)|[`sse-pubsub`](https://www.npmjs.com/package/sse-pubsub)|[`nestjs @Sse`](https://docs.nestjs.com/techniques/server-sent-events)|[`hono/streaming`](https://hono.dev/helpers/streaming#streamsse)|
|-|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
Expand Down
77 changes: 49 additions & 28 deletions docs/src/content/docs/reference/recipes.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Usage Recipes
title: Usage recipes
description: See examples of using Better SSE with various Node HTTP frameworks.
sidebar:
order: 3
Expand All @@ -11,16 +11,16 @@ Feel free to [submit a PR](https://github.com/MatthewWid/better-sse/pulls) with

### [HTTP](https://nodejs.org/api/http.html)

```javascript title="server.js"
import {createServer} from "http";
import {createSession} from "better-sse";
```typescript title="server.ts"
import { createServer } from "http";
import { createSession } from "better-sse";

const server = createServer(async (req, res) => {
switch (req.url) {
case "/sse": {
const sse = await createSession(req, res);
const session = await createSession(req, res);

sse.push("Hello world!");
session.push("Hello world!");

break;
}
Expand All @@ -35,45 +35,38 @@ server.listen(8080);

### [Express](https://expressjs.com/)

```javascript title="server.js"
```typescript title="server.ts"
import express from "express";
import {createSession} from "better-sse";
import { createSession } from "better-sse";

const app = express();

app.get(
"/sse",
async (req, res, next) => {
const session = await createSession(req, res);

session.push("Hello world!");
}
);
app.get("/sse", async (req, res) => {
const session = await createSession(req, res);
session.push("Hello world!");
});

app.listen(8080);
```

### [Koa](https://koajs.com/)

```javascript title="server.js"
```typescript title="server.ts"
import Koa from "koa";
import Router from "@koa/router";
import {createSession} from "better-sse";
import { createSession } from "better-sse";

const app = new Koa();
const router = new Router();

router.get(
"/sse",
async (ctx, next) => {
// Prevent Koa sending a response and closing the connection
ctx.respond = false;
router.get( "/sse", async (ctx) => {
// Prevent Koa sending a response and closing the connection
ctx.respond = false;

const session = await createSession(ctx.req, ctx.res);
const session = await createSession(ctx.req, ctx.res);

session.push("Hello world!");
}
);
session.push("Hello world!");
});

app.use(router.routes());

Expand All @@ -84,7 +77,7 @@ app.listen(8080);

Assuming you are using [`@nestjs/platform-express`](https://www.npmjs.com/package/@nestjs/platform-express) (the default).

```typescript
```typescript title="server.ts"
import { Controller, Get, Req, Res } from "@nestjs/common";
import { Request, Response } from "express";
import { createSession } from "better-sse";
Expand All @@ -99,3 +92,31 @@ export class SseController {
}
}
```

### [Fastify](https://fastify.dev/)

```typescript title="server.ts"
import Fastify from "fastify";
import { createSession } from "better-sse";

const fastify = Fastify();

fastify.get("/sse", async (request, reply) => {
const session = await createSession(request.raw, reply.raw);
session.push("Hello world!");
});

fastify.listen({ port: 8080 });
```

### [Adonis](https://adonisjs.com/)

```typescript title="server.ts"
import router from "@adonisjs/core/services/router";
import { createSession } from "better-sse";

router.get("/sse", async ({ request, response }) => {
const session = await createSession(request.request, response.response);
session.push("Hello world!");
});
```

0 comments on commit 0332511

Please sign in to comment.