Feature request: Local JSON-style versioning for Cornerstone Global Blocks/Theme Options (CI/CD workflows)

Hi Theme.co team,

We are building on Pro Theme (with Cornerstone) for a client project, and we’re currently moving that site into a containerized, Git-based deployment pipeline — immutable Docker images built from a versioned repo, with the database and uploads treated as the only persistent, non-versioned state. Pro’s flexibility made it an easy choice for this project, and pairing it with ACF Pro covers almost everything we need on the content-modeling side. We wanted to share something the DevOps engineer of the client found while designing this pipeline, in case it’s useful input for Cornerstone’s future direction—not as a complaint, but as a specific, fixable gap we noticed while holding Pro to the same bar we’d hold any professional-grade dev tool to.

What we found. A page built with Cornerstone stores several distinct kinds of information together, as one document: section/column structure, per-component settings, editor-entered text, references to media IDs, form definitions and their actions, and bindings to Global Blocks/Components. A .tco export moves that whole document as a unit. In practice, that means if a developer changes a page’s structure in a dev environment while an editor changes that same page’s copy or an image in production, there’s no clean way to reconcile the two — the import is whole-document, not field-level, so one side’s changes get overwritten or the import conflicts outright. That in turn means any Cornerstone-built page is effectively pinned to one specific database/environment: it can’t be treated as portable, versioned release state the way the rest of our stack (theme templates, plugin code, theme.json ) can.

Why we’re flagging this specifically for Pro. Pro isn’t a beginner page-builder — it’s positioned for developers and advanced users building serious, ongoing client work, and it already includes the pieces (bundled Cornerstone, first-class ACF PRO support, a real update/licensing API) to be treated as a professional platform rather than a closed website-builder product. We think that segment increasingly expects the same CI/CD, multi-environment, reproducible-build workflow that’s now standard for the rest of a modern web stack — which is exactly what containerization and “Git as source of truth” are about. Right now, the Cornerstone-authored parts of a Pro site are the one piece of our stack that can’t join that workflow, which is a real limiting factor when we’re scoping this kind of client.

A model that already works, and that you already ship. ACF PRO solves a very similar problem for field groups with Local JSON : the definition of a field group is written to a versionable .json file and synced via wp acf json sync , while the values a user enters per post stay in the database, exactly where they belong. That split — schema/definition as a file, content as DB — is precisely what we think Cornerstone is missing today. We’re not suggesting page content itself (what an editor types into a specific page) needs to become file-based — that’s genuinely DB-shaped, per-instance data. But the design-system layer of Cornerstone — Global Blocks/Components, TSS style definitions, and Theme Options — is conceptually much closer to ACF’s field group definitions than to page content: it’s authored by developers, reused across pages, and is exactly the kind of thing a team would want to review in a pull request and ship as part of a release.

The ask, concretely: would Theme.co consider an opt-in “Local JSON”-style export/sync mechanism for Cornerstone’s Global Blocks/Components, TSS definitions, and Theme Options — mirroring the ACF PRO pattern you already ship today? Even a partial version (say, Global Blocks and Theme Options first) would let teams like ours put the reusable, developer-owned part of a Cornerstone site under version control and through a normal review/release process, while leaving actual page-by-page content exactly where it is now. We think this would meaningfully strengthen Pro’s positioning for the higher end of the professional/agency market, where reproducible, git-driven deployment is quickly becoming a baseline expectation rather than a nice-to-have.

Happy to share more detail from our internal research on this if it’s useful — we did a fairly deep dive into how Cornerstone’s update/licensing mechanism and data model work while building our pipeline, and would be glad to compare notes.

Thanks for reading, and for building a theme that’s actually worth taking this seriously about.

1 Like

Thank you for your feedback @referee. I’ll pass this along to our development team.

1 Like

Hi again, @christian and thank you for that.

Following up on my earlier note about a Local JSON-style mechanism for Cornerstone’s developer-owned layer, and taking you up on the offer to compare notes. We’ve since finished the research that prompted it, and two things came out of it worth sending.

First, I can narrow the original ask considerably.

I see the Control List Editor gained import and export in 7.9.0, for the Variables list, Twig and External API globals. That is the same split I was asking about — developer-owned configuration made portable, page content left where it belongs — so the pattern already exists in Cornerstone rather than needing to be invented. What I’m asking for is its extension to Global Blocks/Components and Theme Options , which is a continuation of something you have already shipped rather than a new direction.

Second, we ended up reading the bundle format, and it is better than we expected.

For context on how we got here: we’re moving a Pro site into a containerized, Git-based pipeline, and needed to know what we would be building tooling against. On Pro 6.9.3 / Cornerstone 7.9.3 we found:

  • .tco is a plain ZIP, and .tco-tmpl inside it is base64(gzip(JSON)) — readable in one line, not an opaque blob.
  • The document manifest is clean, structured JSON that already declares its dependencies as an ordered task list — global colours used, images referenced by content hash, the document itself with a key and a strategy field, and terms.
  • Media is content-addressed: the manifest key matches the filename prefix, with the original filename and a resolution mode alongside. Export names images sensibly — img-<hash>-<original>.jpg .
  • Bundles carry no nonce, so the same content produces the same payload.

That is a considerably more tractable format than we had assumed, and it changed our estimate for building tooling around it. Which leads to the actual request:

Could any of this be documented, even informally?

One thing we could not work out is what the sig field on a document digests. It does not match an MD5 of the encoded meta under any serialization we tried, nor of the document with sig removed, on either of two sample documents. If that is a checksum we could verify against, knowing the algorithm would let us use yours rather than inventing a parallel one.

More generally: teams building deployment tooling around Pro are going to reverse- engineer this format whether or not it is documented, and will get it subtly wrong in ways that produce support tickets. Documenting it — even as a short page describing manifest tasks, strategy values, and sig — would turn that into something people build on correctly. Given how clean the format turned out to be, it reads more like a selling point than an exposure.

(One small thing while we were in there: some bundles from the template library carry images named from their own base64 payload — img/<hash>/seLZjiCzalIAAAAASUVORK5CYII= and similar — where a local export on 7.9.3 produces proper filenames. Contents are intact, so it is cosmetic, and it looks like older packaging on the library side rather than anything in the plugin.)

Happy to share the sample bundles or our notes if either would be useful.

Kind regards

Hey John,

Feel free to drop the sample bundles and notes or other useful information. Our development team will be checking this in due time.

Christian,

Thank you very much for taking your time on this. I will attach an archive with two documents inside the Secure Note.

Thank you, John. We’ll check it out.

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.