@farm.js/auth 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.
- package/README.md +179 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# @farm.js/auth
|
|
2
|
+
|
|
3
|
+
Built-in email/password authentication for Farm.js applications. Set `auth: true` in
|
|
4
|
+
`farm.config.ts` and Farm mounts the auth routes, stores database-backed sessions, and exposes
|
|
5
|
+
server helpers and a React hook. Better Auth is the engine underneath, but application code never
|
|
6
|
+
configures or imports it.
|
|
7
|
+
|
|
8
|
+
See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pnpm add @farm.js/auth
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`react` is a peer dependency, used by the client hooks. Better Auth and the `pg` Postgres driver
|
|
17
|
+
install with the package. Local development opens SQLite through `node:sqlite` on Node 22 and later,
|
|
18
|
+
and falls back to the optional `better-sqlite3` dependency on older Node releases.
|
|
19
|
+
|
|
20
|
+
To start from a complete app instead:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm create @farm.js/app my-app --template auth
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Configure
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { defineConfig } from "@farm.js/core";
|
|
30
|
+
|
|
31
|
+
export default defineConfig({
|
|
32
|
+
auth: true,
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
This is the top-level `auth` framework key, not an `integrations.auth` provider. Farm loads this
|
|
37
|
+
package only when the key is enabled. Setting both `auth` and `integrations.auth` is a
|
|
38
|
+
configuration error, because each one owns the auth catch-all route.
|
|
39
|
+
|
|
40
|
+
With no other options, Farm:
|
|
41
|
+
|
|
42
|
+
- mounts `GET` and `POST` handlers at `/api/auth/[...auth]`;
|
|
43
|
+
- enables email/password sign-up and sign-in;
|
|
44
|
+
- creates database-backed sessions that last 7 days and refresh daily;
|
|
45
|
+
- uses `.farm/auth.sqlite` in development and updates its schema on first use;
|
|
46
|
+
- uses Postgres through `DATABASE_URL` in production.
|
|
47
|
+
|
|
48
|
+
## Server helpers
|
|
49
|
+
|
|
50
|
+
Read the current session or user in a Server Component, server function, middleware, or route
|
|
51
|
+
handler. Both return `null` for an anonymous request.
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { auth } from "@farm.js/auth/server";
|
|
55
|
+
|
|
56
|
+
const session = await auth.session();
|
|
57
|
+
const user = await auth.user();
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Pass `required: true` when the request must be signed in. An anonymous request then throws a `401`
|
|
61
|
+
response with the code `FARM_AUTH_REQUIRED`:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
const user = await auth.user({ required: true });
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Both helpers also accept an explicit `request`, as in this route middleware:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
// src/app/dashboard/middleware.ts
|
|
71
|
+
import { auth } from "@farm.js/auth/server";
|
|
72
|
+
|
|
73
|
+
export const config = {
|
|
74
|
+
runtime: "nodejs" as const,
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
export async function middleware(request: Request) {
|
|
78
|
+
const user = await auth.user({ request });
|
|
79
|
+
|
|
80
|
+
if (!user) {
|
|
81
|
+
return Response.redirect(new URL("/sign-in", request.url), 307);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Client helpers
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
"use client";
|
|
90
|
+
|
|
91
|
+
import { useAuth } from "@farm.js/auth/client";
|
|
92
|
+
|
|
93
|
+
export function AccountMenu() {
|
|
94
|
+
const { user, isPending, signOut } = useAuth();
|
|
95
|
+
|
|
96
|
+
if (isPending) return <span>Loading</span>;
|
|
97
|
+
if (!user) return <a href="/sign-in">Sign in</a>;
|
|
98
|
+
|
|
99
|
+
return <button onClick={() => signOut()}>Sign out {user.email}</button>;
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`useAuth` also returns `session`, `error`, `isRefetching`, `refetch`, `signIn`, and `signUp`. The
|
|
104
|
+
same functions are exported directly for forms that do not need the hook:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
import { signIn, signUp } from "@farm.js/auth/client";
|
|
108
|
+
|
|
109
|
+
await signUp({ name: "Ada Lovelace", email: "ada@example.com", password: "a-long-password" });
|
|
110
|
+
await signIn({ email: "ada@example.com", password: "a-long-password" });
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`getSession` is exported as well. When `basePath` is customized, create matching helpers once with
|
|
114
|
+
`createFarmAuthClient({ basePath: "/account/auth" })`. It also accepts `baseURL` for clients that
|
|
115
|
+
do not run in the browser.
|
|
116
|
+
|
|
117
|
+
## Options
|
|
118
|
+
|
|
119
|
+
| Option | Default | Notes |
|
|
120
|
+
| ------------------------------------------- | ------------------- | ------------------------------------------- |
|
|
121
|
+
| `enabled` | `true` | Set `false` to disable without removing it. |
|
|
122
|
+
| `appName` | `"Farm app"` | Name used in auth metadata and emails. |
|
|
123
|
+
| `basePath` | `"/api/auth"` | Route prefix. Must be a plain pathname. |
|
|
124
|
+
| `emailAndPassword` | enabled | Set `false` to disable. |
|
|
125
|
+
| `emailAndPassword.requireEmailVerification` | `false` | |
|
|
126
|
+
| `emailAndPassword.minPasswordLength` | `8` | |
|
|
127
|
+
| `emailAndPassword.maxPasswordLength` | `128` | |
|
|
128
|
+
| `session.expiresIn` | `604800` | Session lifetime in seconds. |
|
|
129
|
+
| `session.updateAge` | `86400` | Refresh interval in seconds. |
|
|
130
|
+
| `database.url` | `DATABASE_URL` | Postgres connection string. |
|
|
131
|
+
| `database.path` | `.farm/auth.sqlite` | Local SQLite file. |
|
|
132
|
+
| `database.migrateInDevelopment` | `true` | Update the local schema on first use. |
|
|
133
|
+
|
|
134
|
+
`auth: { enabled: true }` is equivalent to `auth: true`.
|
|
135
|
+
|
|
136
|
+
## Environment and deployment
|
|
137
|
+
|
|
138
|
+
| Variable | Purpose |
|
|
139
|
+
| ------------------ | ----------------------------------------------------------------------------------------- |
|
|
140
|
+
| `DATABASE_URL` | Postgres connection string. Required in production. |
|
|
141
|
+
| `FARM_AUTH_SECRET` | Signing secret, required in production. `AUTH_SECRET` and `BETTER_AUTH_SECRET` also work. |
|
|
142
|
+
| `FARM_AUTH_URL` | Public origin. `BETTER_AUTH_URL` is also read. Inferred on Vercel when unset. |
|
|
143
|
+
|
|
144
|
+
Without a secret, development generates a random one in `.farm/auth-secret` and reuses it across
|
|
145
|
+
restarts. Loading `farm.config.ts` and running `farm build` never connect to the database. Apply the
|
|
146
|
+
production schema before serving traffic:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
farm auth migrate
|
|
150
|
+
farm auth migrate --dry-run
|
|
151
|
+
farm auth migrate --write auth-schema.sql
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The first command applies the schema. `--dry-run` prints the statements and `--write` saves them to
|
|
155
|
+
a file, without changing the database. The command needs `DATABASE_URL` but not the secret.
|
|
156
|
+
|
|
157
|
+
Sign-in rate limiting keys on the client address Farm resolves for the request. Behind a proxy,
|
|
158
|
+
enable `server.trustProxy` so visitors are not all counted as the proxy's address.
|
|
159
|
+
|
|
160
|
+
## Entry points
|
|
161
|
+
|
|
162
|
+
- `@farm.js/auth/server`: the `auth.session()` and `auth.user()` helpers.
|
|
163
|
+
- `@farm.js/auth/client`: `useAuth`, `signIn`, `signUp`, `signOut`, `getSession`, and
|
|
164
|
+
`createFarmAuthClient`.
|
|
165
|
+
- `@farm.js/auth`: `resolveFarmAuthConfig` and the configuration and session types, such as
|
|
166
|
+
`FarmAuthConfig`, `FarmAuthSession`, and `FarmAuthUser`.
|
|
167
|
+
- `@farm.js/auth/internal`: loaded by Farm core and `farm auth migrate`. Applications do not
|
|
168
|
+
import it.
|
|
169
|
+
|
|
170
|
+
Use [`@farm.js/better-auth`](https://www.npmjs.com/package/@farm.js/better-auth) instead when the
|
|
171
|
+
application needs Better Auth plugins, adapters, social providers, or the raw instance API.
|
|
172
|
+
|
|
173
|
+
## Documentation
|
|
174
|
+
|
|
175
|
+
- [Built-in Authentication](https://farmjs.dev/docs/auth)
|
|
176
|
+
- [Auth Integrations](https://farmjs.dev/docs/integrations/auth)
|
|
177
|
+
|
|
178
|
+
Report issues and find examples in the
|
|
179
|
+
[Farm.js repository](https://github.com/farming-labs/farm.js).
|