Nuxt EdgeDB

轻松将 Nuxt 3 与 EdgeDB 集成，以最少的配置为您的应用程序添加强大的数据库层。

特性

🍱 轻松集成：只需一行配置即可设置数据库。
🎩 实时模式更新：在模式、查询和迁移上体验具有监听器的类似 HMR 的 DX。
🛟 类型化查询生成：使用 @edgedb/generate 自动生成类型化查询客户端。
🍩 集成数据库管理：从 Nuxt DevTools 管理您的数据库。
🔐 灵活的身份验证：一键切换电子邮件或 OAuth 身份验证，并支持自定义身份验证提供程序。
🧙 初始指导：指导您完成 EdgeDB CLI 设置和项目初始化。

快速设置

将 nuxt-edgedb-module 依赖项添加到您的项目

npx nuxi@latest module add edgedb

将 nuxt-edgedb-module 添加到 nuxt.config.ts 的 modules 部分

export default defineNuxtConfig({
  modules: [
    'nuxt-edgedb-module'
  ]
})

在您的项目根目录中运行 npx nuxt-edgedb-module 以运行 CLI 设置向导。

npx nuxt-edgedb-module

就是这样！您的 Nuxt 项目现在有了一个数据库。✨

如果您尚未在计算机上安装 EdgeDB，则安装向导将帮助您安装它。

示例项目

如果要运行示例项目，则必须克隆此存储库并运行 playground。

由于 EdgeDB 无法在 Stackblitz 或 CodeSandbox 等 Web 容器环境中运行。

git clone [email protected]:Tahul/nuxt-edgedb.git
cd nuxt-edgedb
pnpm install
pnpm stub
cd playground
edgedb project init
npx nuxt-edgedb-module
pnpm run dev

模块选项

您可以从 nuxt.config.ts 文件配置模块的任何行为

export default defineNuxtConfig({
  modules: ['nuxt-edgedb-module'],
  edgeDb: {
    // Devtools integrations
    devtools: true,
    // Completely toggle watchers feature
    watch: true,
    // Enable or disable prompts on watch events
    watchPrompt: true,
    // Generate target for your queries and query builder
    generateTarget: 'ts',
    // dbschema/ dir
    dbschemaDir: 'dbschema',
    // Individual queries dir (useEdgeDbQueries composable)
    queriesDir: 'queries',
    // Toggle CLI install wizard
    installCli: true,
    // Toggles composables
    composables: true,
    // Toggles auto-injection on auth credentials
    injectDbCredentials: true,
    // Enables authentication integration
    auth: false,
    // Enables oauth integration
    oauth: false,
  }
})

服务器用法

该模块会自动导入 Nuxt 应用的 server/ 上下文中可用的所有组合式函数。

useEdgeDb

useEdgeDb 使用您的 Nuxt 环境配置公开来自 edgedb 导入的原始客户端。

// server/api/blogpost/[id].ts
import { defineEventHandler, getRouterParams } from 'h3'

export default defineEventHandler(async (req) => {
  const params = getRouterParams(req)
  const id = params.id
  const client = useEdgeDb()

  const blogpost = await client.querySingle(`
    select BlogPost {
      title,
      description
    } filter .id = <uuid>$id
  `, {
    id: id
  });

  return blogpost
})

useEdgeDbQueries

useEdgeDbQueries 公开来自 dbschema/queries.ts 的所有查询。

您不必向它们传递客户端。它们将使用由 useEdgeDb 生成的客户端，该客户端的作用域限定为当前请求。

// queries/getBlogPost.edgeql
select BlogPost {
  title,
  description
} filter .id = <uuid>$blogpost_id

// server/api/blogpost/[id].ts
import { defineEventHandler, getRouterParams } from 'h3'

export default defineEventHandler(async (req) => {
  const params = getRouterParams(req)
  const id = params.id
  const { getBlogpPost } = useEdgeDbQueries()
  const blogPost = await getBlogpost({ blogpost_id: id })

  return blogpost
})

您仍然可以直接从 #edgedb/queries 导入查询，并将来自 useEdgeDb() 的客户端传递给它们。

// server/api/blogpost/[id].ts
import { getBlogPost } from '#edgedb/queries'
import { defineEventHandler, getRouterParams } from 'h3'

