Back to Details

fragno

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fragno Integration

Fragno 集成

Overview

概述

Fragno is a framework-agnostic, type-safe full-stack TypeScript toolkit that enables building portable full-stack libraries called "fragments". Fragments include backend routes, (optional) client hooks and (optional) database integration.
Important: Before integrating any first-party fragment, always fetch its docs with 
curl
. Use the same search endpoint to find the right page, then fetch the full Markdown docs:
  • curl -s "https://fragno.dev/api/search?query=forms"
  • curl -L "https://fragno.dev/docs/forms/quickstart" -H "accept: text/markdown"
This skill will aid you to integrate a Fragment into an application. To do this we have to mount the Fragment's backend routes, migrate/generate the database schema, and initialize the client-side hooks.
Fragno 是一个与框架无关、类型安全的全栈TypeScript工具包，可用于构建名为“fragments”的可移植全栈库。Fragments包含后端路由、（可选的）客户端hooks以及（可选的）数据库集成。
重要提示：在集成任何官方fragment之前，请务必使用
curl
获取其文档。使用相同的搜索端点找到对应页面，然后获取完整的Markdown文档：
  • curl -s "https://fragno.dev/api/search?query=forms"
  • curl -L "https://fragno.dev/docs/forms/quickstart" -H "accept: text/markdown"
本指南将帮助你把Fragment集成到应用中。为此，我们需要挂载Fragment的后端路由、迁移/生成数据库架构，并初始化客户端hooks。

High-level Workflow

