Merge pull request #2 from jzxhuang/pokemon-example-vercel-og

adds pokemon example using @vercel/og for image generation

Author: jzxhuang

.env.local.example

@@ -7,3 +7,7 @@ DISCORD_APP_PUBLIC_KEY=
 # Settings -> Bot
 # Required to register commands, not required to actually run the bot
 DISCORD_BOT_TOKEN=
+
+# Set this with your local ngrok URL for the pokemon images to be served correctly.
+# Ex: https://1b539072925d.ngrok.app
+ROOT_URL=

README.md

@@ -1,23 +1,27 @@
-# NextBot: Next.js Discord Bot Template that runs in the Edge Runtime
+# NextBot: Next.js Discord Bot Template that runs 100% at the Edge Runtime
 
-NextBot is a template for building and deploying a Discord bot with Next.js. It runs 100% in the edge runtime so you get
-lightning-fast responses and zero cold starts. It uses Discord interactions webhooks to receive and reply to commands.
+NextBot is a template for building and deploying a Discord bot with Next.js. It's configured to run fully at the edge,
+delivering lightning-fast responses with no cold starts.
 
 ![Demo GIF](docs/demo.gif)
 
 - Runs at the edge: Lightning-fast responses, no cold start.
 - Free & easy to deploy: Deploy to Vercel in seconds at no cost. No need to host a server or VM to run your bot! Don't
   bother with Heroku, EC2, etc.
-- Easy to extend: Since the bot is built on Next.js, you can easily build an accompanying webapp in the same repo.
+- Extensible and scalable: Leverage Next.js to pair a dashboard for your bot, or use features like `next/og` to generate
+  dynamic images!
 
 ## Try it out
 
-Join https://discord.gg/NmXuqGgkb3 to try out a demo of NextBot. Type one of these slash commands into the general
-channel:
+Join https://discord.gg/NmXuqGgkb3 to try out NextBot. Here are some commands I've added to the demo bot as an example
+of what you can build!
 
-- `/ping`
-- `/invite`
-- `/randompic`
+| Command      | Description                                                                                                                    |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `/pokemon`   | Returns an image that contains a Pokemon's sprite, name, and pokedex number. The image is generated dynamically using next/og. |
+| `/ping`      | Ping pong! The bot will respond with "Pong".                                                                                   |
+| `/invite`    | Returns a link to invite the bot to your own server.                                                                           |
+| `/randompic` | Returns a random picture.                                                                                                      |
 
 Or add NextBot to your own server with this link:
 https://discord.com/api/oauth2/authorize?client_id=837427503059435530&permissions=2147485696&scope=bot%20applications.commands
@@ -26,14 +30,16 @@ You can also send slash commands through DM to the bot as long as you're in a mu
 
 ## Development
 
-Node.js 18+ is required.
+See https://nextjs.org/docs/getting-started/installation for minimum requirements.
 
 ### Setup
 
+These steps only need to be done once.
+
 - Clone the repo. This is a
   [template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)
   so you can click the green "Use this template" button on GitHub to create your own repo!
