@farm.js/clerk 0.1.50 → 0.1.51-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +122 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,130 @@
1
1
  # @farm.js/clerk
2
2
 
3
- Clerk integration for Farm.js
3
+ Clerk authentication for Farm.js applications. The integration wraps the app in `ClerkProvider`
4
+ and can authenticate matched requests with Clerk's backend SDK before they reach a page. Clerk
5
+ keeps owning the UI, users, sessions, organizations, and account flows, so Farm creates no login,
6
+ callback, or session routes for it.
4
7
 
5
8
  See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
6
9
 
10
+ ## Install
11
+
7
12
  ```bash
8
- npm install @farm.js/clerk
13
+ pnpm add @farm.js/clerk @clerk/react
9
14
  ```
10
15
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
16
+ `@clerk/react` and `react` are peer dependencies: Farm loads `ClerkProvider` from the app's own
17
+ `@clerk/react`. `@clerk/backend` is a dependency and installs with the package. Clerk's components
18
+ require the React renderer. To scaffold the registry entry and sign-in screens in an existing app,
19
+ run `farm add integration clerk --ui`.
20
+
21
+ ## Configure
22
+
23
+ ```ts
24
+ import { defineConfig } from "@farm.js/core";
25
+ import { clerk } from "@farm.js/clerk";
26
+
27
+ export default defineConfig({
28
+ integrations: {
29
+ auth: clerk({
30
+ signInUrl: "/sign-in",
31
+ signUpUrl: "/sign-up",
32
+ protectedRoutes: ["/dashboard(.*)"],
33
+ }),
34
+ },
35
+ });
36
+ ```
37
+
38
+ Keys come from the environment unless they are passed as `publishableKey` and `secretKey`:
39
+
40
+ | Variable | Purpose |
41
+ | ----------------------------------- | ------------------------------------------------------------------------------- |
42
+ | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Publishable key, passed to `ClerkProvider`. Required. |
43
+ | `CLERK_PUBLISHABLE_KEY` | Fallback name for the publishable key. |
44
+ | `CLERK_SECRET_KEY` | Server key for request authentication. Required unless an `instance` is passed. |
45
+
46
+ Keep `CLERK_SECRET_KEY` in server-only environment variables, out of client code.
47
+
48
+ ## Pages and components
49
+
50
+ `signInUrl` and `signUpUrl` tell Farm where the app's Clerk pages live. They do not create the
51
+ pages, so add them with Clerk's components:
52
+
53
+ ```tsx
54
+ // src/app/sign-in/[...clerk]/page.tsx
55
+ "use client";
56
+
57
+ import { SignIn } from "@clerk/react";
58
+
59
+ export default function SignInPage() {
60
+ return (
61
+ <SignIn path="/sign-in" routing="path" signUpUrl="/sign-up" fallbackRedirectUrl="/dashboard" />
62
+ );
63
+ }
64
+ ```
65
+
66
+ Create the matching sign-up page with `SignUp`. Because Farm registers `ClerkProvider`, any client
67
+ component can use Clerk's hooks and components, such as `useUser`, `useAuth`, and `UserButton`,
68
+ without adding a provider of its own.
69
+
70
+ ## Protected routes
71
+
72
+ For a request matching `protectedRoutes`, Farm calls `authenticateRequest` from `@clerk/backend`:
73
+
74
+ - an authenticated request continues to the page or API handler;
75
+ - Clerk handshake and cookie responses are forwarded as they are;
76
+ - a signed-out request gets a `307` redirect to `signInUrl`, with the original pathname in
77
+ Clerk's `redirect_url`.
78
+
79
+ Clerk accepts the request origin as the only authorized party by default. List every trusted origin
80
+ when there are several:
81
+
82
+ ```ts
83
+ clerk({
84
+ authorizedParties: ["https://app.example.com", "https://admin.example.com"],
85
+ });
86
+ ```
87
+
88
+ ## Bring your own client
89
+
90
+ Pass a backend client through `instance` to keep Clerk construction in application code. The
91
+ secret key is then not required by Farm, but the publishable key still is, for `ClerkProvider`.
92
+
93
+ ```ts
94
+ import { createClerkClient } from "@clerk/backend";
95
+ import { clerk } from "@farm.js/clerk";
96
+
97
+ const clerkClient = createClerkClient({
98
+ secretKey: process.env.CLERK_SECRET_KEY,
99
+ publishableKey: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
100
+ });
101
+
102
+ export const auth = clerk({
103
+ instance: clerkClient,
104
+ protectedRoutes: ["/dashboard(.*)"],
105
+ });
106
+ ```
107
+
108
+ Without an instance, Farm creates one backend client lazily, on the first protected request.
109
+
110
+ ## Options
111
+
112
+ | Option | Default | Notes |
113
+ | ------------------- | ------------------- | -------------------------------------------------- |
114
+ | `instance` | | Existing Clerk backend client. |
115
+ | `publishableKey` | publishable key env | |
116
+ | `secretKey` | `CLERK_SECRET_KEY` | Not needed with `instance`. |
117
+ | `signInUrl` | `/sign-in` | App-owned sign-in page. |
118
+ | `signUpUrl` | `/sign-up` | App-owned sign-up page. |
119
+ | `protectedRoutes` | | One matcher or a list. |
120
+ | `authorizedParties` | request origin | Origins accepted by request authentication. |
121
+ | `providerProps` | | Extra `ClerkProvider` props, such as `appearance`. |
122
+ | `log` | | Integration lifecycle logger. |
123
+
124
+ ## Documentation
125
+
126
+ - [Clerk integration](https://farmjs.dev/docs/integrations/auth/clerk)
127
+ - [Auth integrations overview](https://farmjs.dev/docs/integrations/auth)
128
+
129
+ Report issues and find examples in the
130
+ [Farm.js repository](https://github.com/farming-labs/farm.js).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farm.js/clerk",
3
- "version": "0.1.50",
3
+ "version": "0.1.51-beta.1",
4
4
  "description": "Clerk integration for Farm.js",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -26,8 +26,8 @@
26
26
  },
27
27
  "dependencies": {
28
28
  "@clerk/backend": "^3.2.14",
29
- "@farm.js/integration-utils": "0.1.50",
30
- "@farm.js/core": "0.1.50"
29
+ "@farm.js/integration-utils": "0.1.51-beta.1",
30
+ "@farm.js/core": "0.1.51-beta.1"
31
31
  },
32
32
  "peerDependencies": {
33
33
  "@clerk/react": "^6.4.3",