feat(notifications): make notifications configurable by workshop

Author: kentcdodds

docs/configuration.md

@@ -25,6 +25,7 @@ These options should be set in the root `package.json` of your workshop.
 | `testTab.enabled`                      | `boolean` | Whether to enable the test tab           | `true`                                                                  |
 | `scripts.postupdate`                   | `string`  | Script to run after workshop update      | Optional                                                                |
 | `initialRoute`                         | `string`  | Initial route for the app                | `"/"`                                                                   |
+| `notifications`                        | `array`   | Custom notifications for this workshop   | `[]`                                                                    |
 
 ## Product Configuration
 
@@ -161,3 +162,57 @@ Here's an example of some configuration in the root `package.json`:
   }
 }
 ```
+
+### Workshop Notifications
+
+You can define custom notifications for your workshop using the `notifications`
+array in your `epicshop` config. These notifications are always shown to users
+of your workshop (unless expired or muted), and are not subject to product
+filtering like
+[remote notifications](https://gist.github.com/kentcdodds/c3aaa5141f591cdbb0e6bfcacd361f39).
+
+Each notification object can have the following fields:
+
+| Field       | Type   | Description                                                       |
+| ----------- | ------ | ----------------------------------------------------------------- |
+| `id`        | string | Unique identifier for the notification.                           |
+| `title`     | string | The notification title.                                           |
+| `message`   | string | The notification message.                                         |
+| `type`      | string | One of `info`, `warning`, or `danger`.                            |
+| `link`      | string | (Optional) A URL for users to learn more.                         |
+| `expiresAt` | date   | (Optional) A date after which the notification will not be shown. |
+
+**Note:**
+
+- Notifications defined in your workshop config are always included for your
+  users, regardless of the current product host/slug.
+- If `expiresAt` is set and is in the past, the notification will not be shown.
+- If a user mutes a notification, it will not be shown again for that user.
+- These notifications are merged with any remote notifications (such as those
+  from the Epicshop notification gist).
+
+#### Example
+
+```json
+{
+	"epicshop": {
+		// ...other config...
+		"notifications": [
+			{
+				"id": "custom-welcome",
+				"title": "Welcome to the Workshop!",
+				"message": "We're glad you're here. Check out the resources tab for more info.",
+				"type": "info"
+			},
+			{
+				"id": "new-feature",
+				"title": "New Feature",
+				"message": "We've added a new feature to the workshop. Check it out in the resources tab.",
+				"link": "https://www.epicweb.dev/new-feature",
+				"type": "info",
+				"expiresAt": "2025-07-01"
+			}
+		]
+	}
+}
+```

package-lock.json

@@ -13,6 +13,7 @@ import {
 	userHasAccessToWorkshop,
 } from '@epic-web/workshop-utils/epic-api.server'
 import { checkForUpdatesCached } from '@epic-web/workshop-utils/git.server'
+import { getUnmutedNotifications } from '@epic-web/workshop-utils/notifications.server'
 import { makeTimings } from '@epic-web/workshop-utils/timing.server'
 import {
 	getSetClientIdCookieHeader,
@@ -43,7 +44,6 @@ import { GeneralErrorBoundary } from './components/error-boundary.tsx'
 import { EpicProgress } from './components/progress-bar.tsx'
 import { EpicToaster } from './components/toaster.tsx'
 import { TooltipProvider } from './components/ui/tooltip.tsx'
-import { getUnmutedNotifications } from './routes/admin+/notifications.server.tsx'
 import { Notifications } from './routes/admin+/notifications.tsx'
 import { UpdateToast } from './routes/admin+/update-repo.tsx'
 import { useTheme } from './routes/theme/index.tsx'

packages/workshop-app/app/root.tsx

@@ -1,9 +1,9 @@
 import { muteNotification } from '@epic-web/workshop-utils/db.server'
+import { type getUnmutedNotifications } from '@epic-web/workshop-utils/notifications.server'
 import { json, type ActionFunctionArgs } from '@remix-run/node'
 import { useFetcher } from '@remix-run/react'
 import { useEffect, useRef } from 'react'
 import { toast } from 'sonner'
-import { type getUnmutedNotifications } from './notifications.server'
 
 export async function action({ request }: ActionFunctionArgs) {
 	const formData = await request.formData()

packages/workshop-app/app/routes/admin+/notifications.server.tsx

@@ -26,6 +26,7 @@
       "./git.server": "./src/git.server.ts",
       "./iframe-sync": "./src/iframe-sync.ts",
       "./playwright.server": "./src/playwright.server.ts",
+      "./notifications.server": "./src/notifications.server.ts",
       "./process-manager.server": "./src/process-manager.server.ts",
       "./test": "./src/test.ts",
       "./utils.server": "./src/utils.server.ts",
@@ -118,6 +119,12 @@
         "default": "./dist/esm/playwright.server.js"
       }
     },
+    "./notifications.server": {
+      "import": {
+        "types": "./dist/esm/notifications.server.d.ts",
+        "default": "./dist/esm/notifications.server.js"
+      }
+    },
     "./process-manager.server": {
       "import": {
         "types": "./dist/esm/process-manager.server.d.ts",
@@ -181,6 +188,7 @@
     "fs-extra": "^11.2.0",
     "globby": "^14.0.2",
     "ignore": "^5.3.2",
+    "json5": "^2.2.3",
     "lru-cache": "^11.0.1",
     "md5-hex": "^5.0.0",
     "mdast-util-mdx-jsx": "^3.1.3",

packages/workshop-app/app/routes/admin+/notifications.tsx

@@ -13,6 +13,7 @@ import {
 	type ProblemApp,
 	type SolutionApp,
 } from './apps.server.js'
+import { type Notification } from './notifications.server.js'
 import { cachifiedTimingReporter, type Timings } from './timing.server.js'
 import { checkConnectionCached } from './utils.server.js'
 
@@ -45,6 +46,8 @@ export const checkForUpdatesCache = makeSingletonCache<{
 	remoteCommit: string
 	diffLink: string | null
 }>('CheckForUpdatesCache')
+export const notificationsCache =
+	makeSingletonCache<Array<Notification>>('NotificationsCache')
 
 const cacheDir = path.join(os.homedir(), '.epicshop', 'cache')
 

packages/workshop-utils/package.json

@@ -79,6 +79,19 @@ const WorkshopConfigSchema = z
 			})
 			.optional(),
 		initialRoute: z.string().optional().default('/'),
+		notifications: z
+			.array(
+				z.object({
+					id: z.string(),
+					title: z.string(),
+					message: z.string(),
+					link: z.string().optional(),
+					type: z.enum(['info', 'warning', 'danger']),
+					expiresAt: z.date().nullable(),
+				}),
+			)
+			.optional()
+			.default([]),
 	})
 	.transform((data) => {
 		return {

packages/workshop-utils/src/cache.server.ts

@@ -0,0 +1,81 @@
+import json5 from 'json5'
+import { z } from 'zod'
+import { cachified, notificationsCache } from './cache.server.js'
+import { getWorkshopConfig } from './config.server.js'
+import { getMutedNotifications } from './db.server.js'
+
+const NotificationSchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	message: z.string(),
+	link: z.string().optional(),
+	type: z.enum(['info', 'warning', 'danger']),
+	products: z
+		.array(
+			z.object({
+				host: z.string(),
+				slug: z.string().optional(),
+			}),
+		)
+		.optional(),
+	expiresAt: z
+		.string()
+		.nullable()
+		.transform((val) => (val ? new Date(val) : null)),
+})
+
+export type Notification = z.infer<typeof NotificationSchema>
+
+async function getRemoteNotifications() {
+	return cachified({
+		key: 'notifications',
+		cache: notificationsCache,
+		ttl: 1000 * 60 * 60 * 6,
+		swr: 1000 * 60 * 60 * 24,
+		offlineFallbackValue: [],
+		async getFreshValue() {
+			const URL =
+				'https://gist.github.com/kentcdodds/c3aaa5141f591cdbb0e6bfcacd361f39'
+			const filename = 'notifications.json5'
+			const response = await fetch(`${URL}/raw/${filename}`)
+			const text = await response.text()
+			const json = json5.parse(text)
+
+			return NotificationSchema.array().parse(json)
+		},
+	}).catch(() => [])
+}
+
+export async function getUnmutedNotifications() {
+	if (ENV.EPICSHOP_DEPLOYED) return []
+
+	const remoteNotifications = await getRemoteNotifications()
+
+	const config = getWorkshopConfig()
+
+	const notificationsToShow = remoteNotifications
+		.filter((n) => {
+			if (n.expiresAt && n.expiresAt < new Date()) {
+				return false
+			}
+			return true
+		})
+		.filter((n) => {
+			if (!n.products) return true
+			return n.products.some((p) => {
+				return (
+					p.host === config.product.host &&
+					(p.slug ? p.slug === config.product.slug : true)
+				)
+			})
+		})
+		.concat(config.notifications)
+
+	const muted = await getMutedNotifications()
+
+	const visibleNotifications = notificationsToShow.filter(
+		(n) => !muted.includes(n.id),
+	)
+
+	return visibleNotifications
+}