@fragno-dev/create 0.0.2

package/templates/fragment/AGENTS.md

@@ -0,0 +1,220 @@
+# AGENTS.md
+
+This file provides guidance for AI agents working with Fragno fragments. It contains architectural
+information, development strategies, and practical approaches for building fragments.
+
+## Overview
+
+A **Fragment** is a full-stack, framework-agnostic TypeScript library built with Fragno. Fragments
+provide:
+
+- Type-safe server-side API routes
+- Automatic client-side hooks/composables for multiple frameworks (React, Vue, Svelte, Vanilla JS)
+- Automatic code splitting between client and server bundles
+- Built-in state management with reactive stores (TanStack Query-style:
+  `const {data, loading, error} = useData()`)
+
+**Documentation**: Full documentation is available at https://fragno.dev/docs
+
+## Architecture
+
+Fragments follow a core pattern:
+
+1. **Server-side**: Define routes with input/output schemas, handlers, and dependencies
+2. **Client-side**: Auto-generated type-safe hooks for each route
+3. **Code splitting**: Server-only code (handlers, dependencies) is stripped from client bundles
+
+## File Structure & Core Concepts
+
+### `src/index.ts` - Main Fragment Definition
+
+This is the core file that contains the fragment definition, routes, dependencies, services, and
+client builder.
+
+**Key concepts defined in this file**:
+
+**Fragment Definition** (`defineFragment`):
+
+- Takes a config type parameter that defines what users must provide (API keys, callbacks, etc.)
+- The fragment name is used in the URL path: `/api/<fragment-name>/...`
+
+**Dependencies** (`.withDependencies()`):
+
+- Server-side only (never included in client bundle)
+- Private to the fragment, not accessible to users
+- Access to config for initialization (e.g., API keys, database connections)
+- Used in route handlers
+
+**Services** (`.withServices()`):
+
+- Server-side only (never included in client bundle)
+- Public-facing API accessible to users via `fragment.services.methodName()`
+- Access to both config and dependencies
+- Useful for exposing utility methods to users
+
+**Route Definition** (`defineRoute` and `defineRoutes`):
+
+- `defineRoute`: Simple routes without dependencies
+- `defineRoutes`: Route factory that has access to dependencies and services
+- Route handler context:
+  - First parameter (input): `{ input, query, pathParams, request, url }`
+  - Second parameter (output): `{ json, jsonStream, empty, error }`
+  - `input.valid()` validates and returns parsed data (throws on validation error)
+
+**Server-Side Fragment** (`createFragment`):
+
+- Users call this function to instantiate the fragment on the server
+- Returns an object with request handlers (`handler(request: Request) => Response`) and `services`
+
+**Client-Side Builder** (`createClientBuilder`):
+
+- Creates type-safe hooks for each route
+- `createHook(path)`: For GET routes (returns `{ data, loading, error }`)
+- `createMutator(method, path)`: For POST/PUT/PATCH/DELETE routes (returns
+  `{ data, loading, error, mutate }`)
+- Advanced: Use `computed`, `atom` from `nanostores` for derived state
+
+### `src/client/*.ts` - Framework-Specific Exports
+
+Each framework requires a separate client file that wraps the generic client builder with the
+framework-specific `useFragno` hook. Check the `src/client/` directory for existing framework
+implementations. Use the frameworks page on https://fragno.dev/docs/frameworks to see if all clients
+have their stubs defined. Make sure to include new frameworks in the exports section of
+package.json.
+
+### `package.json` - Package Configuration
+
+The package.json defines multiple export paths for different frameworks and environments. Key
+points:
+
+- Main export (`.`) is server-side code
+- Framework exports (`./react`, `./vue`, `./svelte`, `./vanilla`) use "browser" condition to load
+  client bundle
+- Development mode uses source files for better debugging
+- Production uses built files from `dist/`
+- When adding new framework exports, add corresponding client files in `src/client/`
+
+## Strategies for Building Fragments
+
+### OpenAPI/Swagger Spec → Fragno Routes
+
+Parse an OpenAPI specification and convert it to Fragno routes. Map HTTP methods to `defineRoute`,
+convert path parameters (e.g., `/users/{id}` → `/users/:id`), convert JSON schemas to Zod schemas
+for `inputSchema`/`outputSchema`, and generate handlers. Group related routes using `defineRoutes`
+if they share dependencies. Extract error codes from OpenAPI error responses.
+
+### REST API Wrapper
+
+Wrap an existing REST API with proper typing and error handling. Add HTTP client (fetch, axios) to
+dependencies with API credentials from config. Create routes that proxy to API endpoints with proper
+error handling and validation. Optionally add caching or rate limiting in services. This approach is
+useful when you want to provide a type-safe interface to an existing API.
+
+### Third-Party SDK Integration
+
+Wrap third-party SDKs (Stripe, OpenAI, Twilio, etc.) as fragments. Add SDK to dependencies with API
+keys from config. Create routes that expose SDK functionality, transform SDK responses to match your
+schemas, and handle SDK-specific errors and rate limits. Optionally expose the SDK client directly
+in services for advanced users. Use streaming responses for real-time SDK features like AI chat.
+
+## Development Workflow
+
+### Building
+
+Fragments require code splitting between client and server bundles using
+`@fragno-dev/unplugin-fragno`. The plugin can also be imported for different kinds of build tools:
+`/esbuild`, `/rollup`, `/webpack`, `/rspack`, `/farm`.
+
+### Type Checking
+
+```bash
+bun run types:check
+```
+
+## Common Patterns
+
+### Streaming Responses
+
+For real-time data (e.g., AI chat, large datasets), use `jsonStream` with `stream.write()` and
+`stream.sleep()`. The output schema must be an array. Client-side: The `data` array is updated
+reactively as chunks arrive.
+
+### Error Handling
+
+- Always define `errorCodes` array in route definition
+- Use structured errors: `error({ message: string, code: string }, statusCode)`
+- `input.valid()` automatically throws validation errors (converted to 400 responses)
+- Check for null/undefined before processing and return appropriate error codes
+
+### Create Callbacks
+
+Allow users to react to events by including optional callback functions in your config:
+
+```typescript
+interface FragmentConfig {
+  onDataCreated?: (data: Data) => void;
+  onError?: (error: Error) => void;
+}
+```
+
+Call them in handlers after operations complete: `config.onDataCreated?.(data);`
+
+## Using Your Fragment in Other Projects
+
+Once you've built and published your fragment, users can integrate it into their projects. The
+integration has two parts:
+
+### 1. Server-Side Setup
+
+Create a server instance of your fragment (e.g., in `lib/fragment-server.ts`):
+
+```typescript
+import { createFragment } from "your-fragment-name";
+
+export const createFragmentInstance = () =>
+  createFragment({
+    // Fragment-specific configuration here
+    apiKey: process.env.API_KEY,
+  });
+```
+
+Then mount it as a route handler. For example, in Next.js:
+
+```typescript
+// app/api/your-fragment/[...all]/route.ts
+import { createFragmentInstance } from "@/lib/fragment-server";
+
+const fragment = createFragmentInstance();
+export const { GET, POST, PUT, PATCH, DELETE } = fragment.handlersFor("next-js");
+```
+
+### 2. Client-Side Setup
+
+Initialize the client in your app (e.g., React):
+
+```typescript
+// lib/fragment-client.ts
+import { createFragmentClient } from "your-fragment-name/react";
+
+export const { useData, useMutateData } = createFragmentClient({
+  // Optional Fragno configuration
+  baseUrl: "/",
+  mountRoute: "/api/your-fragment",
+});
+```
+
+Then use the generated hooks in your components:
+
+```tsx
+import { useData } from "@/lib/fragment-client";
+
+function MyComponent() {
+  const { data, loading, error } = useData({
+    /* input */
+  });
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  return <div>{JSON.stringify(data)}</div>;
+}
+```

