docs: Add quick start links & update Bun example (#870)

- Link to quick starts - Adjust Bun example to match the docs - mainly added more comments, but also switched to token bucket as it's more interesting. - Remove the Next.js example that was mirroring the Vercel repo because I closed the PR. Will open a new one once Next.js 15 is out and we can show off more functionality.
arcjet · Jun 7, 2024 · ee3079f · ee3079f
1 parent d7a698f
commit ee3079f
Show file tree

Hide file tree

Showing 30 changed files with 103 additions and 308 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -340,31 +340,6 @@ updates:
       - dependency-name: eslint
         versions: [">=9"]
 
-  - package-ecosystem: npm
-    directory: /examples/nextjs-example
-    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:
-          - "*"
-    ignore:
-      # Ignore updates to the @types/node package due to conflict between
-      # Headers in DOM.
-      - dependency-name: "@types/node"
-        versions: [">18.18"]
-      # TODO(#539): Upgrade to eslint 9
-      - dependency-name: eslint
-        versions: [">=9"]
-
   - package-ecosystem: npm
     directory: /examples/nodejs-express-rl
     schedule:

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <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">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -15,20 +15,22 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the monorepo containing various [Arcjet][arcjet] open source packages
 for JS.
 
 ## Quick start
 
-- **Bun?** Use the [`@arcjet/bun`][npm-bun] package.
+- **Bun?** Use the [`@arcjet/bun`][npm-bun] package with our [Bun quick start
+  guide][bun-quick-start].
 - **Next.js?** Use the [`@arcjet/next`][npm-next] package with our [Next.js
   quick start guide][next-quick-start].
 - **Node.js?** Use the [`@arcjet/node`][npm-node] package with our [Node.js
   quick start guide][node-quick-start].
-- **SvelteKit?** Use the [`@arcjet/sveltekit`][npm-sveltekit] package.
+- **SvelteKit?** Use the [`@arcjet/sveltekit`][npm-sveltekit] package with our
+  [SvelteKit quick start guide][sveltekit-quick-start].
 
 ## Get help
 
@@ -199,9 +201,11 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [arcjet]: https://arcjet.com
 [npm-bun]: https://www.npmjs.com/package/@arcjet/bun
 [npm-next]: https://www.npmjs.com/package/@arcjet/next
+[bun-quick-start]: https://docs.arcjet.com/get-started/bun
 [next-quick-start]: https://docs.arcjet.com/get-started/nextjs
 [npm-node]: https://www.npmjs.com/package/@arcjet/node
 [node-quick-start]: https://docs.arcjet.com/get-started/nodejs
+[sveltekit-quick-start]: https://docs.arcjet.com/get-started/sveltekit
 [npm-sveltekit]: https://www.npmjs.com/package/@arcjet/sveltekit
 [discord-invite]: https://discord.gg/TPra6jqZDC
 [support]: https://docs.arcjet.com/support

diff --git a/analyze/README.md b/analyze/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,7 +17,7 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] local analysis engine.

diff --git a/arcjet-bun/README.md b/arcjet-bun/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,11 +17,15 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] SDK for [Bun.sh][bun-sh].
 
+## Getting started
+
+Visit the [quick start guide][quick-start] to get started.
+
 ## Example app
 
 Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
@@ -116,6 +120,7 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [arcjet]: https://arcjet.com
 [bun-sh]: https://bun.sh/
 [example-url]: https://example.arcjet.com
+[quick-start]: https://docs.arcjet.com/get-started/bun
 [example-source]: https://github.com/arcjet/arcjet-js-example
 [rate-limit-concepts-docs]: https://docs.arcjet.com/rate-limiting/concepts
 [shield-concepts-docs]: https://docs.arcjet.com/shield/concepts

diff --git a/arcjet-next/README.md b/arcjet-next/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,7 +17,7 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] SDK for the [Next.js][next-js] framework.
@@ -27,7 +27,7 @@ package.
 
 ## Getting started
 
-Visit [docs.arcjet.com][next-sdk-docs] to get started.
+Visit the [quick start guide][quick-start] to get started.
 
 ## Example app
 
@@ -130,6 +130,7 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [arcjet]: https://arcjet.com
 [next-js]: https://nextjs.org/
 [alt-sdk]: https://www.npmjs.com/package/@arcjet/node
+[quick-start]: https://docs.arcjet.com/get-started/nextjs
 [next-sdk-docs]: https://docs.arcjet.com/reference/nextjs
 [example-url]: https://example.arcjet.com
 [example-source]: https://github.com/arcjet/arcjet-js-example

diff --git a/arcjet-node/README.md b/arcjet-node/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,14 +17,18 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] SDK for [Node.js][node-js].
 
 **Looking for our Next.js framework SDK?** Check out the
 [`@arcjet/next`][alt-sdk] package.
 
