feat(fastify)!: Support Fastify v5 (#4270)

.changeset/wise-onions-double.md

@@ -0,0 +1,9 @@
+---
+"@clerk/fastify": major
+---
+
+Recently Fastify released its v5 and along with it came some breaking changes. Read their [migration guide](https://fastify.dev/docs/latest/Guides/Migration-Guide-V5/) to learn more.
+
+In order to support Fastify v5 a new major version of `@clerk/fastify` is required as Fastify's Node.js requirement is now `>=20`. Previously `@clerk/fastify` allowed `>=18.17.0`.
+
+`@clerk/fastify@2.0.0` only supports Fastify v5 or later, if you want/need to continue using Fastify v4, please stick with your current version. The `@clerk/fastify@2.0.0` upgrade itself doesn't have any required code changes as only internal dependencies and requirements were updated.

.github/workflows/ci.yml

@@ -115,7 +115,7 @@ jobs:
         run: |
           if [ "${{ matrix.node-version }}" == "18" ]; then
             echo "Running tests on Node 18 only for packages with LTS support."
-            npx turbo test $TURBO_ARGS --filter="@clerk/astro" --filter="@clerk/backend" --filter="@clerk/express" --filter="@clerk/nextjs" --filter="@clerk/clerk-react" --filter="@clerk/fastify" --filter="@clerk/clerk-sdk-node" --filter="@clerk/shared" --filter="@clerk/remix" --filter="@clerk/tanstack-start" --filter="@clerk/elements"
+            npx turbo test $TURBO_ARGS --filter="@clerk/astro" --filter="@clerk/backend" --filter="@clerk/express" --filter="@clerk/nextjs" --filter="@clerk/clerk-react" --filter="@clerk/clerk-sdk-node" --filter="@clerk/shared" --filter="@clerk/remix" --filter="@clerk/tanstack-start" --filter="@clerk/elements"
           else
             echo "Running tests for all packages on Node 20."
             npx turbo test $TURBO_ARGS

package.json

@@ -80,8 +80,6 @@
     "eslint": "^8.49.0",
     "execa": "^5.1.1",
     "expect-type": "^0.16.0",
-    "fastify": "4.12.0",
-    "fastify-plugin": "^4.5.0",
     "fs-extra": "^11.1.1",
     "get-port": "^5.1.1",
     "globby": "^13.2.2",

packages/fastify/README.md

@@ -31,8 +31,8 @@
 
 ### Prerequisites
 
-- Fastify `^4.0.0` or later
-- Node.js `>=18.17.0` or later
+- Fastify `^5.0.0` or later
+- Node.js `>=20.0.0` or later
 - An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_fastify).
 
 ### Installation

packages/fastify/package.json

@@ -43,20 +43,21 @@
     "@clerk/backend": "1.13.8",
     "@clerk/shared": "2.9.0",
     "@clerk/types": "4.25.0",
-    "cookies": "0.8.0"
+    "cookies": "0.8.0",
+    "fastify-plugin": "^5.0.1"
   },
   "devDependencies": {
     "@clerk/eslint-config-custom": "*",
-    "@types/node": "^18.19.33",
+    "@types/node": "^20.14.8",
+    "fastify": "^5.0.0",
     "tsup": "*",
     "typescript": "*"
   },
   "peerDependencies": {
-    "fastify": ">=4",
-    "fastify-plugin": "^4.5.0"
+    "fastify": ">=5"
   },
   "engines": {
-    "node": ">=18.17.0"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"

packages/fastify/src/clerkPlugin.ts

@@ -17,13 +17,12 @@ const plugin: FastifyPluginCallback<ClerkFastifyOptions> = (
     throw new Error(`Unsupported hookName: ${hookName}`);
   }
 
-  // @ts-expect-error unions don't play well with TS overload signatures
   instance.addHook(hookName, withClerkMiddleware(opts));
 
   done();
 };
 
 export const clerkPlugin = fp(plugin, {
   name: '@clerk/fastify',
-  fastify: '4.x',
+  fastify: '5.x',
 });

playground/fastify/.env.sample

@@ -1 +1,4 @@
-CLERK_API_KEY=
+CLERK_PUBLISHABLE_KEY=
+CLERK_SECRET_KEY=
+PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+FRONTEND_API_URL=

playground/fastify/README.md

@@ -1,31 +1,26 @@
-## Setup development
+# playground-fastify
 
-Execute in root folder:
+Use this example app to test `@clerk/fastify`.
 
-```bash
-npm i
-npm run build && npm run yalc:all
-```
+## Usage
 