整体工作流程

  1. Install the Fragment
  2. Mount the Fragment's backend routes
  3. Initialize the client-side hooks
  4. (Optionally) Database integration
  5. (Optionally) Setup middleware for Fragment-defined routes (based on the user's authentication system)
  6. (Optionally) Create a custom fetcher for the Fragment (e.g. for authentication headers)
  7. Integrate the Fragment into frontend and backend where it makes sense
  1. 安装Fragment
  2. 挂载Fragment的后端路由
  3. 初始化客户端hooks
  4. （可选）数据库集成
  5. （可选）为Fragment定义的路由设置中间件（基于用户的认证系统）
  6. （可选）为Fragment创建自定义fetcher（例如用于认证头）
  7. 在合理的位置将Fragment集成到前端和后端中

Integration Workflow

集成工作流程

1. Install the Fragment Package

1. 安装Fragment包

Install the Fragment package via the user's npm-compatible package manager.
通过用户使用的兼容npm的包管理器安装Fragment包。

2. Create a Server-Side Fragment Instance

2. 创建服务器端Fragment实例

  1. Find the most logical place, usually a central module in the application. If the user is already using Fragments, follow the same patterns.
  2. Find the Fragment's main entrypoint function, e.g. 
    import { createFormsFragment } from "@fragno-dev/forms";
  3. Pass the Fragment-specific config (API keys, callbacks, etc.)
  4. Determine if the Fragment needs a database: this is the case when the main function requires a 
    DatabaseAdapter
    parameter.
  1. 找到最合适的位置，通常是应用中的核心模块。如果用户已经在使用Fragments，请遵循相同的模式。
  2. 找到Fragment的主入口函数，例如：
    import { createFormsFragment } from "@fragno-dev/forms";
  3. 传入Fragment特定的配置（API密钥、回调函数等）
  4. 判断Fragment是否需要数据库：当主函数需要
    DatabaseAdapter
    参数时，即表示需要数据库。

3. Initialize the Database (If Required)

3. 初始化数据库（如有需要）

  1. Determine the user's database system (should be any of the following, otherwise tell the user that installation WILL NOT be possible):
    • PostgreSQL (or PGLite), MySQL, SQLite (or Cloudflare Durable Objects)
    • Kysely, Drizzle, Prisma, (or no ORM)
  2. Install 
    @fragno-dev/db
    and 
    @fragno-dev/cli
    .
  3. Create a 
    databaseAdapter
    in a central place.
    1. Import Dialect from 
      @fragno-dev/db/dialects
    2. Import DriverConfig from 
      @fragno-dev/db/drivers
  4. Determine the method of migration generation:
    • For Drizzle and Prisma, schemas can be generated for use with the ORM's own migration tool.
    • For Kysely or no ORM, SQL migrations can be generated for use with the Fragno CLI.
  5. Use the Fragno CLI to generate the schema file or migrations: (note that input can be more than one file) 
    • npx fragno-cli db generate lib/comment-fragment-server.ts --output migrations/001.sql
    • npx fragno-cli db generate lib/comment-fragment-server.ts --format drizzle --output schema/fragno-schema.ts
    • npx fragno-cli db generate lib/comment-fragment-server.ts --format prisma --output prisma/schema/fragno.prisma
  6. Integrate the schema with the ORM (e.g. by updating the Drizzle config)
  1. 确定用户的数据库系统（必须是以下之一，否则请告知用户无法完成安装）：
    • PostgreSQL（或PGLite）、MySQL、SQLite（或Cloudflare Durable Objects）
    • Kysely、Drizzle、Prisma、（或无ORM）
  2. 安装
    @fragno-dev/db
    和
    @fragno-dev/cli
    。
  3. 在核心位置创建
    databaseAdapter
    。
    1. 从
      @fragno-dev/db/dialects
      导入Dialect
    2. 从
      @fragno-dev/db/drivers
      导入DriverConfig
  4. 确定迁移生成方式：
    • 对于Drizzle和Prisma，可以生成架构文件供ORM自身的迁移工具使用。
    • 对于Kysely或无ORM，可以生成SQL迁移文件供Fragno CLI使用。
  5. 使用Fragno CLI生成架构文件或迁移文件（注意输入可以是多个文件）： 
    • npx fragno-cli db generate lib/comment-fragment-server.ts --output migrations/001.sql
    • npx fragno-cli db generate lib/comment-fragment-server.ts --format drizzle --output schema/fragno-schema.ts
    • npx fragno-cli db generate lib/comment-fragment-server.ts --format prisma --output prisma/schema/fragno.prisma
  6. 将架构与ORM集成（例如更新Drizzle配置）

4. Mount the Fragment's Backend Routes

4. 挂载Fragment的后端路由

Fragment's use web standard Request/Response objects, so they can be mounted in any framework that supports them. There is also the framework-specific 
handlersFor
function.
  1. Determine what the Fragment's mount route is. The default is usually 
    /api/${fragmentName}
    .
  2. Determine the framework-specific way to mount the backend routes in the right location (example below)
Next.js example:
ts
// This uses the Next.js file-based routing pattern.
import { createExampleFragmentInstance } from "@/lib/example-fragment-server";

const exampleFragment = createExampleFragmentInstance();
export const { GET, POST, PUT, PATCH, DELETE } = exampleFragment.handlersFor("next-js");
React Router v7 (Remix) example:
ts
import type { Route } from "./+types/example-fragment";
import { createExampleFragmentInstance } from "@/lib/example-fragment-server";

export async function loader({ request }: Route.LoaderArgs) {
  return await createExampleFragmentInstance().handler(request);
}

export async function action({ request }: Route.ActionArgs) {
  return await createExampleFragmentInstance().handler(request);
}
For Node.js (Express/Node.js) a separate package is required: 
@fragno-dev/node
.
Fragments使用Web标准的Request/Response对象，因此可以挂载到任何支持该标准的框架中。同时也提供了框架特定的
handlersFor
函数。
  1. 确定Fragment的挂载路由，默认通常是
    /api/${fragmentName}
    。
  2. 确定在对应框架中挂载后端路由的具体方式（示例如下）
Next.js示例：
ts
// This uses the Next.js file-based routing pattern.
import { createExampleFragmentInstance } from "@/lib/example-fragment-server";

const exampleFragment = createExampleFragmentInstance();
export const { GET, POST, PUT, PATCH, DELETE } = exampleFragment.handlersFor("next-js");
React Router v7（Remix）示例：
ts
import type { Route } from "./+types/example-fragment";
import { createExampleFragmentInstance } from "@/lib/example-fragment-server";

export async function loader({ request }: Route.LoaderArgs) {
  return await createExampleFragmentInstance().handler(request);
}

export async function action({ request }: Route.ActionArgs) {
  return await createExampleFragmentInstance().handler(request);
}
对于Node.js（Express/Node.js），需要单独安装包：
@fragno-dev/node
。

5. Create a Client-Side Integration

5. 创建客户端集成

  1. Create a client-side integration module in a central location.
  2. Import the client creator from the fragment's framework-specific export (e.g. 
    /react
    , 
    /vue
    , 
    /svelte
    , 
    /solid
    , 
    /vanilla
    ).
  3. If the backend routes are mounted on a non-default path, pass 
    mountRoute
    to the client creator:
    typescript
    ...
export const exampleFragment = createExampleFragmentClient({
   baseUrl: "/",
   mountRoute: "/custom/api/example-fragment",
});
  4. Use the fragment hooks/composables in UI components.
  1. 在核心位置创建客户端集成模块。
  2. 从fragment的框架特定导出中导入客户端创建器（例如
    /react
    、
    /vue
    、
    /svelte
    、
    /solid
    、
    /vanilla
    ）。
  3. 如果后端路由挂载在非默认路径，请将
    mountRoute
    传入客户端创建器：
    typescript
    ...
