@farm.js/clerk 0.1.50 → 0.1.51-beta.0
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.
- package/README.md +122 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,11 +1,130 @@
|
|
|
1
1
|
# @farm.js/clerk
|
|
2
2
|
|
|
3
|
-
Clerk
|
|
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
|
-
|
|
13
|
+
pnpm add @farm.js/clerk @clerk/react
|
|
9
14
|
```
|
|
10
15
|
|
|
11
|
-
|
|
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.
|
|
3
|
+
"version": "0.1.51-beta.0",
|
|
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/
|
|
30
|
-
"@farm.js/
|
|
29
|
+
"@farm.js/core": "0.1.51-beta.0",
|
|
30
|
+
"@farm.js/integration-utils": "0.1.51-beta.0"
|
|
31
31
|
},
|
|
32
32
|
"peerDependencies": {
|
|
33
33
|
"@clerk/react": "^6.4.3",
|