@farm.js/auth 0.1.49 → 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.
Files changed (2) hide show
  1. package/README.md +179 -0
  2. 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).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farm.js/auth",
3
- "version": "0.1.49",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "Farm-native authentication with email/password, server helpers, and React hooks",
5
5
  "license": "MIT",
6
6
  "repository": {