Headless API vs. Codegen
tl;dr:
Most users use the Headless API. That’s what’s recommended for websites, has fewer moving parts you must manually manage, and is portable to more frameworks. It lets you use Plasmic as a CMS—allow non-developers to ship content (such as landing pages, marketing content, etc.) without developer involvement.
Codegen is a more advanced use case. It is for developers who want to use Plasmic as a UI builder for arbitrary stateful React apps. It requires you manage the syncing of actual source files, committing them into your repo, etc.
Overview
Turning your designs into production code is Plasmic’s flagship capability. Plasmic has two methods of consuming designs built in Plasmic from your codebase. We’ll look at each and then help you decide which makes sense.
Codegen
You use the Plasmic CLI (plasmic sync) to pull Plasmic-generated React code directly into your git repo. You treat the generated code just like any React code—it is checked into your git repo, versioned with git history, and deployed by your usual pipelines. As “just code”, you can review, test, deploy, and rollback design changes just as you can any code changes.
However, that means whenever you want to deploy some design changes to production, you’ll need to run plasmic sync to generate new code, create a git commit, possibly go through code reviews, merge the commit into main branch, and deploy as usual. Because the Plasmic-generated code lives in your codebase, deploying changes necessarily involves developers who have access to work through this workflow. Depending on your use case, this may be fine, or too heavyweight.
Headless API
No Plasmic-generated code is checked into your git repo. Developers need only add some code that fetches and renders the latest published pages/components as designed in Plasmic.
For instance, if you want to render a non-page component somewhere in your app, you use a PlasmicComponent component:
<PlasmicComponent component="LandingPagePromotion" />
Importantly, for frameworks that support server-side rendering or static generation, such as Next.js and Gatsby, you can ensure that the fetching happens server-side/at build-time. Whenever you want to deploy some new or updated pages/components to production, you just need to trigger a re-build of the site, which will pick up the latest changes, without involving developers.
If you are familiar with Content Management Systems, this is a very similar workflow—once the build-time fetching is integrated into the codebase, non-technical content owners in the marketing and design teams can exercise autonomy in publishing content without blocking on developers. Unlike a CMS, Plasmic does not require developers first define a schema and implement frontend code, and non-developers have the freedom to build freeform content.
Which scheme should you use?
In short, the Headless API makes it possible for non-developers to push design changes without ongoing developer involvement. We believe it is a great workflow for projects involving mostly static designs, where designers / marketing / etc. want to be able to deploy changes made in Plasmic without involving developers. These are similar workflow benefits to adopting a CMS—Headless API lets you use Plasmic as a CMS that gives you full visual control and page-building capability.
You should use the Headless API if you use Plasmic as a CMS.
Here, we primarily want to enable non-developers (marketing, design, content editors) to build landing pages and other content without involving developers.
Developers perform the initial integration of Plasmic into the codebase, and optionally register code components for non-developers to use. But after that, developers should be able to mostly step aside. In particular, developers don’t expect to heavily instrument the Plasmic components with logic/behavior—any such dynamic behavior is packaged in code components.
You should use Codegen if you use Plasmic as an IDE/UI builder.
You may prefer this when building a dynamic app with a lot of code instrumentation (via overrides passed to Plasmic* components).
You’re likely using Plasmic primarily yourself as a development tool, taking advantage of its fast and easy visual crafting DX. Optionally, you can invite technical designers to jump in and edit the designs, or even create entire new designs.
You expect the code to be versioned in your git history.
This is how we build Plasmic Studio itself, for instance.