@flocon-ai/react 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# @flocon-ai/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Show your [Flocon AI](https://flocon-ai.com) pages in a **server-rendered** React website.
+You create the pages from your AI tool (Claude, Cursor…). This lib renders them.
+
+> ⚠️ **Browser-only React apps are not supported** (Vite SPA, Create React App).
+> Most AI bots do not run JavaScript. They would see an empty page.
+> Use a framework that renders on the server: React Router v7 (framework mode), TanStack Start…
+> On Next.js, use [`@flocon-ai/next`](https://www.npmjs.com/package/@flocon-ai/next).
+
+- Needs React 18+.
+- Call the client **on the server only** (route loader, server function). The token must never reach the browser.
+- Pages are read on each request, so a new page shows up on the next visit. Drafts are never returned.
+
+## Install
+
+```bash
+npm i @flocon-ai/react
+```
+
+## Token
+
+Copy your **website token** from [flocon-ai.com/app/tokens](https://flocon-ai.com/app/tokens).
+
+```bash
+# .env
+FLOCON_TOKEN=your_read_token
+```
+
+Never commit it. Never send it to the browser.
+
+Token not in `FLOCON_TOKEN`? Every helper that calls the API takes an optional `token`:
+
+```ts
+await getPage({ path, token: myToken })
+await floconSitemap({ url, token: myToken })
+```
+
+## Page route (React Router v7, framework mode)
+
+```tsx
+// app/routes/flocon.tsx  (route: "*")
+import { FloconPage, getFloconMetadata, getPage } from "@flocon-ai/react"
+import type { Route } from "./+types/flocon"
+
+// Your URL rule. One locale: keep as is.
+// Several locales: put the locale in the URL (e.g. `https://example.com/${locale}${path}`),
+// or every hreflang link points to the same URL.
+const url = ({ locale, path }: { locale: string; path: string }) => `https://example.com${path}`
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const page = await getPage({ path: "/" + params["*"] })
+  if (!page) throw new Response("Not found", { status: 404 })
+  return page
+}
+
+export function meta({ data }: Route.MetaArgs) {
+  // No data on a 404.
+  if (!data) return [{ title: "Not found" }]
+  const m = getFloconMetadata({ page: data, url })
+  return [
+    { title: m.title },
+    { name: "description", content: m.description },
+    // Free plan only: `m.generator` is "Flocon AI".
+    ...(m.generator ? [{ name: "generator", content: m.generator }] : []),
+    { property: "og:type", content: m.openGraph.type },
+    { property: "og:title", content: m.openGraph.title },
+    { property: "og:description", content: m.openGraph.description },
+    { property: "og:url", content: m.openGraph.url },
+    { property: "og:locale", content: m.openGraph.locale },
+    { name: "twitter:card", content: m.twitter.card },
+    { name: "twitter:title", content: m.twitter.title },
+    { name: "twitter:description", content: m.twitter.description },
+    // Canonical + hreflang go here: `links()` gets no loader data.
+    { tagName: "link", rel: "canonical", href: m.canonical },
+    ...Object.entries(m.languages).map(([hrefLang, href]) => ({ tagName: "link", rel: "alternate", hrefLang, href }))
+  ]
+}
+
+export default function Page({ loaderData }: Route.ComponentProps) {
+  return <FloconPage page={loaderData} url={url} />
+}
+```
+
+- `getPage({ path, locale? })` returns the page, or `null` when it does not exist (return a 404).
+- `locale` is optional. No `locale` = the default locale of your website.
+- `<FloconPage page={page} />` does no fetching. It renders the blocks, the JSON-LD script and (Free plan) the "❄ Made with Flocon AI · flocon-ai.com" badge (link to flocon-ai.com).
+- `url({ locale, path })` is **your** URL rule. The lib adds no prefix of its own.
+- `getFloconMetadata({ page, url })` returns plain data: `title`, `description`, `keywords`, `canonical`, `languages` (hreflang, with `x-default`), `openGraph`, `twitter`. Put it in the `<head>` the way your framework does. It sets no OG image. On the Free plan, it also returns `generator: "Flocon AI"` (for `<meta name="generator">`).
+
+## Sitemap and llms.txt
+
+```ts
+// app/routes/sitemap[.]xml.ts
+import { floconSitemap } from "@flocon-ai/react"
+
+export async function loader() {
+  const xml = await floconSitemap({ url: ({ locale, path }) => `https://example.com${path}` })
+  return new Response(xml, { headers: { "content-type": "application/xml; charset=utf-8" } })
+}
+```
+
+```ts
+// app/routes/llms[.]txt.ts
+import { floconLlmsTxt } from "@flocon-ai/react"
+
+export async function loader() {
+  const text = await floconLlmsTxt({ url: ({ locale, path }) => `https://example.com${path}` })
+  return new Response(text, { headers: { "content-type": "text/plain; charset=utf-8" } })
+}
+```
+
+Both list **published** pages only. `floconSitemap` returns XML with hreflang links.
+On the Free plan, `llms.txt` ends with a "Made with [Flocon AI](https://flocon-ai.com)" line.
+`getAllPages()` gives you the same list if you need it.
+
+## Theming
+
+The CSS is added by `<FloconPage />`. Nothing to import.
+
+- **Your website uses shadcn?** The page uses your colors, radius, font and dark mode. Nothing to do.
+- **No shadcn?** The page uses the Flocon colors. It turns dark only if your website has a dark mode: `color-scheme: dark` (or `light dark` with a dark browser) on your page, or a `.dark` class (Tailwind).
+- Old shadcn (Tailwind v3, colors like `222 47% 11%`) is not supported yet: set the `--flocon-*` variables yourself.
+- Override any `--flocon-*` variable on `.flocon-page`: `--flocon-primary`, `--flocon-background`, `--flocon-foreground`, `--flocon-card`, `--flocon-muted`, `--flocon-muted-foreground`, `--flocon-border`, `--flocon-radius`, `--flocon-font`.
+- All the CSS is in `@layer flocon`: your unlayered CSS on the class names wins.
+
+## Exports
+
+| Export | What |
+| --- | --- |
+| `getPage` | One published page (or `null`) |
+| `FloconPage` | Renders one page from its data |
+| `getFloconMetadata` | Title, description, canonical, hreflang, `og:*`, `twitter:*` as plain data |
+| `getAllPages` | All published pages (light) |
+| `floconSitemap`, `floconLlmsTxt` | Sitemap XML and `llms.txt` text |
+| `createFloconClient` | Typed Packages API client (server only) |
+| types | `PageEntry`, `UrlOption`, `TokenOption`, `FloconPageData`, `paths`, `components` |
+
+## Docs
+
+[flocon-ai.com/docs](https://flocon-ai.com/docs)