Build-time codegen

Unlike the headless API, codegen produces actual source files into your repo. However, you don’t have to check them in as part of your version history. This lets you use codegen in a fashion that’s a bit more similar to the headless API. The idea is to only generate these at build-time, whether in your local development environment or your CI/CD pipeline. This will on-demand generate the source files from the latest Plasmic designs, without requiring you to add them to version control.

Why might you want to do this? Typically, the headless API mode of integration is what makes the most sense, but you may be deploying to an environment that does not support dynamic code evaluation (eval())—most notably Cloudflare Workers, which powers Vercel Edge and Shopify Oxygen. This way, you get to use codegen with many of the benefits of the headless API—letting you treat the design/content as data rather than code files you must manage.

Example repo

See an example Hydrogen app, deployed to the Shopify Oxygen runtime.

Setup

Step 1. Run Plasmic CLI in local repo.

Make sure you are able to run plasmic sync in your project locally, and that everything works.

Step 2. Allow CI to run Plasmic CLI.

Copy
git add plasmic.json

This identifies what project(s) to sync and their associated API tokens.

Do not add other Plasmic files. This includes:

  • plasmic.lock, which prevents the CLI from syncing the latest designs.
  • any generated source files, since the CLI would be overwriting these.

It is a good idea to add these to your .gitignore.

Step 3. Add Plasmic as a build step.

Your build script should upgrade all Plasmic dependencies to the latest version, run plasmic sync, and then build the site.

Plasmic upgrades the minimum required CLI version regularly to work with new features.

Copy
npm update @plasmicapp/cli @plasmicapp/react-web
npm run plasmic sync --yes --force
npm run build

Note the --yes --force flags in the sync command, which will automatically answer yes to any prompts from the CLI.

Step 4. Add Plasmic to local dev workflow.

Make sure Plasmic is also synced as a step before your local development server startup as well.

You may want to concurrently use plasmic watch instead of plasmic sync here, and have it run alongside your framework’s dev server.

Was this page helpful?

Have feedback on this page? Let us know on our forum.