Headless API vs. Codegen
tl;dr:
Most users use the Headless API. That’s what’s recommended for most projects. It is much simpler, has fewer moving parts you must manually manage, and is portable to more frameworks.
Codegen is more complex, and is for more advanced use cases. It is typically for developers who want to use Plasmic as a UI builder, but attach code/logic/behavior arbitrary stateful React apps. It requires you manage the syncing of actual source files, committing them into your repo, etc.
Build-time codegen provides the workflow of the Headless API but for users who also either need greater control/auditability or who use runtimes that do not support dynamic code evaluation (like Cloudflare Workers).
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.
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.
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.
Build-time codegen
The exception to this is build-time codegen. This enables you to wield codegen in a fashion more similar to the Headless API (next), and is esp. useful for teams needing the content management workflow but on platforms that do not support dynamic code evaluation, like Cloudflare Workers. Learn more.
Which scheme should you use?
In short, use the Headless API unless you have a good reason not to.
Some more specific cases below.
I want to embed Plasmic-created apps/screens into my application codebase.
Use the Headless API. You won’t need to sync or manage source files this way.
I want to use Plasmic as a CMS—letting non-developers publish content.
Use the Headless API. 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.
I want to use Plasmic as a CMS but am using a Cloudflare Workers-based edge platform that doesn’t support Headless API.
Use Build-Time Codegen.
You can thus avoid the overhead of needing to manage or check in the generated files into your version history.
You can do this by running plasmic sync as a step in your build process.
Learn more.
I want to use Plasmic as an IDE/UI builder that just generates presentational components, and write all the behavioral logic myself as normal code.
Use Codegen.
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 parts of Plasmic Studio itself, for instance.