package/templates/fragment/README.md

@@ -0,0 +1,16 @@
+# Fragno Fragment
+
+You've created a new [Fragno](https://fragno.dev/) fragment!
+
+## Build
+
+```bash
+npm run types:check
+npm run build
+```
+
+## Next Steps
+
+- Define your routes in `src/index.ts`
+- Add framework-specific clients in `src/client/`
+- See `AGENTS.md` for detailed development patterns

package/templates/fragment/package.template.json

@@ -0,0 +1,65 @@
+{
+  "description": "A Fragno fragment",
+  "version": "0.0.1",
+  "files": ["dist"],
+  "keywords": ["fragno", "typescript", "react", "vue", "svelte"],
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    },
+    "./react": {
+      "development": {
+        "browser": "./dist/browser/client/react.js",
+        "default": "./src/client/react.ts"
+      },
+      "types": "./dist/browser/client/react.d.ts",
+      "default": "./dist/browser/client/react.js"
+    },
+    "./vue": {
+      "development": {
+        "browser": "./dist/browser/client/vue.js",
+        "default": "./src/client/vue.ts"
+      },
+      "types": "./dist/browser/client/vue.d.ts",
+      "default": "./dist/browser/client/vue.js"
+    },
+    "./svelte": {
+      "development": {
+        "browser": "./dist/browser/client/svelte.js",
+        "default": "./src/client/svelte.ts"
+      },
+      "types": "./dist/browser/client/svelte.d.ts",
+      "default": "./dist/browser/client/svelte.js"
+    },
+    "./vanilla": {
+      "development": {
+        "browser": "./dist/browser/client/vanilla.js",
+        "default": "./src/client/vanilla.ts"
+      },
+      "types": "./dist/browser/client/vanilla.d.ts",
+      "default": "./dist/browser/client/vanilla.js"
+    }
+  },
+  "main": "./dist/node/index.js",
+  "module": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
+  "scripts": {
+    "types:check": "tsc --noEmit"
+  },
+  "type": "module",
+  "dependencies": {
+    "@fragno-dev/core": "^0.0.6",
+    "zod": "^4.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20"
+  },
+  "private": true,
+  "peerDependencies": {
+    "typescript": "^5",
+    "react": ">=18.0.0",
+    "svelte": ">=4.0.0",
+    "vue": ">=3.0.0"
+  }
+}

