chore(examples): Add Hono + Node.js example (#538)

Closes #477 

This adds an example to show how to use Hono with their Node.js Adapter and the Arcjet Node.js SDK.

Note: This doesn't resolve the issue with Hono + Bun, since we'll need to investigate an SDK for Bun itself.

.github/dependabot.yml

@@ -323,6 +323,23 @@ updates:
         patterns:
           - "*"
 
+  - package-ecosystem: npm
+    directory: /examples/nodejs-hono-rl
+    schedule:
+      # Our dependencies should be checked daily
+      interval: daily
+    assignees:
+      - blaine-arcjet
+    reviewers:
+      - blaine-arcjet
+    commit-message:
+      prefix: deps(example)
+      prefix-development: deps(example)
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+
   - package-ecosystem: npm
     directory: /examples/nodejs-rl
     schedule:

.github/workflows/reusable-examples.yml

@@ -460,3 +460,43 @@ jobs:
       - name: Build
         working-directory: examples/nextjs-14-pages-wrap
         run: npm run build
+
+  nodejs-hono-rl:
+    name: Node.js + Hono + Rate Limit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # Environment security
+      - name: Harden Runner
+        uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            github.com:443
+            registry.npmjs.org:443
+
+      # Checkout
+      # Most toolchains require checkout first
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Language toolchains
+      - name: Install Node
+        uses: actions/setup-node@v4.0.0
+        with:
+          node-version: 20
+
+      # Workflow
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install example dependencies
+        working-directory: examples/nodejs-hono-rl
+        run: npm ci
+
+      - name: Build
+        working-directory: examples/nodejs-hono-rl
+        run: npm run build

.trunk/trunk.yaml

@@ -69,3 +69,4 @@ merge:
     - Build examples / Next.js 14 + NextAuth 4
     - Build examples / Next.js 14 + OpenAI
     - Build examples / Next.js 14 + Page Router + withArcjet
+    - Build examples / Node.js + Hono + Rate Limit

examples/nodejs-hono-rl/.env.local.example

@@ -0,0 +1 @@
+ARCJET_KEY=

examples/nodejs-hono-rl/.gitignore

@@ -0,0 +1,2 @@
+# Generated by TypeScript
+index.js

examples/nodejs-hono-rl/README.md

@@ -0,0 +1,42 @@
+<a href="https://arcjet.com" target="_arcjet-home">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-minimal-dark-mark-all.svg">
+    <img src="https://arcjet.com/arcjet-logo-minimal-light-mark-all.svg" alt="Arcjet Logo" height="128" width="auto">
+  </picture>
+</a>
+
+# Arcjet Rate Limit with Hono for Node.js
+
+This example shows how to use Arcjet with a Node.js
+[Hono](https://hono.dev/getting-started/nodejs) server.
+
+## How to use
+
+1. From the root of the project, install the SDK dependencies.
+
+   ```bash
+   npm ci
+   ```
+
+2. Enter this directory and install the example's dependencies.
+
+   ```bash
+   cd examples/nodejs-hono-rl
+   npm ci
+   ```
+
+3. Rename `.env.local.example` to `.env.local` and add your Arcjet key.
+
+4. Start the server.
+
+   ```bash
+   npm start
+   ```
+
+   This assumes you're using Node.js 20 or later because the `start` script
+   loads a local environment file with `--env-file`. If you're using an older
+   version of Node.js, you can use a package like
+   [dotenv](https://www.npmjs.com/package/dotenv) to load the environment file.
+
+5. Visit `http://localhost:3000/`.
+6. Refresh the page to trigger the rate limit.

examples/nodejs-hono-rl/index.ts

@@ -0,0 +1,39 @@
+import arcjet, { tokenBucket } from "@arcjet/node";
+import { serve, type HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+
+const aj = arcjet({
+  key: process.env.ARCJET_KEY!,
+  rules: [
+    // Create a token bucket rate limit. Other algorithms are supported.
+    tokenBucket({
+      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
+      characteristics: ["userId"], // track requests by a custom user ID
+      refillRate: 5, // refill 5 tokens per interval
+      interval: 10, // refill every 10 seconds
+      capacity: 10, // bucket maximum capacity of 10 tokens
+    }),
+  ],
+});
+
+const app = new Hono<{ Bindings: HttpBindings }>();
+
+app.get("/", async (c) => {
+  const userId = "user123"; // Replace with your authenticated user ID
+
+  const decision = await aj.protect(c.env.incoming, { userId, requested: 9 }); // Deduct 9 tokens from the bucket
+
+  if (decision.isDenied()) {
+    return c.json({ error: "Too Many Requests" }, 429);
+  }
+
+  return c.json({ message: "Hello Hono!" });
+});
+
+const port = 3000;
+console.log(`Server is running on port ${port}`);
+
+serve({
+  fetch: app.fetch,
+  port,
+});

examples/nodejs-hono-rl/package.json

@@ -0,0 +1,18 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "prestart": "npm run build",
+    "start": "node --env-file .env.local ./index.js",
+    "build": "tsc -p ."
+  },
+  "dependencies": {
+    "@arcjet/node": "file:../../arcjet-node",
+    "@hono/node-server": "^1.9.1",
+    "hono": "^4.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}

examples/nodejs-hono-rl/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "compilerOptions": {
+        "module": "ESNext",
+        "moduleResolution": "Node",
+        "target": "ES2022"
+    },
+    "include": ["index.ts"],
+    "exclude": ["node_modules"]
+}