export const exampleFragment = createExampleFragmentClient({
   baseUrl: "/",
   mountRoute: "/custom/api/example-fragment",
});
  4. 在UI组件中使用fragment的hooks/composables。

6. Optional steps

6. 可选步骤

  1. Create Fragno Fragment-specific route middleware to implement authentication (or other features). See 
    ./references/middleware.md
    .
  2. Create a custom fetcher for the Fragment (e.g. for authentication headers). See 
    ./references/client-customization.md
    .
  3. Configure a durable hooks dispatcher for fragments that use durable hooks (background retries, scheduled hooks). See 
    ./references/dispatchers.md
    .
  1. 创建Fragno Fragment专属的路由中间件以实现认证（或其他功能）。请参阅
    ./references/middleware.md
    。
  2. 为Fragment创建自定义fetcher（例如用于认证头）。请参阅
    ./references/client-customization.md
    。
  3. 为使用durable hooks的fragments配置durable hooks调度器（后台重试、定时hooks）。请参阅
    ./references/dispatchers.md
    。

7. Present options to user

7. 为用户提供选项

  • Determine what frontend hooks are available
  • Determine what backend routes are available
  • Determine what service methods are available
Present these to the user to come up with a plan for further deep integration into their application.
  • 确定可用的前端hooks
  • 确定可用的后端路由
  • 确定可用的服务方法
将这些信息呈现给用户，以制定进一步深度集成到其应用中的方案。

First-party Fragments (FP)

官方Fragments（FP）

Use these fragments when you need their domain-specific features. Always 
curl
the fragment docs before wiring anything.
当需要特定领域的功能时使用这些fragments。在接入任何内容之前，请务必使用
curl
获取fragment文档。

Auth (
@fragno-dev/auth
)

Auth (
@fragno-dev/auth
)

Definition: Minimal email/password auth with session cookies and DB-backed users/sessions.
Use when: you need a simple, self-hosted auth flow (sign-up/sign-in/sign-out, session, roles) and can store credentials in your database.
Reference: 
./references/first-party-fragments/auth.md
.
Docs lookup: 
curl -s "https://fragno.dev/api/search?query=auth%20fragment"
.
定义：基于会话Cookie和数据库存储用户/会话的极简邮箱/密码认证方案。
适用场景：当你需要一个简单的自托管认证流程（注册/登录/登出、会话、角色），且可以在自己的数据库中存储凭证时。
参考：
./references/first-party-fragments/auth.md
。
文档查询：
curl -s "https://fragno.dev/api/search?query=auth%20fragment"
。

Forms (
@fragno-dev/forms
)

Forms (
@fragno-dev/forms
)

Definition: JSON Schema and JSON Forms-based form builder plus response collection stored in your database.
Use when: you need schema-driven forms, admin-managed form lifecycle, and stored submissions.
Reference: 
./references/first-party-fragments/forms.md
.
Docs: 
curl -L "https://fragno.dev/docs/forms/quickstart" -H "accept: text/markdown"
.
定义：基于JSON Schema和JSON Forms的表单构建器，以及存储在数据库中的响应收集功能。
适用场景：当你需要基于 schema 的表单、管理员可管理的表单生命周期，以及存储提交数据时。
参考：
./references/first-party-fragments/forms.md
。
文档：
curl -L "https://fragno.dev/docs/forms/quickstart" -H "accept: text/markdown"
。

Stripe (
@fragno-dev/stripe
)

Stripe (
@fragno-dev/stripe
)

Definition: Stripe subscription management with webhook-backed local state and client mutators.
Use when: your app sells subscriptions and you want built-in checkout, upgrade, cancel, and admin hooks.
Reference: 
./references/first-party-fragments/stripe.md
.
Docs: 
curl -L "https://fragno.dev/docs/stripe/quickstart" -H "accept: text/markdown"
.
定义：基于Webhook的本地状态和客户端修改器实现的Stripe订阅管理。
适用场景：当你的应用销售订阅服务，且需要内置的结账、升级、取消和管理员hooks时。
参考：
./references/first-party-fragments/stripe.md
。
文档：
curl -L "https://fragno.dev/docs/stripe/quickstart" -H "accept: text/markdown"
。

Workflows (
@fragno-dev/workflows
)

Workflows (
@fragno-dev/workflows
)

