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).

Marketplace themes update the same way as plugins: Themes shows Update available with an Update to vX button, and each theme has an Auto-update switch that stays within the same major version (see Plugins). Save as new theme writes the fork to the site's own folder, packages-installed/sites/<siteId>/themes/local.<slug>/. Forks saved earlier keep working, and deleting a fork removes its folder.

Marketplace themes include Halden, a clean clothing-store theme with collection tiles, a lookbook, and product styling for Shop; Zine, a playful blog and news theme with sticker-style cards, terminal-style code blocks, and a full dark mode; Beacon, a calm help-center and documentation theme with a search hero, icon topic cards, step-numbered articles, and styling for the Helpdesk pages; and Space Voyage, an editable cinematic homepage that travels from Mars to Earth to Venus with video transitions, a canvas portal, and planet facts. Browse them all on the Marketplace.

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.

Widget areas#

A theme can declare its own sidebars and columns under widgetAreas in justflows-theme.json, with starting widgets in widgets/<key>.json, or place the Widget area block in a template. Site owners fill them under Appearance → Widgets. See Widgets and sidebars.

Theme scripts and remote media#

A theme can list scripts in justflows-theme.json: package-relative .js or .mjs files that the public layout loads in order through /theme.js. They run as classic deferred scripts, so wrap each in an IIFE and use no imports or exports. Each file may be up to 512 KiB and the bundle up to 1 MiB. The bundle is served no-store, so switching themes never runs an old one, and scripts never run in the block editor.

For remote video or audio, declare up to 20 exact HTTPS origins in mediaOrigins. The default security policy then adds only those origins to media-src; an explicit media-src policy is left alone. Space Voyage uses both.

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.