package/templates/fragment/src/client/react.ts

@@ -0,0 +1,7 @@
+import { useFragno } from "@fragno-dev/core/react";
+import { createExampleFragmentClients } from "..";
+import type { FragnoPublicClientConfig } from "@fragno-dev/core";
+
+export function createExampleFragmentClient(config: FragnoPublicClientConfig = {}) {
+  return useFragno(createExampleFragmentClients(config));
+}

package/templates/fragment/src/client/svelte.ts

@@ -0,0 +1,7 @@
+import { useFragno } from "@fragno-dev/core/svelte";
+import { createExampleFragmentClients } from "..";
+import type { FragnoPublicClientConfig } from "@fragno-dev/core";
+
+export function createExampleFragmentClient(config: FragnoPublicClientConfig = {}) {
+  return useFragno(createExampleFragmentClients(config));
+}

package/templates/fragment/src/client/vanilla.ts

@@ -0,0 +1,7 @@
+import { useFragno } from "@fragno-dev/core/vanilla";
+import { createExampleFragmentClients } from "..";
+import type { FragnoPublicClientConfig } from "@fragno-dev/core";
+
+export function createExampleFragmentClient(config: FragnoPublicClientConfig = {}) {
+  return useFragno(createExampleFragmentClients(config));
+}

package/templates/fragment/src/client/vue.ts

@@ -0,0 +1,7 @@
+import { useFragno } from "@fragno-dev/core/vue";
+import { createExampleFragmentClients } from "..";
+import type { FragnoPublicClientConfig } from "@fragno-dev/core";
+
+export function createExampleFragmentClient(config: FragnoPublicClientConfig = {}) {
+  return useFragno(createExampleFragmentClients(config));
+}

package/templates/fragment/src/index.ts