-Execute in current folder:
+1. Install dependencies
 
-```bash
-touch .env # set PUBLISHABLE_KEY and SECRET_KEY from Clerk Dashboard API keys
-npm i
-rm -rf node_modules/@clerk
-yalc add @clerk/fastify @clerk/backend @clerk/types --pure
+```shell
+npm install
 ```
 
-## Getting Started
+1. Use [`@clerk/dev-cli`](https://github.com/clerk/javascript/tree/main/packages/dev-cli) to build all repository packages and install the local version into this playground.
 
-First, run the development server:
+1. Start the server:
 
-```bash
+```shell
 npm run start
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-## Reload changes from packages/\* package
+You can visit these routes:
 
-Apply change in packages/\* project folder and run `npm run build`. Then restart Fastify server by killing the current and executing `npm start` and the change should be visible.
+- `/`
+- `/sign-in`
+- `/me` (requires sign-in)
+- `/private` (requires sign-in)

playground/fastify/package.json

@@ -6,21 +6,20 @@
     "start": "ts-node ./src/server.ts"
   },
   "dependencies": {
-    "@clerk/backend": "file:.yalc/@clerk/backend",
-    "@clerk/fastify": "file:.yalc/@clerk/fastify",
-    "@clerk/shared": "file:.yalc/@clerk/shared",
-    "@clerk/types": "file:.yalc/@clerk/types",
-    "@fastify/view": "^8.0.0",
-    "dotenv": "^16.0.3",
-    "ejs": "^3.1.9",
-    "fastify": "^4.12.0",
-    "ts-node": "^10.9.1"
+    "@clerk/backend": "^1.13.6",
+    "@clerk/fastify": "^1.0.49",
+    "@clerk/shared": "^2.8.4",
+    "@clerk/types": "^4.23.0",
+    "@fastify/view": "^10.0.1",
+    "dotenv": "^16.4.5",
+    "ejs": "^3.1.10",
+    "fastify": "^5.0.0",
+    "ts-node": "^10.9.2"
   },
   "devDependencies": {
-    "@types/ejs": "^3.1.2",
-    "@types/node": "^18.11.18",
-    "eslint": "8.24.0",
-    "tslib": "^2.5.0",
-    "typescript": "4.8.4"
+    "@types/ejs": "^3.1.5",
+    "@types/node": "^20.14.8",
+    "tslib": "^2.7.0",
+    "typescript": "5.0.4"
   }
 }

playground/fastify/src/loadEnv.ts

@@ -1,2 +1,2 @@
 import * as dotenv from 'dotenv';
-dotenv.config();
+dotenv.config({ path: ['.env.local', '.env.production', '.env'] });

playground/fastify/src/routes/public.ts

@@ -1,16 +1,15 @@
 import type { FastifyInstance } from 'fastify';
 
 export const publicRoutes = async (fastify: FastifyInstance, _opts: any) => {
-  fastify.get('/public', async (_req, _reply) => {
+  fastify.get('/', async (_req, _reply) => {
     return { hello: 'world' };
   });
 
-  fastify.get('/home', async (_req, reply) => {
-    return reply.view('/src/templates/home.ejs', {
-      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
-      domain: process.env.CLERK_DOMAIN,
-      isSatellite: process.env.CLERK_IS_SATELLITE,
-      signInUrl: process.env.CLERK_SIGN_IN_URL,
+  fastify.get('/sign-in', async (_req, reply) => {
+    return reply.viewAsync('/src/templates/sign-in.ejs', {
+      CLERK_PUBLISHABLE_KEY: process.env.CLERK_PUBLISHABLE_KEY,
+      PUBLIC_CLERK_SIGN_IN_URL: process.env.PUBLIC_CLERK_SIGN_IN_URL,
+      FRONTEND_API_URL: process.env.FRONTEND_API_URL,
     });
   });
 };

playground/fastify/src/templates/sign-in.ejs

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script
+      async
+      crossorigin="anonymous"
+      data-clerk-publishable-key="<%= CLERK_PUBLISHABLE_KEY %>"
+      src="<%= FRONTEND_API_URL %>/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
+      type="text/javascript"
+      onLoad="startClerk()"
+    ></script>
+  </head>
+  <body>
+    <script>
+        window.startClerk = async () => {
+          await Clerk.load({
+            signInUrl: "<%= PUBLIC_CLERK_SIGN_IN_URL %>",
+          });
+          Clerk.openSignIn();
+        }
+    </script>
+  </body>
+</html>