add docs for caching and server timing

Author: kentcdodds

app/root.tsx

@@ -74,7 +74,7 @@ export const meta: V2_MetaFunction = () => {
 
 export async function loader({ request }: DataFunctionArgs) {
 	const cookieSession = await getSession(request.headers.get('Cookie'))
-	const timings = makeTimings('rootLoader')
+	const timings = makeTimings('root loader')
 	const userId = await time(() => getUserId(request), {
 		timings,
 		type: 'getUserId',

app/routes/_marketing+/index.tsx

@@ -1,16 +1,8 @@
-import type { HeadersFunction, V2_MetaFunction } from '@remix-run/node'
-import { logos, kodyRocket, stars } from './logos/logos.ts'
-import { combineServerTimings } from '~/utils/timing.server.ts'
+import type { V2_MetaFunction } from '@remix-run/node'
+import { kodyRocket, logos, stars } from './logos/logos.ts'
 
 export const meta: V2_MetaFunction = () => [{ title: 'Epic Notes' }]
 
-export const headers: HeadersFunction = ({ loaderHeaders, parentHeaders }) => {
-	const headers = {
-		'Server-Timing': combineServerTimings(parentHeaders, loaderHeaders),
-	}
-	return headers
-}
-
 export default function Index() {
 	return (
 		<main className="relative min-h-screen sm:flex sm:items-center sm:justify-center">

app/routes/users+/$username_+/notes.$noteId_.edit.tsx

@@ -1,12 +1,15 @@
 import { json, type DataFunctionArgs } from '@remix-run/node'
 import { useLoaderData } from '@remix-run/react'
 import { NoteEditor } from '~/routes/resources+/note-editor.tsx'
+import { requireUserId } from '~/utils/auth.server.ts'
 import { prisma } from '~/utils/db.server.ts'
 
-export async function loader({ params }: DataFunctionArgs) {
-	const note = await prisma.note.findUnique({
+export async function loader({ params, request }: DataFunctionArgs) {
+	const userId = await requireUserId(request)
+	const note = await prisma.note.findFirst({
 		where: {
 			id: params.noteId,
+			ownerId: userId,
 		},
 	})
 	if (!note) {

app/routes/users+/$username_+/notes.new.tsx

@@ -1,4 +1,12 @@
+import { json } from '@remix-run/router'
+import { type DataFunctionArgs } from '@remix-run/server-runtime'
 import { NoteEditor } from '~/routes/resources+/note-editor.tsx'
+import { requireUserId } from '~/utils/auth.server.ts'
+
+export async function loader({ request }: DataFunctionArgs) {
+	await requireUserId(request)
+	return json({})
+}
 
 export default function NewNoteRoute() {
 	return <NoteEditor />

app/routes/users+/$username_+/notes.tsx

@@ -1,37 +1,62 @@
-import { json, type DataFunctionArgs } from '@remix-run/node'
+import {
+	json,
+	type DataFunctionArgs,
+	type HeadersFunction,
+} from '@remix-run/node'
 import { Link, NavLink, Outlet, useLoaderData } from '@remix-run/react'
 import { twMerge } from 'tailwind-merge'
 import { GeneralErrorBoundary } from '~/components/error-boundary.tsx'
-import { requireUserId } from '~/utils/auth.server.ts'
 import { prisma } from '~/utils/db.server.ts'
 import { getUserImgSrc } from '~/utils/misc.ts'
+import {
+	combineServerTimings,
+	makeTimings,
+	time,
+} from '~/utils/timing.server.ts'
 
-export async function loader({ params, request }: DataFunctionArgs) {
-	await requireUserId(request, { redirectTo: null })
-	const owner = await prisma.user.findUnique({
-		where: {
-			username: params.username,
-		},
-		select: {
-			id: true,
-			username: true,
-			name: true,
-			imageId: true,
-		},
-	})
+export async function loader({ params }: DataFunctionArgs) {
+	const timings = makeTimings('notes loader')
+	const owner = await time(
+		() =>
+			prisma.user.findUnique({
+				where: {
+					username: params.username,
+				},
+				select: {
+					id: true,
+					username: true,
+					name: true,
+					imageId: true,
+				},
+			}),
+		{ timings, type: 'find user' },
+	)
 	if (!owner) {
 		throw new Response('Not found', { status: 404 })
 	}
-	const notes = await prisma.note.findMany({
-		where: {
-			ownerId: owner.id,
-		},
-		select: {
-			id: true,
-			title: true,
-		},
-	})
-	return json({ owner, notes })
+	const notes = await time(
+		() =>
+			prisma.note.findMany({
+				where: {
+					ownerId: owner.id,
+				},
+				select: {
+					id: true,
+					title: true,
+				},
+			}),
+		{ timings, type: 'find notes' },
+	)
+	return json(
+		{ owner, notes },
+		{ headers: { 'Server-Timing': timings.toString() } },
+	)
+}
+
+export const headers: HeadersFunction = ({ loaderHeaders, parentHeaders }) => {
+	return {
+		'Server-Timing': combineServerTimings(parentHeaders, loaderHeaders),
+	}
 }
 
 export default function NotesRoute() {

docs/caching.md

@@ -0,0 +1,82 @@
+# Caching
+
+The Epic Stack comes with caching utilities and a management dashboard that
+allows you to view and clear your cache. There are two caches built into the
+Epic Stack:
+
+- **SQLite**: This is a separate database from the main application database.
+  It's managed by LiteFS so the data is replicated across all instances of your
+  app. This can be used for long-lived cached values.
+- **LRU**: This is an in-memory cache that is used to store the results of
+  expensive queries or help deduplicate requests for data. It's not replicated
+  across instances and as it's in-memory it will be cleared when your app is
+  restarted. So this should be used for short-lived cached values.
+
+Caching is intended to be used for data that is expensive and/or slow to compute
+or retrieve. It can help you avoid costs or rate limits associated with making
+requests to third parties.
+
+It's important to note that caching should not be the first solution to slowness
+issues. If you've got a slow query, look into optimizing it with database
+indexes before caching the results.
+
+## Using the cache
+
+You won't typically interact directly with the caches. Instead, you will use
+[`cachified`](https://npm.im/cachified) which is a nice abstraction for cache
+management. We have a small abstraction on top of it which allows you to pass
+`timings` to work seamlessly with
+[the server timing utility](./server-timing.md).
+
+Let's say we're making a request to tito to get a list of events. Tito's API is
+kinda slow and our event details don't change much so we're ok speeding things
+up by caching them and utilizing the stale-while-revalidate features in
+cachified. Here's how you would use cachified to do this:
+
+```tsx
+import { cachified, cache } from '~/utils/cache.server.ts'
+import { type Timings } from '~/utils/timing.server.ts'
+
+const eventSchema = z.object({
+	/* the schema for events */
+})
+
+export async function getScheduledEvents({
+	timings,
+}: {
+	timings: Timings
+} = {}) {
+	const scheduledEvents = await cachified({
+		key: 'tito:scheduled-events',
+		cache,
+		timings,
+		getFreshValue: () => {
+			// do a fetch request to the tito API and stuff here
+			return [
+				/* the events you got from tito */
+			]
+		},
+		checkValue: eventSchema.array(),
+		// Time To Live (ttl): the cached value is considered valid for 24 hours
+		ttl: 1000 * 60 * 24,
+		// Stale While Revalidate (swr): if the cached value is less than 30 days
+		// expired, return it while fetching a fresh value in the background
+		staleWhileRevalidate: 1000 * 60 * 60 * 24 * 30,
+	})
+	return scheduledEvents
+}
+```
+
+With this setup, the first time you call `getScheduledEvents` it will make a
+request to the tito API and return the results. It will also cache the results
+in the `cache` (which is the SQLite cache). The next time you call
+`getScheduledEvents` it will return the cached value if the cached value is less
+than 30 days old. If the cached value is older than 24 hours, it will also make
+a request to the tito API in the. If the cache value is more than 30 days old,
+it will wait until the tito request is complete and then return the fresh value.
+
+Bottom line: You make the request much less often and users are never waiting
+for it.
+
+A lot more needs to be said on this subject (an entire workshop full!), but this
+should be enough to get you going!

docs/server-timing.md

@@ -0,0 +1,86 @@
+# Server Timing
+
+![Network tab of Chrome DevTools showing the Timing tab of a specific network call and an arrow pointing to the Server Timing section with the words "This is what server timings do"](https://github.com/epicweb-dev/epic-stack/assets/1500684/e5a28253-8204-43b1-8222-3f287d024ca5)
+
+The Epic Stack comes with a built-in server timing utility that allows you to
+measure the performance of your application. You can find it in the
+`app/utils/timing.server.ts` file. The idea is you can wrap a function in a
+`time` call and then use the timings object to generate a `Server-Timing` header
+which you can then use to have fine grained timing metrics for requests made in
+your app.
+
+You can
+[learn more about the Server Timing header on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing).
+The metrics passed in this header will be visually displayed in
+[the DevTools "Timing" tab](https://developer.chrome.com/docs/devtools/network/reference/#timing).
+
+## Usage
+
+Timings requires four parts:
+
+1. Setup Timings
+2. Time functions
+3. Create headers
+4. Send headers
+
+Here are all those parts in action in the `/user/:username/notes` route at the
+time of this writing:
+
+```tsx
+import {
+	combineServerTimings,
+	makeTimings,
+	time,
+} from '~/utils/timing.server.ts'
+
+export async function loader({ params }: DataFunctionArgs) {
+	const timings = makeTimings('notes loader') // <-- 1. Setup Timings
+	// 2. Time functions
+	const owner = await time(
+		() =>
+			prisma.user.findUnique({
+				where: {
+					username: params.username,
+				},
+				select: {
+					id: true,
+					username: true,
+					name: true,
+					imageId: true,
+				},
+			}),
+		{ timings, type: 'find user' },
+	)
+	if (!owner) {
+		throw new Response('Not found', { status: 404 })
+	}
+	// 2. Time functions
+	const notes = await time(
+		() =>
+			prisma.note.findMany({
+				where: {
+					ownerId: owner.id,
+				},
+				select: {
+					id: true,
+					title: true,
+				},
+			}),
+		{ timings, type: 'find notes' },
+	)
+	return json(
+		{ owner, notes },
+		{ headers: { 'Server-Timing': timings.toString() } }, // <-- 3. Create headers
+	)
+}
+
+export const headers: HeadersFunction = ({ loaderHeaders, parentHeaders }) => {
+	return {
+		'Server-Timing': combineServerTimings(parentHeaders, loaderHeaders), // <-- 4. Send headers
+	}
+}
+```
+
+You can
+[learn more about `headers` in the Remix docs](https://remix.run/docs/en/main/route/headers)
+(note, the Epic Stack has the v2 behavior enabled).