+## Getting started
+
+Visit the [quick start guide][quick-start] to get started.
+
 ## Example app
 
 Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
@@ -129,6 +133,7 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [node-js]: https://nodejs.org/
 [alt-sdk]: https://www.npmjs.com/package/@arcjet/next
 [example-url]: https://example.arcjet.com
+[quick-start]: https://docs.arcjet.com/get-started/nodejs
 [example-source]: https://github.com/arcjet/arcjet-js-example
 [rate-limit-concepts-docs]: https://docs.arcjet.com/rate-limiting/concepts
 [shield-concepts-docs]: https://docs.arcjet.com/shield/concepts

diff --git a/arcjet-sveltekit/README.md b/arcjet-sveltekit/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,11 +17,15 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] SDK for [SvelteKit][sveltekit].
 
+## Getting started
+
+Visit the [quick start guide][quick-start] to get started.
+
 ## Example app
 
 Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
@@ -127,6 +131,7 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [arcjet]: https://arcjet.com
 [sveltekit]: https://kit.svelte.dev/
 [example-url]: https://example.arcjet.com
+[quick-start]: https://docs.arcjet.com/get-started/sveltekit
 [example-source]: https://github.com/arcjet/arcjet-js-example
 [rate-limit-concepts-docs]: https://docs.arcjet.com/rate-limiting/concepts
 [shield-concepts-docs]: https://docs.arcjet.com/shield/concepts

diff --git a/arcjet/README.md b/arcjet/README.md
@@ -1,7 +1,7 @@
 <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">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 
@@ -17,7 +17,7 @@
 </p>
 
 [Arcjet][arcjet] helps developers protect their apps in just a few lines of
-code. Implement rate limiting, bot protection, email verification & defense
+code. Implement rate limiting, bot protection, email verification, and defense
 against common attacks.
 
 This is the [Arcjet][arcjet] TypeScript and JavaScript SDK core.

diff --git a/decorate/README.md b/decorate/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 

diff --git a/duration/README.md b/duration/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 

diff --git a/eslint-config/README.md b/eslint-config/README.md
@@ -1,7 +1,7 @@
 <a href="https://arcjet.com" target="_arcjet-home">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/arcjet-logo-dark-planet-arrival.svg">
-    <img src="https://arcjet.com/arcjet-logo-light-planet-arrival.svg" alt="Arcjet Logo" height="144" width="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
   </picture>
 </a>
 

diff --git a/examples/bun-rl/index.ts b/examples/bun-rl/index.ts
@@ -1,13 +1,17 @@
-import arcjet, { fixedWindow, shield } from "@arcjet/bun";
+import arcjet, { shield, tokenBucket } from "@arcjet/bun";
 
 const aj = arcjet({
-  key: Bun.env.ARCJET_KEY!,
+  key: Bun.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
   rules: [
+    // Shield protects your app from common attacks like SQL injection
     shield({ mode: "LIVE" }),
-    fixedWindow({
-      mode: "LIVE",
-      max: 1,
-      window: "1m",
+    // 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
     }),
   ],
 });
@@ -16,30 +20,44 @@ const aj = arcjet({
 export default {
   port: 3000,
   fetch: aj.handler(async (req) => {
-    const decision = await aj.protect(req);
+    const userId = "user123"; // Replace with your authenticated user ID
+    const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
     console.log("Arcjet request ID", decision.id);
     console.log("Arcjet decision", decision.conclusion);
 
     if (decision.isDenied()) {
-      return new Response("Blocked", { status: 403 });
+      if (decision.reason.isRateLimit()) {
+        return new Response("Too many requests", { status: 429 });
+      } else {
+        return new Response("Forbidden", { status: 403 });
+      }
     }
 
     return new Response("Hello world");
   }),
 };
 
 // Or using the `Bun.serve()` API
-// const server = Bun.serve({
-//   port: 3000,
-//   fetch: aj.handler(async (req) => {
-//     const decision = await aj.protect(req);
+/*
+const server = Bun.serve({
+  port: 3000,
+  fetch: aj.handler(async (req) => {
+    const userId = "user123"; // Replace with your authenticated user ID
+    const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
+    console.log("Arcjet request ID", decision.id);
+    console.log("Arcjet decision", decision.conclusion);
 
-//     if (decision.isDenied()) {
-//       return new Response("Blocked", { status: 403 });
-//     }
+    if (decision.isDenied()) {
+      if (decision.reason.isRateLimit()) {
+        return new Response("Too many requests", { status: 429 });
+      } else {
+        return new Response("Forbidden", { status: 403 });
+      }
+    }
 
-//     return new Response("Hello world");
-//   }),
-// });
+    return new Response("Hello world");
+  }),
+});
 
-// console.log(`Listening on ${server.url}`);
+console.log(`Listening on ${server.url}`);
+*/
diff --git a/examples/nextjs-example/.env.local.example b/examples/nextjs-example/.env.local.example