Definition: Durable, long-running workflows with steps, timers, retries, and event waits backed by your database.
Use when: you need reliable multi-step processes and an HTTP API/CLI to manage instances.
Reference: 
./references/first-party-fragments/workflows.md
.
Docs: 
curl -L "https://fragno.dev/docs/workflows/quickstart" -H "accept: text/markdown"
.
定义：基于数据库的持久化、长运行工作流，包含步骤、定时器、重试和事件等待功能。
适用场景：当你需要可靠的多步骤流程，以及用于管理实例的HTTP API/CLI时。
参考：
./references/first-party-fragments/workflows.md
。
文档：
curl -L "https://fragno.dev/docs/workflows/quickstart" -H "accept: text/markdown"
。

Upload (
@fragno-dev/upload
)

Upload (
@fragno-dev/upload
)

Definition: Full-stack uploads with a normalized file model, S3/R2 or filesystem storage adapters, and client helpers for direct or server-streamed uploads.
Use when: you need file uploads with progress tracking and storage-backed file metadata.
Reference: 
./references/first-party-fragments/upload.md
.
Docs: 
curl -L "https://fragno.dev/docs/upload/quickstart" -H "accept: text/markdown"
.
定义：全栈上传功能，包含标准化文件模型、S3/R2或文件系统存储适配器，以及用于直接上传或服务器流式上传的客户端助手。
适用场景：当你需要带有进度跟踪和存储后端文件元数据的文件上传功能时。
参考：
./references/first-party-fragments/upload.md
。
文档：
curl -L "https://fragno.dev/docs/upload/quickstart" -H "accept: text/markdown"
。

Docs lookup

文档查询

The Fragno documentation is available online:
  • Search the docs: 
    • curl -s "https://fragno.dev/api/search?query=databaseAdapter"
  • Fetch Framework docs as Markdown: 
    • curl -L "https://fragno.dev/docs/fragno/user-quick-start" -H "accept: text/markdown"
  • Fetch a specific first-party Fragment's docs: 
    • curl -L "https://fragno.dev/docs/forms/static-forms" -H "accept: text/markdown"
Fragno文档可在线获取：
  • 搜索文档： 
    • curl -s "https://fragno.dev/api/search?query=databaseAdapter"
  • 获取Markdown格式的框架文档： 
    • curl -L "https://fragno.dev/docs/fragno/user-quick-start" -H "accept: text/markdown"
  • 获取特定官方Fragment的文档： 
    • curl -L "https://fragno.dev/docs/forms/static-forms" -H "accept: text/markdown"

References

参考资料

The following reference files are available in 
./references/
: Note: all reference paths are relative to this skill file.
FileDescription
server-integration.md
Server-side integration: Framework-specific mounting patterns for server-side API routes
client-integration.md
Creating client-side integration modules and using Fragment hooks/composables in UI components
client-customization.md
Customizing HTTP requests made by Fragno Fragments (authentication, CORS, interceptors)
middleware.md
Intercepting and processing requests before they reach route handlers
services.md
Running functions defined by Fragments on the server, including calling route handlers directly
dispatchers.md
Durable hooks dispatchers: background processing, retries, and platform-specific setups
first-party-fragments/auth.md
Auth fragment one-pager (install, routes, client, migrations)
first-party-fragments/forms.md
Forms fragment one-pager (schemas, hooks, admin routes, migrations)
first-party-fragments/stripe.md
Stripe fragment one-pager (subscriptions, webhooks, admin hooks)
first-party-fragments/workflows.md
Workflows fragment one-pager (runner/dispatcher, routes, CLI)
first-party-fragments/upload.md
Upload fragment one-pager (storage adapters, helpers, routes)
以下参考文件位于
./references/
：注意：所有参考路径均相对于本指南文件。
文件描述
server-integration.md
服务器端集成：针对服务器端API路由的框架特定挂载模式
client-integration.md
创建客户端集成模块并在UI组件中使用Fragment的hooks/composables
client-customization.md
自定义Fragno Fragments发起的HTTP请求（认证、CORS、拦截器）
middleware.md
在请求到达路由处理器之前拦截并处理请求
services.md
在服务器端运行Fragments定义的函数，包括直接调用路由处理器
dispatchers.md
Durable hooks调度器：后台处理、重试和平台特定设置
first-party-fragments/auth.md
Auth fragment单页指南（安装、路由、客户端、迁移）
first-party-fragments/forms.md
Forms fragment单页指南（架构、hooks、管理员路由、迁移）
first-party-fragments/stripe.md
Stripe fragment单页指南（订阅、Webhook、管理员hooks）
first-party-fragments/workflows.md
Workflows fragment单页指南（运行器/调度器、路由、CLI）
first-party-fragments/upload.md
Upload fragment单页指南（存储适配器、助手、路由）