@@ -0,0 +1,94 @@
+import {
+  defineFragment,
+  defineRoute,
+  defineRoutes,
+  createFragment,
+  type FragnoPublicClientConfig,
+  type FragnoPublicConfig,
+} from "@fragno-dev/core";
+import { createClientBuilder } from "@fragno-dev/core/client";
+
+// NOTE: We use zod here for defining schemas, but any StandardSchema library can be used!
+//       For a complete list see:
+// https://github.com/standard-schema/standard-schema#what-schema-libraries-implement-the-spec
+import { z } from "zod";
+
+export interface ExampleFragmentServerConfig {
+  initialData?: string;
+}
+
+type ExampleRouteConfig = {
+  initialData: string;
+};
+
+type ExampleRouteDeps = {
+  serverSideData: { value: string };
+};
+
+const exampleRoutesFactory = defineRoutes<ExampleRouteConfig, ExampleRouteDeps>().create(
+  ({ deps }) => {
+    const { serverSideData } = deps;
+
+    return [
+      defineRoute({
+        method: "GET",
+        path: "/hello",
+        outputSchema: z.string(),
+        handler: async (_, { json }) => {
+          return json(serverSideData.value);
+        },
+      }),
+
+      defineRoute({
+        method: "POST",
+        path: "/hello",
+        inputSchema: z.object({ message: z.string() }),
+        outputSchema: z.string(),
+        errorCodes: [],
+        handler: async ({ input }, { json }) => {
+          const { message } = await input.valid();
+          serverSideData.value = message;
+          return json(message);
+        },
+      }),
+    ];
+  },
+);
+
+const exampleFragmentDefinition = defineFragment<ExampleFragmentServerConfig>("example-fragment")
+  .withDependencies((config: ExampleFragmentServerConfig) => {
+    return {
+      serverSideData: { value: config.initialData ?? "Hello World! This is a server-side data." },
+    };
+  })
+  .withServices((_cfg, deps) => {
+    return {
+      getData: () => deps.serverSideData.value,
+    };
+  });
+
+export function createExampleFragment(
+  serverConfig: ExampleFragmentServerConfig = {},
+  fragnoConfig: FragnoPublicConfig = {},
+) {
+  const config: ExampleRouteConfig = {
+    initialData: serverConfig.initialData ?? "Hello World! This is a server-side data.",
+  };
+
+  return createFragment(
+    exampleFragmentDefinition,
+    { ...serverConfig, ...config },
+    [exampleRoutesFactory],
+    fragnoConfig,
+  );
+}
+
+export function createExampleFragmentClients(fragnoConfig: FragnoPublicClientConfig) {
+  const b = createClientBuilder(exampleFragmentDefinition, fragnoConfig, [exampleRoutesFactory]);
+
+  return {
+    useHello: b.createHook("/hello"),
+    useHelloMutator: b.createMutator("POST", "/hello"),
+  };
+}
+export type { FragnoRouteConfig } from "@fragno-dev/core/api";

package/templates/fragment/tsconfig.base.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": false,
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    // Project reference specific settings
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rewriteRelativeImportExtensions": true,
+    "emitDeclarationOnly": false,
+    "isolatedDeclarations": false,
+    "isolatedModules": true,
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    // Some stricter flags
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true,
+    // Misc
+    "esModuleInterop": true,
+    "noErrorTruncation": true
+  }
+}

package/templates/fragment/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "composite": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/optional/builder/esbuild.config.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { build } from "esbuild";
+import unpluginFragno from "@fragno-dev/unplugin-fragno/esbuild";
+
+build({
+  entryPoints: [
+    "./src/index.ts",
+    "./src/client/react.ts",
+    "./src/client/svelte.ts",
+    "./src/client/vanilla.ts",
+    "./src/client/vue.ts",
+  ],
+  outdir: "./dist/browser",
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2020",
+  splitting: true,
+  sourcemap: true,
+  plugins: [unpluginFragno({ platform: "browser" })],
+  external: ["react", "svelte", "vue", "zod"],
+});
+
+build({
+  entryPoints: ["./src/index.ts"],
+  outdir: "./dist/node",
+  bundle: true,
+  format: "esm",
+  platform: "node",
+  target: "node18",
+  sourcemap: true,
+  plugins: [unpluginFragno({ platform: "node" })],
+  external: ["zod"],
+});