export default defineEventHandler(async (req) => {
  const params = getRouterParams(req)
  const id = params.id
  const client = useEdgeDb()
  const blogPost = await getBlogpost(client, { blogpost_id: id })

  return blogpost
})

useEdgeDbQueryBuilder

useEdgeDbQueryBuilder 直接将生成的查询构建器公开到您的 server/ 上下文。

// server/api/blogpost/[id].ts
import { defineEventHandler, getRouterParams } from 'h3'

export default defineEventHandler(async (req) => {
  const params = getRouterParams(req)
  const id = params.id
  const client = useEdgeDb()
  const e = useEdgeDbQueryBuilder()

  const blogPostQuery = e.select(
    e.BlogPost,
    (blogPost) => ({
      id: true,
      title: true,
      description: true,
      filter_single: { id }
    })
  )

  const blogPost = await blogPostQuery.run(client)

  return blogpost
})

类型

EdgeDB 生成的所有接口都可以通过 #edgedb/interfaces 的导入获得。

<script setup lang="ts">
import type { BlogPost } from '#edgedb/interfaces'

defineProps<{ blogPost: BlogPost }>()
</script>

身份验证

您可以将 EdgeDB 用作通过 server/api 端点和客户端上的 $fetch 公开的仅限服务器的数据库，从而避免身份验证的需要。

但在某些项目中，您可能希望用户登录，以便他们也可以在服务器上拥有身份。幸运的是，该模块可以满足您的需求。

在执行这些身份验证安装步骤之前，我们强烈建议您阅读 EdgeDB 身份验证文档。

在您的 Nuxt 配置中启用 `auth` 选项

export default defineNuxtConfig({
  modules: ['nuxt-edgedb-module'],
  edgedb: {
    auth: true
  }
})

在您的模式中设置 EdgeDB 身份验证

在此示例中，您可以注意到

global current_user，它定义了一个链接到客户端令牌标识的全局属性。
type User 是用户的模型，您可以自由更改它，这可以通过迁移稍后完成。
access policy author_has_full_access & using (.author ?= global current_user); 定义了用户只能访问自己的 BlogPost 的策略。

// dbschema/default.esdl
using extension auth;

module default {
  global current_user := (
    assert_single((
      select User { id, name }
      filter .identity = global ext::auth::ClientTokenIdentity
    ))
  );

  type User {
    required name: str;
    required identity: ext::auth::Identity;
  }

  type BlogPost {
    property content: str {
      default := 'My blog post content.';
    };
    property title: str {
      default := 'My blog post';
    };
    required author: User;

    access policy author_has_full_access
      allow all
      using (.author ?= global current_user);

    access policy others_read_only
      allow select;
  }
}

您可以在服务器运行时编辑此模式，并接受提示消息以自动迁移。

如果您在服务器关闭时进行这些编辑，则可以运行 edgedb migration create 和 edgedb migrate。

在您的服务器中设置 EdgeDB 身份验证

您需要在您的 EdgeDB 服务器上启用身份验证提供程序。

这可以在您的 DevTools 中通过 EdgeDB 选项卡完成。

浏览您的数据库到 Auth Admin 并指定

auth_signing_key
allowed_redirect_urls

您还必须启用一些提供程序。例如，您可以从 Email + Password 开始。

如果您启用 required_verification，您将需要为您的 EdgeDB 实例配置 SMTP 服务器。

您可以在此处找到有关如何在本地使用 Mailtrap 来试用此功能的更多说明。

不要忘记，这些步骤也必须在您的生产环境中执行。

在客户端上使用身份验证组件

当您在配置中启用身份验证时，该模块会将这些组件注入到您的项目中

您可以查看这些组件的源代码以了解有关其道具的更多信息。

它们都是无样式组件，仅公开实现流畅身份验证流程的必要逻辑。

<template>
  <EdgeDbAuthEmailLogin
    v-slot="{ email, updateEmail, password, updatePassword, submit, loading }"
    redirect-to="/"
  >
    <div>
      <input
        type="email"
        :value="email"
        placeholder="[email protected]"
        @change="(e) => updateEmail(e.target.value)"
      >
      <input
        type="password"
        :value="password"
        placeholder="password"
        @change="(e) => updatePassword(e.target.value)"
      >
      <button
        type="button"
        @click="(e) => !loading && submit()"
      >
        {{ loading ? 'Loading' : 'Login' }}
      </button>
    </div>
  </EdgeDbAuthEmailLogin>
