Developer docs

Choose what you want to build

Justflows exposes three extension surfaces: an in-process TypeScript SDK for plugins, a declarative block-and-CSS format for themes, and a read-only HTTP API for headless applications.

Three ways to extend Justflows

Plugin

Add business logic, blocks, admin pages, routes, jobs, storage, and lifecycle handlers.

Build a plugin

Theme

Ship design tokens, CSS, templates, template parts, patterns, and demo layouts.

Build a theme

Headless app

Read published content, types, media, and menus from any frontend using JSON.

Use the API

Development environment

The public CE monorepo is the reference implementation and development workspace. It includes the SDK, runtime, example extensions, tests, and package tooling.

Terminal

git clone https://github.com/JustFlows/justflows-ce-development.git
cd justflows-ce-development
pnpm install
pnpm --filter @justflows/sdk build

Extension lifecycle

1. Declare

Give every extension a dot-namespaced ID, SemVer version, GPL-compatible license, and supported engines.justflows range.

2. Build

Compile plugins to runnable ESM. Themes remain declarative JSON and CSS. The host never installs dependencies or compiles uploaded packages.

3. Test

Run type checking and focused tests against the SDK version and host range you declare.

4. Package

Create a gzipped ustar .jfpkg with justflows.json at the archive root and all runtime files included.

Compatibility at a glance

The runtime exposes ctx.runtime.justflows, ctx.runtime.sdk, and ctx.runtime.sdkApi. Use a bounded host range and test both its lowest supported version and the current release.

justflows.json

{
  "schemaVersion": 1,
  "type": "plugin",
  "id": "acme.seo",
  "name": "Acme SEO",
  "version": "1.0.0",
  "publisher": "Acme",
  "license": "GPL-2.0-or-later",
  "engines": { "justflows": ">=0.1.8 <0.2.0" },
  "permissions": []
}