User Quick Start

Installation

Install the fragment you want to use:

npm i @fragno-dev/example-fragment

Create a server-side instance of the Fragment

Create a server-side instance of the Fragment in a central location in your codebase:

This is where the Fragment is configured by passing Fragment-specific config fields such as API keys and callback methods.

import { createExampleFragment } from "@fragno-dev/example-fragment";

export function createExampleFragmentInstance() {
  return createExampleFragment({
    // Pass any Fragment-specific config fields
    someApiKey: process.env.EXAMPLE_API_KEY!,
  });
}

Setup Database (if required)

If the Fragment requires database integration:

1. Install the database package and the CLI:

   npm

   pnpm

   yarn

   bun

   npm install @fragno-dev/db @fragno-dev/cli

2. Create a database adapter:

   import { KyselyAdapter } from "@fragno-dev/db/adapters/kysely";
   import { db } from "./database"; // Your existing Kysely/Drizzle instance
   
   export const fragmentDbAdapter = new KyselyAdapter({
     db,
     provider: "postgresql", // or "mysql", "sqlite"
   });

3. Pass the adapter when creating the Fragment:

   import { createExampleFragment } from "@fragno-dev/example-fragment";
   import { fragmentDbAdapter } from "./database-adapter";
   
   export function createExampleFragmentInstance() {
     return createExampleFragment(
       {
         someApiKey: process.env.EXAMPLE_API_KEY!,
       },
       {
         databaseAdapter: fragmentDbAdapter,
       },
     );
   }

4. Run migrations:

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

For complete instructions, see Database Fragments.

Mount the API routes

The API routes defined in the Fragment should be accessible from your frontend. We do this by creating a "catch-all" API route that will (in this case) forward all requests starting with /api/example-fragment to the Fragment.

Since most frameworks use file-based routing, the location of this file is important.

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

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

Create a client-side integration

Create the client-side integration in a central location:

import { createExampleFragmentClient } from "@fragno-dev/example-fragment/react";

export const exampleFragment = createExampleFragmentClient();

Client-side usage

You can now use the Fragment in any of your components:

import { exampleFragment } from "@/lib/example-fragment-client";

export default function ExampleComponent() {
  const { data, loading } = exampleFragment.useData();

  return (
    <div>
      <h1>Example Component</h1>
      {loading ? <div>Loading...</div> : <div>{data}</div>}
    </div>
  );
}