</template>

当然，您可以完全在本地重写这些组件中的任何一个，以实现您自己的身份验证流程。

OAuth

如果要使用 OAuth，则必须在 nuxt.config 中启用它

export default defineNuxtConfig({
  edgeDb: {
    oauth: true
  }
})

这会将两个新组件注入到您的应用中

EdgeDB 当前支持以下提供程序的 OAuth

Apple
Azure (Microsoft)
GitHub
Google

为了使 OAuth 正常工作，您必须通过 Nuxt DevTools 访问您的 EdgeDB 实例 UI。

浏览到您的数据库并访问“身份验证管理员”选项卡。

在您的提供程序列表中，您可以添加任何您想要的提供程序并配置必要的密钥（通常是客户端 appid 和 secret）。

不要忘记将您的提供程序的回调 URL 设置为您的 EdgeDB 身份验证管理员顶部列出的 URL。

然后，您可以在您的应用中创建一个简单的 OAuth 按钮，如下所示

<template>
  <!-- Gives access to all available auth providers -->
  <EdgeDbAuthProviders v-slot="{ oAuthProviders: providers }">
    <!-- Create a OAuth button behavior from a provider name -->
    <EdgeDbOAuthButton
      v-for="provider of providers"
      :key="provider.name"
      v-slot="{ redirect }"
      :provider="provider.name"
    >
      <!-- Call `redirect` from the OAuthButton -->
      <button @click="() => redirect()">
        {{ provider.display_name }}
      </button>
    </EdgeDbOAuthButton>
  </EdgeDbAuthProviders>
</template>

您还需要一个回调页面，该页面可以使用 EdgeDbAuthCallback。

<template>
  <EdgeDbOAuthCallback
    v-slot="{ loading }"
    redirect-to="/"
  >
    <div>
      <h2>OAuth callback</h2>
      <p v-if="loading">
        Loading...
      </p>
      </UCard>
    </div>
  </EdgeDbOAuthCallback>
</template>

太棒了，对吧？！只需几行代码，我们就为我们的应用程序添加了一个基本身份验证。

客户端用法

现在身份验证已实现，您还可以在 Nuxt 应用中访问 useEdgeDbIdentity 组合式函数。

<script setup lang="ts">
const { isLoggedIn } = useEdgeDbIdentity()
</script>

<template>
  <div>
    <LoginButton v-if="isLoggedIn" />
    <LogoutButton v-else />
  </div>
</template>

您可以查看 useEdgeDbIdentity 以了解更多详细信息。

服务器端用法

身份验证过程确实使用了一个名为 edgedb-auth-token 的 cookie。

在服务器上，如果您想为当前用户对数据库进行身份验证，您只需将当前请求对象传递给组合式函数

export default defineEventHandler(async (req) => {
  // Will throw an error, as you cannot delete a BlogPost without being the author
  const { deleteBlogPost } = useEdgeDbQueries()
  await deleteBlogPost({ blogpost_id: id })

  // Success
  const { deleteBlogPost: deleteBlogPostAuthenticated } = useEdgeDbQueries(req)
  await deleteBlogPostAuthenticated({ blogpost_id: id })

  return { id }
})

其他身份验证解决方案

EdgeDDB 身份验证是一个很好的解决方案，但您的应用程序最终可能需要更多功能。

不要忘记，EdgeDB 也可以用作数据库。您可以构建自己的身份验证或使用现有的解决方案，例如

您也可以同时使用并从您自己的身份验证提供程序创建 Identity 对象，并使用 edgedb-auth-token 作为您的 cookie。

我建议您查看 https://github.com/edgedb/edgedb-examples，其中包含大量基于 EdgeDB 构建的自定义身份验证示例。

身份验证环境变量

# Your EdgeDB instance auth extension base URL
NUXT_EDGEDB_AUTH_BASE_URL=https://127.0.0.1:10702/db/edgedb/ext/auth/
# Your EdgeDB instance OAuth callback URL
NUXT_EDGEDB_OAUTH_CALLBACK=https://127.0.0.1:10702/db/edgedb/ext/auth/callback
# Your app callback page
NUXT_EDGEDB_OAUTH_REDIRECT_URL=https://127.0.0.1:3000/auth/callback
# Your app app reset password URL (receiving the token from the forgot password email)
NUXT_EDGEDB_AUTH_RESET_PASSWORD_URL=https://127.0.0.1:3000/auth/reset-password
# Your app email verify url (receiving the token from email verify feature)
NUXT_EDGEDB_AUTH_VERIFY_REDIRECT_URL=https://127.0.0.1:3000/auth/verify

