Overview

@floggy/cms is the single dependency you install to build a blog on Floggy. It returns your content fully typed and ready to render - html, markdown, SEO metadata, JSON-LD, and feeds - so you drop it straight into your pages. Zero runtime dependencies.

Install

Quickstart

A working blog index plus a post page, with SEO, in about 15 lines.

import { createClient } from "@floggy/cms";

const floggy = createClient({ project: "projecta" });

// Blog index
const { posts, pageInfo } = await floggy.posts.list({ page: 1, perPage: 10 });
for (const post of posts) {
  console.log(post.title, "/" + post.slug);
}

// Post page (rendered HTML + adjacent nav + SEO block + JSON-LD)
const post = await floggy.posts.get("hello-world", { format: "html" });
console.log(post.rendered);          // ready-to-inject HTML string
console.log(post.adjacent.prev);     // { slug, title } | null
const metadata = floggy.seo.meta(post); // plain Next.js-compatible Metadata object

Configuration

createClient({
  project: "projecta",                 // required: the Floggy username/project
  key: process.env.FLOGGY_KEY,         // optional: flg_ key for drafts/private content
  site: {                              // optional: used by feeds.*
    url: "blog.example.com",           // public origin (protocol auto-added)
    name: "Example",                   // defaults to project name
    description: "My blog",            // defaults to "<name>'s blog"
    locale: "en",                      // defaults to "en"
  },
  fetch: customFetch,                  // optional: custom fetch implementation
});

Auth

Public reads need no key. Pass an flg_ key only to read drafts or private content. Use a Read-only key in any frontend - a leaked read key only exposes content that is already public. Never embed a Full-access key in a frontend.

const floggy = createClient({ project: "projecta", key: process.env.FLOGGY_KEY });

Methods at a glance

The client exposes four namespaces:

  • posts - list, get, search
  • tags - list
  • seo - meta, jsonLd
  • feeds - sitemap, rss, robots

See the SDK reference for full signatures, options, and return shapes.

Errors

Every non-2xx response throws a typed error.

import { FloggyError, RateLimitError } from "@floggy/cms";

try {
  await floggy.posts.get("missing");
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("retry after", err.retryAfter, "seconds");
  } else if (err instanceof FloggyError) {
    console.log(err.status, err.message, err.code);
  }
}

FloggyError carries status, message, code, and url. RateLimitError (status 429) adds retryAfter (seconds, parsed from the Retry-After header).

Next

  • Quickstart - list, fetch, render, and add SEO in about 15 lines.
  • SDK reference - every @floggy/cms method, with Next.js and TanStack Start examples.
  • Authentication - creating flg_ keys, the scope table, presets, and key-safety rules.
  • Webhooks - subscribe to post.published / post.updated and verify signatures.