You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Nuxt 3](https://nuxt.com) integration for [EdgeDB](https://www.edgedb.com) that aims at being the fastest way to add a fully typed database layer to your Nuxt 3 project.
9
-
10
-
-[✨ Release Notes](/CHANGELOG.md)
8
+
Integrate [Nuxt 3](https://nuxt.com) with [EdgeDB](https://www.edgedb.com) effortlessly, adding a robust database layer to your app with minimal configuration.
11
9
12
10
## Features
13
11
14
-
- 🍱 Zero-config setup; just add `nuxt-edgedb-module` to your `modules`
15
-
- 🧙 [EdgeDB CLI install](https://www.edgedb.com/docs/cli/index) and [project init](https://www.edgedb.com/docs/cli/edgedb_project/edgedb_project_init) wizards
16
-
- 🎩 Watchers on `dbschema/*`, `queries/*`, `dbschema/migrations/*` bringing _HMR_ to your database
17
-
- 🛟 Auto-imported typed database query client provided by [`@edgedb/generate`](https://www.edgedb.com/docs/clients/js/generation)
18
-
- 🍩 [`edgedb ui`](https://www.edgedb.com/docs/cli/edgedb_ui) injected into [Nuxt Devtools](https://github.com/nuxt/devtools)
19
-
20
-
⚠️ This is still very experimental project. Please do not use until it is properly announced.
12
+
- 🍱 **Effortless Integration**: Set up a database with just one line of configuration.
- 🎩 **Live Schema Updates**: Experience _HMR-like DX_ with watchers on `dbschema/*`, `queries/*`, and `dbschema/migrations/*`.
15
+
- 🛟 **Typed Query Generation**: Automatically generate a typed query client with [@edgedb/generate](https://www.edgedb.com/docs/clients/js/generation).
16
+
- 🍩 **Integrated Database Management**: Administer your database directly from [Nuxt DevTools](https://github.com/nuxt/devtools).
17
+
- 🔐 **Flexible Authentication**: Easily enable [Email](https://www.edgedb.com/docs/guides/auth/email_password) or [OAuth](https://www.edgedb.com/docs/guides/auth/oauth) authentication, with support for custom auth providers.
You can use EdgeDB like a server-only database exposed via `server/api` endpoints and `$fetch` on the client, avoiding the need for authentication.
176
+
177
+
But in some projects, you might want your users to login and have an identity on the server as well, luckily, the module got you covered.
178
+
179
+
> Before going through these auth installation steps, we strongly recommend you to check [EdgeDB Auth](https://www.edgedb.com/docs/guides/auth/index#auth) documentation.
180
+
181
+
### Enable `auth` option in your Nuxt configuration
182
+
183
+
```ts
184
+
exportdefaultdefineNuxtConfig({
185
+
modules: ['nuxt-edgedb-module'],
186
+
edgedb: {
187
+
auth: true
188
+
}
189
+
})
190
+
```
191
+
192
+
### Setup EdgeDB Auth in your schema
193
+
194
+
In this example, you can notice:
195
+
196
+
-`global current_user` which defines a [global property](https://www.edgedb.com/docs/datamodel/globals) linked to the client token identity
197
+
-`type User` is the model if your user, you are free to change it, that can be done later on thanks to migrations
198
+
-`access policy author_has_full_access` & `using (.author ?= global current_user);` defines the policy for the users to only have access to their own `BlogPost`
199
+
200
+
```esdl
201
+
// dbschema/default.esdl
202
+
using extension auth;
203
+
204
+
module default {
205
+
global current_user := (
206
+
assert_single((
207
+
select User { id, name }
208
+
filter .identity = global ext::auth::ClientTokenIdentity
209
+
))
210
+
);
211
+
212
+
type User {
213
+
required name: str;
214
+
required identity: ext::auth::Identity;
215
+
}
216
+
217
+
type BlogPost {
218
+
property content: str {
219
+
default := 'My blog post content.';
220
+
};
221
+
property title: str {
222
+
default := 'My blog post';
223
+
};
224
+
required author: User;
225
+
226
+
access policy author_has_full_access
227
+
allow all
228
+
using (.author ?= global current_user);
229
+
230
+
access policy others_read_only
231
+
allow select;
232
+
}
233
+
}
234
+
```
235
+
236
+
You can edit that schema while your server is running and accept the prompt to auto-migrate.
237
+
238
+
If you are doing these edits while the server is off, you can run `edgedb migration create` and `edgedb migrate`.
239
+
240
+
### Setup EdgeDB auth in your server
241
+
242
+
You will need to enable auth providers on your EdgeDB server.
243
+
244
+
That can be done through DevTools, in the `EdgeDB`.
245
+
246
+
Browse to your database, then inside `Auth Admin` tab.
247
+
248
+
There, you must specify:
249
+
250
+
-`auth_signing_key`
251
+
-`allowed_redirect_urls`
252
+
253
+
You also must enable some providers, you can usually start with `Email + Password`.
254
+
255
+
If you enable `required_verification`, you will need to configure a SMTP server for you EdgeDB instance.
256
+
257
+
You can find further instructions on how to use [Mailtrap](https://mailpit.axllent.org/docs/configuration/) locally to debug this feature [here](https://www.edgedb.com/docs/guides/auth/index#email-and-password).
258
+
259
+
> Do not forget these steps must also be performed on your production environment.
260
+
261
+
### Use authentication components on the client
262
+
263
+
As you enabled auth in your config, the module injected these components in your project:
<!-- Create a OAuth button behavior from a provider name -->
336
+
<EdgeDbOAuthButton
337
+
v-for="provider of providers"
338
+
:key="provider.name"
339
+
v-slot="{ redirect }"
340
+
:provider="provider.name"
341
+
>
342
+
<!-- Call `redirect` from the OAuthButton -->
343
+
<button @click="() => redirect()">
344
+
{{ provider.display_name }}
345
+
</button>
346
+
</EdgeDbOAuthButton>
347
+
</EdgeDbAuthProviders>
348
+
</template>
349
+
```
350
+
351
+
You will also need a call back page, that can use `EdgeDbAuthCallback`.
352
+
353
+
```vue
354
+
<template>
355
+
<EdgeDbOAuthCallback
356
+
v-slot="{ loading }"
357
+
redirect-to="/"
358
+
>
359
+
<div>
360
+
<h2>OAuth callback</h2>
361
+
<p v-if="loading">
362
+
Loading...
363
+
</p>
364
+
</UCard>
365
+
</EdgeDbOAuthCallback>
366
+
</template>
367
+
```
368
+
369
+
In just a few lines, you added a basic authentication to your application.
370
+
371
+
### Client-side usage
372
+
373
+
Now that you added authentication to your project, you also have access to the `useEdgeDbIdentity` composable in your Nuxt app.
374
+
375
+
```vue
376
+
<script setup lang="ts">
377
+
const { isLoggedIn } = useEdgeDbIdentity()
378
+
</script>
379
+
380
+
<template>
381
+
<div>
382
+
<LoginButton v-if="isLoggedIn" />
383
+
<LogoutButton v-else />
384
+
</div>
385
+
</template>
386
+
```
387
+
388
+
You can look at the [`useEdgeDbIdentity`](./src/runtime/composables/useEdgeDbIdentity.ts) for further usage.
389
+
390
+
### Server-side usage
391
+
392
+
The authentication does use a cookie called `edgedb-auth-token`.
393
+
394
+
On the server, if you want to authenticate your requests to the database for the current user, you only have to pass the current request object to composables:
395
+
396
+
```typescript
397
+
exportdefaultdefineEventHandler(async (req) => {
398
+
const { deleteBlogPost } =useEdgeDbQueries()
399
+
400
+
// Will throw an error, as you cannot delete a BlogPost without being its author.
You can also use _both_ and create Identity objects from your own authentication provider, and use `edgedb-auth-token` as your cookie.
424
+
425
+
I would recommend looking at [https://github.com/edgedb/edgedb-examples] that is filled with great examples of custom authentications built on EdgeDB.
EdgeDB Auth only provides bare minimal identity feature for authentication.
445
+
446
+
In the code example I provided, I added a `User` type that goes along with the `Identity` interface.
447
+
186
448
## Production
187
449
188
450
If you want to get out of development and deploy your database to prodution, you must follow [EdgeDB guides](https://www.edgedb.com/docs/guides/deployment/index).
@@ -191,6 +453,18 @@ If you want to get out of development and deploy your database to prodution, you
191
453
192
454
However, they also offer a [Cloud](https://www.edgedb.com/docs/guides/cloud), which is fully compatible with this module thanks to environment variables.
193
455
456
+
If you want to customize the [DSN] used by the composables, you can use the environment variables provided by the module:
457
+
458
+
```
459
+
NUXT_EDGEDB_HOST=
460
+
NUXT_EDGEDB_PORT=
461
+
NUXT_EDGEDB_USER=
462
+
NUXT_EDGEDB_PASS=
463
+
NUXT_EDGEDB_DATABASE=
464
+
```
465
+
466
+
> If you want to use the env variables, you have to specify **ALL** of them, otherwise the client will fallback on default values.
467
+
194
468
## Q&A
195
469
196
470
### Will my database client be exposed in userland?
@@ -242,6 +516,7 @@ No, as they are generated with your Nuxt client, you should add them to your `.g
242
516
**/*.edgeql.ts
243
517
dbschema/queries.*
244
518
dbschema/query-builder
519
+
queries/*.query.ts
245
520
```
246
521
247
522
You must change these paths accordingly if you change the `**Dir` options.
0 commit comments