进一步了解身份验证

EdgeDB 身份验证仅为身份验证提供最基本的身份功能。

在身份验证设置提供的代码示例中，User 类型与 Identity 接口一起使用。

如果要在注册时使用其他属性填充 User，则必须自己实现此行为。

如果要从 OAuth 提供程序解析数据，则可以使用来自 Nitro 插件的名为 edgedb:auth:callback 的 Nitro 钩子。

// server/plugins/auth.ts

export default defineNitroPlugin((app) => {
  app.hooks.hook('edgedb:auth:callback', (data) => {
    const {
      code,
      verifier,
      codeExchangeUrl,
      codeExchangeResponseData,
    } = data

    // codeExchangeResponseData contains the OAuth token from the provider.
    // ... implement your own authentication logic.
  })
})

生产环境

如果要退出开发并将数据库部署到生产环境，则必须遵循 EdgeDB 指南。

EdgeDB 是一个设计为自托管的开源数据库。

但是，他们还提供了一个 Cloud，由于环境变量，它与此模块完全兼容。

如果要自定义组合式函数使用的 DSN，可以使用模块提供的环境变量

NUXT_EDGEDB_HOST=
NUXT_EDGEDB_PORT=
NUXT_EDGEDB_USER=
NUXT_EDGEDB_PASS=
NUXT_EDGEDB_DATABASE=

如果要使用 env 变量，则必须指定所有变量，否则客户端将回退到默认值。

问答

我的数据库客户端会暴露在用户空间中吗？

不会，useEdgeDb 和 useEdgeDbQueries 仅在 Nuxt 的 server/ 上下文中可用。

作为选择加入功能，您可以在客户端上从 @dbschema/queries 导入查询。

您需要使用 createClient() 的客户端向这些查询提供。

<script setup lang="ts">
import { createClient } from 'edgedb'
import { getUser } from '@dbschema/queries'

const client = createClient()
const user = await getUser(client, 42)
</script>

您还可以作为选择加入功能，将查询构建器导入客户端。

我想这对于超级管理员/内部仪表板可能很有用，但请自行承担安全访问方面的风险。

<script setup lang="ts">
import e, { type $infer } from '#edgedb/builder'

const query = e.select(e.Movie, () => ({ id: true, title: true }))
type result = $infer<typeof query>
//   ^ { id: string; title: string }[]
</script>

请注意这些导入，因为如果您导入错误的查询，则最终可能会在客户端上获得可用的写入操作，从而可能损坏您的数据库。

如何在生产环境中运行迁移？

在您的生产环境中克隆您的 Nuxt 项目
确保服务器上安装了 EdgeDB CLI
将 edgedb migrate --quiet 添加到您的 CLI 脚本

我应该对生成的文件进行版本控制吗？

不应该，因为它们是使用您的 Nuxt 客户端生成的，所以您应该将它们添加到您的 .gitignore 中

**/*.edgeql.ts
dbschema/queries.*
dbschema/query-builder
dbschema/interfaces.ts
queries/*.query.ts

如果您更改 **Dir 选项，则必须相应地更改这些路径。

我的数据库模式的 HMR 真的安全吗？

嗯，这取决于您何时想使用它。

我建议在您随意开发项目时保持 watchPrompt 启用。

这将防止运行任何不需要的迁移，并且仅在您向模式添加新内容时才会提示。

如果您想快速操作并且知道自己在做什么，可以将 watchPrompt 设置为 false，并在模式发生任何更改时自动创建和应用迁移。

如果您不想要这些功能中的任何一个，只需将 watch 设置为 false，并对应用于开发数据库的更改感到安全。

数据库上的 HMR 显然在生产环境中没有效果。

为什么名称不是 `nuxt-edgedb`

因为该句柄在 NPM 上已被占用。

它似乎被 ohmree 占用，但该软件包似乎不活跃。

如果有人碰巧认识他，我很乐意与他取得联系！

贡献

此集成仍有许多很棒的功能可以构建。

我很乐意接收和审查任何 Pull Request。

开发

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release