Themes

Admin → Themes. Upload a .jfpkg or zip (POST /api/themes, administrator). Activate with POST /api/themes/:id/activate. List from GET /api/themes. Hooks: theme.installed, theme.activated. Admin → Themes also lists every published theme from the hosted Marketplace, with installed, paid, and coming-soon states; community themes install through the same signed-package flow, and inactive installed themes can be deleted (the active and bundled themes are protected).

Every folder under themes/ is registered in the themes table automatically the first time the admin themes or customizer screen loads — previously only justflows.default was seeded, so a bundled or dropped-in theme is now selectable without a .jfpkg upload. syncBundledThemes also refreshes an existing row's name, version, and manifest from the folder while leaving its status, activated_at, and css_variables as the admin left them. The bundled starter is `justflows.default` under themes/default (templates, styles, patterns, justflows-theme.json).

Patterns#

GET /api/themes/patterns and GET /api/themes/patterns/:slug feed the block editor. Patterns are starter block trees, not separate post types. A pattern can declare requiresBlockTypes; if an active plugin does not provide a required block, its card explains what is missing and links to Extensions instead of importing broken content. patterns/product.json and patterns/post.json also double as the starting canvas for a new product or post whose editor opens empty, matched by an explicit type allowlist (defaultBlocksForContentType). The default theme includes a Contact pattern that uses the Forms block.

Theme builder#

• Home — choose any published page for /, or turn the active theme's current home layout into an editable page.
• Blog — choose any page as the blog index, or create one from the theme default. Add Post List to build a custom paginated index.
• Footer — edit the shared site footer as blocks, keep a draft, and publish it. Sites without a custom footer fall back to the theme's demo/footer.json.
• Header — keep a library of named headers; one is the site default and renders on every page. Each page picks its header — the site default, a named header, or *None* — from the page builder.
• Templates — edit any template in the hierarchy (index, front-page, single, page, 404, …) visually; edits save per site with draft / publish / reset.

Template hierarchy#

Themes own page structure through a WordPress-style template hierarchy — one JSON block document per slot under templates/, shared chrome under parts/, and a visual editor at Theme builder → Templates. See Templates.

Theme-shipped site chrome#

A theme can ship default chrome that is resolved live at render, the same way demo/home.json provides a home layout. demo/footer.json is a block document — Theme builder → Footer seeds its canvas from it and GET /api/template-parts/footer returns fromThemeDefault. demo/header.json is a sparse PageHeaderConfig merged over the built-in default, used when the header library has no default entry. Nothing is written to the database on activation; an admin edit always wins.

The visual menu designer adds front-end the default theme ships: the partials/nav-menu.ejs renderer, /js/site-nav.js (desktop flyouts, an off-canvas mobile drawer, keyboard navigation, prefers-reduced-motion), and the .jf-nav styles in global.css. The shared data-jf-devices CSS primitive for per-device visibility is emitted into every theme's /theme.css. Themes contribute menu layout presets through the menu.design.presets filter.

Theme-contributed controls#

A customize block in justflows-theme.json adds the theme's own Customizer sections and controls (color, range, select, font, each keyed by the CSS custom property it sets), and a blockControls map promotes chosen theme variables to first-class fields in the block inspector. See Theme customizer and Block editor.