package/templates/optional/builder/rollup.config.js

@@ -0,0 +1,58 @@
+import typescript from "@rollup/plugin-typescript";
+import unpluginFragno from "@fragno-dev/unplugin-fragno/rollup";
+import resolve from "@rollup/plugin-node-resolve";
+
+export default [
+  // Browser build
+  {
+    input: {
+      index: "./src/index.ts",
+      "client/react": "./src/client/react.ts",
+      "client/svelte": "./src/client/svelte.ts",
+      "client/vanilla": "./src/client/vanilla.ts",
+      "client/vue": "./src/client/vue.ts",
+    },
+    output: {
+      dir: "./dist/browser",
+      format: "es",
+      sourcemap: true,
+    },
+    // https://rollupjs.org/tools/#peer-dependencies
+    external: ["zod", "react", "svelte", "vue"],
+    plugins: [
+      resolve({
+        moduleDirectories: ["node_modules"],
+        browser: true,
+      }),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: true,
+        outDir: "./dist/browser",
+        declarationDir: "./dist/browser",
+      }),
+      unpluginFragno({ platform: "browser" }),
+    ],
+  },
+  // Node build
+  {
+    input: "./src/index.ts",
+    output: {
+      dir: "./dist/node",
+      format: "es",
+      sourcemap: true,
+    },
+    external: ["zod"],
+    plugins: [
+      resolve({
+        moduleDirectories: ["node_modules"],
+      }),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: true,
+        outDir: "./dist/node",
+        declarationDir: "./dist/node",
+      }),
+      unpluginFragno({ platform: "node" }),
+    ],
+  },
+];

package/templates/optional/builder/rspack.config.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import unpluginFragno from "@fragno-dev/unplugin-fragno/rspack";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** @type {import('@rspack/core').Configuration[]} */
+export default [
+  // Browser build
+  {
+    name: "browser",
+    mode: "production",
+    entry: {
+      index: "./src/index.ts",
+      "client/react": "./src/client/react.ts",
+      "client/svelte": "./src/client/svelte.ts",
+      "client/vanilla": "./src/client/vanilla.ts",
+      "client/vue": "./src/client/vue.ts",
+    },
+    output: {
+      path: path.resolve(__dirname, "dist/browser"),
+      filename: "[name].js",
+      library: {
+        type: "module",
+      },
+    },
+    experiments: {
+      outputModule: true,
+    },
+    resolve: {
+      extensions: [".ts", ".js"],
+    },
+    module: {
+      rules: [
+        {
+          test: /\.ts$/,
+          use: "builtin:swc-loader",
+          exclude: /node_modules/,
+          options: {
+            jsc: {
+              parser: {
+                syntax: "typescript",
+              },
+            },
+          },
+        },
+      ],
+    },
+    plugins: [unpluginFragno({ platform: "browser" })],
+    devtool: "source-map",
+    externals: ["zod", "react", "vue", "svelte"],
+  },
+  // Node build
+  {
+    name: "node",
+    mode: "production",
+    entry: {
+      index: "./src/index.ts",
+    },
+    output: {
+      path: path.resolve(__dirname, "dist/node"),
+      filename: "[name].js",
+      library: {
+        type: "module",
+      },
+    },
+    experiments: {
+      outputModule: true,
+    },
+    resolve: {
+      extensions: [".ts", ".js"],
+    },
+    module: {
+      rules: [
+        {
+          test: /\.ts$/,
+          use: "builtin:swc-loader",
+          exclude: /node_modules/,
+          options: {
+            jsc: {
+              parser: {
+                syntax: "typescript",
+              },
+            },
+          },
+        },
+      ],
+    },
+    plugins: [unpluginFragno({ platform: "node" })],
+    devtool: "source-map",
+    externals: ["zod"],
+  },
+];