Integrating a Fragment

Integrating a Fragment into your project is a straightforward process. There are two main integration points for a Fragment: server-side and client-side. This page contains framework-specific integration details.

A complete guide to integrating a Fragment is available on the previous page:

Fragno Configuration

Every Fragno Fragment can be configured with several built-in options:

These options can be configured at the frontend integration point, and are relevant when mounting the backend route in a non-standard location.

Fragment-specific Configuration

Most Fragments will also require some configuration specific to them. Check the documentation for the specific Fragment you are integrating to figure out what configuration is required.

Fragments with Databases

Some Fragments include a database layer for persistent storage. These Fragments require you to provide a database adapter that connects the Fragment to your existing database.

Fragno’s DB adapters use Kysely’s Dialect interface as the query execution layer. This lets us reuse Kysely’s dialect ecosystem (and keep adapter code small). When creating an adapter you must provide:

• dialect: from @fragno-dev/db/dialects (or a Kysely/community dialect)
• driverConfig: from @fragno-dev/db/drivers (must match the database + driver you use)

Quick Setup

1. Install the database package:

   npm install @fragno-dev/db

2. Create an adapter (dialect + driver config):

   import { DrizzleAdapter } from "@fragno-dev/db/adapters/drizzle";
   import { PostgresDialect } from "@fragno-dev/db/dialects";
   import { NodePostgresDriverConfig } from "@fragno-dev/db/drivers";
   import { Pool } from "pg";
   
   const dialect = new PostgresDialect({
     pool: new Pool({ connectionString: process.env.DATABASE_URL }),
   });
   
   export const adapter = new DrizzleAdapter({
     dialect,
     driverConfig: new NodePostgresDriverConfig(),
   });

3. Pass adapter when creating Fragment:

   const fragment = createCommentFragment({}, { databaseAdapter: adapter });

4. Run migrations:

   npx fragno-cli db generate lib/fragment-instance.ts
   npx fragno-cli db migrate lib/fragment-instance.ts

For complete database integration instructions, see Database Fragments.

Reference

Database Adapters

Available built-in dialects:

• SQL: SqliteDialect, PostgresDialect, MysqlDialect (from @fragno-dev/db/dialects)
• Cloudflare Durable Objects (SQLite): DurableObjectDialect (from @fragno-dev/db/dialects/durable-object)

Available driver configs (@fragno-dev/db/drivers):

• SQLite: BetterSQLite3DriverConfig, SQLocalDriverConfig, CloudflareDurableObjectsDriverConfig
• PostgreSQL: NodePostgresDriverConfig, PGLiteDriverConfig
• MySQL/MariaDB: MySQL2DriverConfig

Full-stack Frameworks

import { createExampleFragmentInstance } from "@/lib/example-fragment-server";

const exampleFragment = createExampleFragmentInstance();
export const { GET, POST, PUT, PATCH, DELETE } = exampleFragment.handlersFor("next-js");

Note: in Remix, the file location might be different, as well as the Route type import.

Server-side Frameworks

import { Hono } from "hono";
import { createExampleFragmentInstance } from "@/lib/example-fragment-server";

const app = new Hono();
app.all("/api/example-fragment/*", (c) => createExampleFragmentInstance().handler(c.req.raw));

For Node/Express, install @fragno-dev/node to use toNodeHandler.

import express from "express";
import { createExampleFragmentInstance } from "@/lib/example-fragment-server";
import { toNodeHandler } from "@fragno-dev/node";

const app = express();
app.all("/api/example-fragment/*", toNodeHandler(createExampleFragmentInstance().handler));

// WARNING! If you're using the Express json middleware, make sure that it's mounted AFTER the
// Fragment handler.
app.use(express.json());

app.listen(3000);