-  - Run `yarn` to install dependencies.
+- Run `yarn` to install dependencies.
 - [Create a new Discord application](https://discord.com/developers/applications).
   - In the `Bot` settings of your Discord application, enable the `Message Content` intent.
 - Fill out environment variables:
@@ -57,6 +63,7 @@ For this guide, I'll be using ngrok.
 - In the Discord app settings, set `Interactions Endpoint URL` to `<YOUR_PUBLIC_TUNNELED_NGROK_URL>/api/interactions`.
   Make sure to use the `https` URL!
 - Save changes in the Discord app settings.
+- Set the value of `ROOT_URL` in `.env.local` to your ngrok URL.
 
 In order to verify your interactions endpoint URL, Discord will send a `PING` message to your bot, and the bot should
 reply with a PONG (see `src/pages/api/interactions.ts`). If this is successful, your bot is ready to go!
@@ -104,26 +111,33 @@ commands!
 
 - `src/app/api/interactions/route.ts`: This is the main route handler for the Interactions Endpoint. It receives
   interactions from Discord and handles them accordingly.
-- `src/discord/verify-incoming-request.ts`: Helper functions to verify incoming requests from Discord, as outlined in https://discord.com/developers/docs/interactions/receiving-and-responding#security-and-authorization.
+- `src/discord/verify-incoming-request.ts`: Helper functions to verify incoming requests from Discord, as outlined in
+  https://discord.com/developers/docs/interactions/receiving-and-responding#security-and-authorization.
 - `src/app/page.tsx`: A basic web page. This could be your admin portal or whatever you'd like!
 
 ## Why Next.js (instead of Express, serverless, or Cloudflare Workers)?
 
-NextBot leverages Next.js 13
-[Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) to receive and respond to
-interactions. But why Next.js instead of something like Express or serverless (AWS Lambda)?
-
-- Next.js is free and effortless to deploy on Vercel. Don't bother with trying to host your Express server
-- Compared to serverless, edge is faster (no cold start) and cheaper (Edge Runtimes have more generous free tiers and
-  are cheaper per request)
-
-A better comparison would be hosting a Discord bot on Cloudflare Workers, as shown in this
-[official Discord tutorial](https://discord.com/developers/docs/tutorials/hosting-on-cloudflare-workers). The Next.js
-edge runtime is built on Cloudflare Workers! Still, I think Next.js has some notable benefits:
-
-- Next.js has the advantage of being a full web-app framework, making it easy to build an accompanying web app to go
-  along with your Discord app!
-- Deploying on Vercel is not only simple, but it also scales out very effectively if you need to build a more complex
-  app (analytics, logging, integrations, etc.)
-  - You can use Next.js/Vercel features like [Dynamic Image Generation](NextBot is a template for building and deploying a Discord bot with Next.js. It runs 100% in the edge runtime so you get
-lightning-fast responses and zero cold starts).
+NextBot leverages Next.js [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)
+to receive and respond to interactions. Why Next.js instead of something like Express or serverless (AWS Lambda)?
+
+- Next.js is free and easy to deploy on Vercel. Don't bother with managing VMs, EC2 instances, etc.
+- Compared to serverless (i.e. AWS Lambda), edge is faster (no cold start) and cheaper (edge has a more generous free
+  tiers and is cheaper per request)
+- Next.js is a full web-app framework, making it easy to build an accompanying web app to go along with your Discord
+  app. An example of this can be seen in `src/app/page.tsx`.
+- You can use Next.js features like [@vercel/og](https://vercel.com/docs/functions/edge-functions/og-image-generation).
+  The `/pokemon` command demonstrates this! It generates a dynamic image at runtime, and responses are cached at the
+  edge.
+- Vercel scales out very effectively for a more complex Discord bot, for example if you need to add analytics, logging,
+  auth, etc.
+
+Note: Discord's official docs include a
+[full tutorial for hosting a Discord bot on Cloudflare Workers](https://discord.com/developers/docs/tutorials/hosting-on-cloudflare-workers).
+This is the best comparison to NextBot: Next's edge runtime is built on Cloudflare Workers!
+
+In the `/pokemon` command, I demonstrate some of the powerful Next.js features that can use!
+
+- The image in the response is generated dynamically using
+  [next/og](https://nextjs.org/docs/app/building-your-application/optimizing/metadata#dynamic-image-generation).
+- Requests to [PokeAPI](https://pokeapi.co/) are [cached automatically](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating) by Next.js
+- The dynamic image itself is also cached, so it only needs to be generated once.

assets/pokemon/Pokemon Hollow.ttf

@@ -14,7 +14,7 @@
     "dotenv": "^16.3.1",
     "ky": "^0.33.3",
     "nanoid": "^4.0.2",
-    "next": "^13.5.2",
+    "next": "^14.0.2",
     "postcss": "^8.4.30",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

assets/pokemon/Pokemon-Solid.ttf

@@ -20,6 +20,13 @@ export const runtime = "edge"
 
 // Your public key can be found on your application in the Developer Portal
 const DISCORD_APP_PUBLIC_KEY = process.env.DISCORD_APP_PUBLIC_KEY
+const ROOT_URL = process.env.VERCEL_URL
+  ? `https://${process.env.VERCEL_URL}`
+  : process.env.ROOT_URL || "http://localhost:3000"
+
+function capitalizeFirstLetter(s: string) {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
 
 /**
  * Handle Discord interactions. Discord will send interactions to this endpoint.
@@ -58,6 +65,80 @@ export async function POST(request: Request) {
           },
         })
 
+      case commands.pokemon.name:
+        if (!interaction.data.options || interaction.data.options?.length < 1) {
+          return NextResponse.json({
+            type: InteractionResponseType.ChannelMessageWithSource,
+            data: {
+              content: "Oops! Please enter a Pokemon name or Pokedex number.",
+              flags: MessageFlags.Ephemeral,
+            },
+          })
+        }
+
+        const option = interaction.data.options[0]
+        // @ts-ignore
+        const idOrName = String(option.value).toLowerCase()
+
+        try {
+          const pokemon = await fetch(`https://pokeapi.co/api/v2/pokemon/${idOrName}`).then((res) => {
+            return res.json()
+          })
+          const types = pokemon.types.reduce(
+            (prev: string[], curr: { type: { name: string } }) => [...prev, capitalizeFirstLetter(curr.type.name)],
+            []
+          )
+
+          const r = {
+            type: InteractionResponseType.ChannelMessageWithSource,
+            data: {
+              embeds: [
+                {
+                  title: capitalizeFirstLetter(pokemon.name),
+                  image: {
+                    url: `${ROOT_URL}/api/pokemon/${idOrName}`,
+                  },
+                  fields: [
+                    {
+                      name: "Pokedex",
+                      value: `#${String(pokemon.id).padStart(3, "0")}`,
+                    },
+                    {
+                      name: "Type",
+                      value: types.join("/"),
+                    },
+                  ],
+                },
+              ],
+            },
+          }
+          return NextResponse.json({
+            type: InteractionResponseType.ChannelMessageWithSource,
+            data: {
+              embeds: [
+                {
+                  title: capitalizeFirstLetter(pokemon.name),
+                  image: {
+                    url: `${ROOT_URL}/api/pokemon/${idOrName}`,
+                  },
+                  fields: [
+                    {
+                      name: "Pokedex",
+                      value: `#${String(pokemon.id).padStart(3, "0")}`,
+                    },
+                    {
+                      name: "Type",
+                      value: types.join("/"),
+                    },
+                  ],
+                },
+              ],
+            },
+          })
+        } catch (error) {
+          throw new Error("Something went wrong :(")
+        }
+
       case commands.randompic.name:
         const { options } = interaction.data
         if (!options) {

docs/demo.gif

@@ -0,0 +1,70 @@
+import { ImageResponse } from "next/og"
+
+export const runtime = "edge"
+
+/**
+ * Generates an image containing a
+ * Pokemon' name, Pokedex number, and image.
+ *
+ * Accepts either a Pokemon's name or Pokedex number as the slug.
+ * If the pokemon cannot be found, returns Unown.
+ *
+ * @see https://vercel.com/docs/functions/edge-functions/og-image-generation
+ *
+ * Responses are automatically cached in production.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/routing/route-handlers
+ */
+export async function GET(_: Request, { params }: { params: { slug: string } }) {
+  // From https://www.dafont.com/pokemon.font
+  const fontData = await fetch(new URL("../../../../../assets/pokemon/Pokemon-Solid.ttf", import.meta.url)).then(
+    (res) => res.arrayBuffer()
+  )
+
+  let name = "Unown"
+  let number = "???"
+  let exists = false
+
+  const { slug } = params
+
+  /** @see https://pokeapi.co/docs/v2#pokemon-section */
+  try {
+    const pokemon = await fetch(`https://pokeapi.co/api/v2/pokemon/${slug}`).then((res) => res.json())
+    name = pokemon.name
+    number = String(pokemon.id)
+    exists = true
+  } catch (_) {
+    // Pokemon doesn't exist, or some other error.
+    // We'll return Unown :)
+  }
+
+  return new ImageResponse(
+    (
+      <div
+        tw="flex h-full w-full items-center justify-center bg-white text-center text-4xl text-black"
+        style={{ fontFamily: "Pokemon" }}
+      >
+        <div tw="flex flex-col items-center text-center py-8 px-8">
+          <p tw="m-0 font-bold text-7xl tracking-wide capitalize">{name}</p>
+          <p tw="m-0 text-5xl pt-6 tracking-wider">#{number.padStart(3, "0")}</p>
+        </div>
+
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          alt={name}
+          tw="ml-5"
+          width="360"
+          height="360"
+          src={`https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/${
+            exists ? number : 201
+          }.png`}
+        />
+      </div>
+    ),
+    {
+      width: 960,
+      height: 540,
+      fonts: [{ name: "Pokemon", data: fontData, style: "normal" }],
+    }
+  )
+}

package.json

@@ -1,8 +1,13 @@
-import { getGlobalCommands } from "@/discord/client"
+import { APIApplication } from "discord-api-types/v10"
 
 export async function GlobalCommands() {
   try {
-    const commands = await getGlobalCommands({ appId: process.env.DISCORD_APP_ID! })
+    const commands = await fetch(`https://discord.com/api/v8/applications/${process.env.DISCORD_APP_ID}/commands`, {
+      headers: {
+        Authorization: `Bot ${process.env.DISCORD_BOT_TOKEN}`,
+      },
+      next: { revalidate: 60 * 5 },
+    }).then((res) => res.json() as Promise<APIApplication[]>)
     if (commands.length <= 0) {
       return <p className="pt-6">No commands found :(</p>
     }

src/app/api/interactions/route.ts

@@ -1,3 +1,4 @@
+import { Suspense } from "react"
 import { GlobalCommands } from "./global-commands"
 
 export default async function Page() {
@@ -33,7 +34,9 @@ export default async function Page() {
           This is an example of an admin portal might look like. It leverages RSCs to fetch the Slash commands
           associated with the Discord bot!
         </p>
-        <GlobalCommands />
+        <Suspense fallback={null}>
+          <GlobalCommands />
+        </Suspense>
       </section>
     </main>
   )