Add new Pulse examples (#5992)

* minor updates

* update READMEs

* update READMEs

* use stream instead of subscribe

* update READMEs

* update ui

* update READMEs

* fix simple chat

* update READMEs

* minor changes

* update deps

* minor changes

* update readmes

* update readmes

* update deps

* update terminology from subscribe to stream

* minor changes

* minor changes

* update readmes

* update readmes

* update readmes

* Update README.md

* add pulse examples to main readme

* Update package.json

* Update package.json

README.md

@@ -54,6 +54,8 @@ The [`pulse`](./pulse) folder contains examples of projects using [Prisma Pulse]
 | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
 | [`starter`](./pulse/starter)                     | A Prisma Pulse starter app                                               |
 | [`email-with-resend`](./pulse/email-with-resend) | An example app to send emails to new users using Prisma Pulse and Resend |
+| [`fullstack-leaderboard`](./pulse/fullstack-leaderboard) | An example app to send emails to new users using Prisma Pulse and Resend |
+| [`fullstack-simple-chat`](./pulse/fullstack-simple-chat) | An example app to send emails to new users using Prisma Pulse and Resend |
 
 
 ## Prisma ORM (TypeScript)

pulse/email-with-resend/README.md

@@ -1,15 +1,18 @@
 # Prisma Pulse Example: Send Onboarding Email with Resend
 
-This repository contains an example app that uses Prisma Pulse to detect when new users are added to the database and sends them an onboarding email using [Resend](https://resend.com/).
+This repository contains an example app that uses Prisma Pulse to detect when new users are added to the database and sends them an onboarding email:
 
+- [Prisma Pulse](https://www.prisma.io/data-platform/pulse) to get real-time updates from the database
+- [Resend](https://resend.com/) to send emails
+- [PostgreSQL](https://www.postgresql.org/) as the database
 
 ## Prerequisites
 
 To successfully run the project, you will need the following:
 
 - The **connection string** of a Pulse-ready database (if you don't have one yet, you can configure your database following the instructions in our [docs](https://www.prisma.io/docs/pulse/database-setup) or [use a Railway template](https://railway.app/template/pulse-pg?referralCode=VQ09uv))
 - A **Pulse API key** which you can get by enabling Pulse in a project in your [Prisma Data Platform](https://pris.ly/pdp) account (learn more in the [docs](https://www.prisma.io/docs/platform/concepts/environments#api-keys))
-- A **Resend API Key** which you can get from your [Resend account](https://resend.com/api-keys)
+- A **Resend API Key** which you can get from your [Resend account](https://resend.com/api-keys) (note that if you're on the [free plan](https://resend.com/blog/new-free-tier), you'll only be able to send emails to exactly _one_ email address per day)
 
 ## Getting started
 
@@ -54,7 +57,7 @@ You now have an empty `User` table in your database.
 
 ### 4. Start the Pulse subscription
 
-Run the [script](./index.ts) that contains the code to subscribe to database events:
+Run the [script](./index.ts) that contains the code to stream database events:
 
 ```
 npm run dev
@@ -71,6 +74,8 @@ The following instructions use [Prisma Studio](https://www.prisma.io/studio) to
 3. You will receive a new email in the inbox of the specified `email`. For example: When a new user with an email of `[email protected]` and a name of `Ankur` is created, the email inbox for `[email protected]` should have received the following email (the copy for this email is hardcoded in [`./script.ts`](./script.ts#L33)):
    ![image.png](./images/email.png)
 
+> **Note**: If you can see the event logged to the terminal but didn't receive an email, it may be that you have maxed out the receiver mail addresses on the [free tier](https://resend.com/blog/new-free-tier) for the day.
+
 ## Resources
 
 - [Pulse examples](https://pris.ly/pulse-examples)

pulse/email-with-resend/package.json

@@ -6,7 +6,7 @@
   },
   "dependencies": {
     "@prisma/client": "5.14.0",
-    "@prisma/extension-pulse": "1.0.2",
+    "@prisma/extension-pulse": "dev",
     "@types/node": "20.12.12",
     "dotenv": "16.4.5",
     "resend": "3.2.0"
@@ -16,4 +16,4 @@
     "ts-node": "10.9.2",
     "typescript": "5.4.5"
   }
-}
+}

pulse/email-with-resend/script.ts

@@ -42,22 +42,20 @@ const sendUserCreationEmail = async ({ email, name }: UserEmail) => {
   return await resendClient.emails.send(emailOptions);
 };
 
-// Subscribe to user creation events and send emails
-const emailSubscriber = async () => {
-  const subscription = await prisma.user.subscribe({
-    create: {},
+// Stream user creation events and send emails
+const emailStream = async () => {
+  const stream = await prisma.user.stream({
+    name: 'all-created-users', // Add `name` so that we never lose events
+    create: {}
   });
 
   process.on("exit", (code) => {
-    console.log("Closing Prisma Pulse Subscription.");
-    subscription.stop();
+    console.log("Closing Prisma Pulse Stream.");
+    stream.stop();
   });
 
-  if (subscription instanceof Error) {
-    throw subscription;
-  }
 
-  for await (const event of subscription) {
+  for await (const event of stream) {
     console.log("Received event:", event);
     const { email, name } = event.created;
 
@@ -72,7 +70,7 @@ const emailSubscriber = async () => {
 
 // Main function
 async function main() {
-  await emailSubscriber();
+  await emailStream();
 }
 
 // Run the main function

pulse/fullstack-leaderboard/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

pulse/fullstack-leaderboard/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+dist

pulse/fullstack-leaderboard/README.md

@@ -0,0 +1,118 @@
+# Prisma Pulse Example: Fullstack Leaderboard (Next.js)
+
+![](./leaderboard.gif)
+
+This repository contains an example app that uses Prisma Pulse in a fullstack application to display and update a real-time leaderboard:
+
+- [Next.js](https://nextjs.org/) (_frontend_) with a [custom server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server) (_backend_)
+- [React Flip Move](https://github.com/joshwcomeau/react-flip-move) for animating React components
+- [socket.io](https://socket.io/) for the websocket connection between client and server
+- [Prisma Pulse](https://www.prisma.io/data-platform/pulse) to get real-time updates from the database
+- [PostgreSQL](https://www.postgresql.org/) as the database
+
+> **Note**: The custom server is required because Pulse requires a long-running connection to the database. As an alternative to the custom server included in this app, you can also build your own server using a library/framework like Express, Fastify or NestJS.
+
+
+## Prerequisites
+
+To successfully run the project, you will need the following:
+
+- The **connection string** of a Pulse-ready database (if you don't have one yet, you can configure your database following the instructions in our [docs](https://www.prisma.io/docs/pulse/database-setup) or [use a Railway template](https://railway.app/template/pulse-pg?referralCode=VQ09uv))
+- A **Pulse API key** which you can get by enabling Pulse in a project in your [Prisma Data Platform](https://pris.ly/pdp) account (learn more in the [docs](https://www.prisma.io/docs/platform/concepts/environments#api-keys))
+
+## Getting started
+
+### 1. Clone the respository
+
+Clone the repository, navigate into it and install dependencies:
+
+```
+git clone [email protected]:prisma/prisma-examples.git --depth=1
+cd prisma-examples/pulse/fullstack-leaderboard
+npm install
+```
+
+### 2. Configure environment variables
+
+Create a `.env` in the root of the project directory:
+
+```bash
+touch .env
+```
+
+Now, open the `.env` file and update the `DATABASE_URL` and `PULSE_API_KEY` environment variables with the values of your connection string and your Pulse API keys:
+
+```bash
+# .env
+DATABASE_URL="__YOUR_DATABASE_CONNECTION_STRING__"
+PULSE_API_KEY="__YOUR_PULSE_API_KEY__"
+```
+
+Note that `__YOUR_DATABASE_CONNECTION_STRING__` and `__YOUR_PULSE_API_KEY__` are **placeholder values that you must replace** with the values of your own connection string and Pulse API key.
+
+### 3. Run a database migration to create the `Player` table
+
+The [Prisma schema file](./prisma/schema.prisma) in this project contains a single `Player` model. You can map this model to the database and create the corresponding `Player` table using the following command:
+
+```
+npx prisma migrate dev --name init
+```
+
+You now have a table called `Player` in your database.
+
+Next, run the following command to [seed](./prisma/seed.ts) the database with some dummy data:
+
+```
+npx prisma db seed
+```
+
+The is invoked the [seed script](./prisma/seed.ts) and created three `Player` records in the database.
+
+
+### 4. Start the server
+
+Make sure you're inside the [`server`](./server) directory and start the long-running server that streams changes from the database:
+
+```
+npm run server
+```
+
+The server will accept WebSocket connections at `http://localhost:3001`.
+
+Next, run the Next.js app:
+
+```
+npm run dev
+```
+
+You can open the app at [`http://localhost:3000`](http://localhost:3000).
+
+Every new tab/window you open in your browser and point to that URL will instantiate its own WebSocket connection to the long-running server.
+
+### 5. Use the app
+
+Click on the buttons at the bottom to increase the score of a player and see how the leaderboard updates in real-time.
+
+## Deployment
+
+Because the app requires a [custom server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server) to enable the WebSocket connections, you need to deploy the frontend and the [backend](./src/server.ts) separately.
+
+### Deploying on Railway
+
+In the following, you find instructions to deploy the app via [Railway](https://railway.app). In order to deploy successfully, you need:
+- a Railway account
+- the Railway CLI installed on your machine
+
+
+#### Deploying the frontend
+
+Create a new
+
+#### Deploying the backend
+
+## Resources
+
+- [Pulse examples](https://pris.ly/pulse-examples)
+- [Pulse documentation](https://pris.ly/pulse-docs)
+- [Pulse announcement blog post](https://pris.ly/gh/pulse-ga)
+- [Prisma Discord](https://pris.ly/discord)

pulse/fullstack-leaderboard/next.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;

pulse/fullstack-leaderboard/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pulse-leaderboard",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "server": "ts-node --project tsconfig.server.json src/server.ts",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@prisma/client": "^5.14.0",
+    "@prisma/extension-pulse": "^1.1.0",
+    "@types/socket.io": "^3.0.2",
+    "next": "14.2.3",
+    "react": "^18",
+    "react-dom": "^18",
+    "react-flip-move": "^3.0.5",
+    "socket.io": "^4.7.5",
+    "socket.io-client": "^4.7.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "eslint": "^8",
+    "eslint-config-next": "14.2.3",
+    "postcss": "^8",
+    "prisma": "^5.14.0",
+    "tailwindcss": "^3.4.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5"
+  },
+  "prisma": {
+    "seed": "ts-node --project tsconfig.server.json prisma/seed.ts"
+  }
+}

pulse/fullstack-leaderboard/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    tailwindcss: {},
+  },
+};
+
+export default config;

pulse/fullstack-leaderboard/prisma/schema.prisma

@@ -0,0 +1,20 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+// Looking for ways to speed up your queries, or scale easily with your serverless or edge functions?
+// Try Prisma Accelerate: https://pris.ly/cli/accelerate-init
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Player {
+  id       Int    @id @default(autoincrement())
+  username String @unique
+  points   Int    @default(0)
+}

pulse/fullstack-leaderboard/prisma/seed.ts

@@ -0,0 +1,22 @@
+import { PrismaClient } from "@prisma/client";
+
+const prisma = new PrismaClient();
+
+async function main() {
+  const players = await prisma.player.createMany({
+    data: [
+      {
+        username: "Marc",
+      },
+      {
+        username: "Ankur",
+      },
+      {
+        username: "Jon",
+      },
+    ],
+  });
+  console.log(`Seeded the database with ${players.count} players.`);
+}
+
+main();

pulse/fullstack-leaderboard/src/app/actions.ts

@@ -0,0 +1,11 @@
+"use server";
+import prisma from "@/lib/prisma";
+
+export async function addPoints({ points, playerId }: { points: number; playerId: number }) {
+  console.log(`addPoints, `, points, playerId);
+  const updatedPlayer = await prisma.player.update({
+    where: { id: playerId },
+    data: { points: { increment: points } },
+  });
+  console.log(`Player ${updatedPlayer.username} now has ${updatedPlayer.points}.`);
+}