visual-editor

This library provides components necessary to set up a Section Library Pages repository that can interact with Visual Editor in the Yext platform.

Package release tags

Run pnpm run release from this repository. The confirmation prompt shows the npm tags. CI publishes with the existing tag, then adds the major-version tags.

Release type	New npm tag
Stable	stable-v<major>
Alpha	alpha-v<major>
Beta	beta-v<major>
Release candidate	rc-v<major>
Any release type	latest-v<major>

For example, 2.0.0-beta.1 uses beta-v2 and latest-v2. Stable 2.0.0 uses stable-v2 and latest-v2. Other prerelease identifiers only get latest-v<major>.

CLI

@yext/visual-editor includes the yextve CLI for creating a Section Library revision from the current Git commit. In a repository that uses Visual Editor, install the package and run its local CLI:

Deploy

npx yextve deploy

Run the command from the dependent repository's root. That repository must include src/library/library.json:

{
  "id": "my-section-library",
  "displayName": "My Section Library",
  "description": "Reusable sections for my site."
}

The command reads the selected Git remote URL and the current commit hash, then creates a revision. With terminal input, it offers to create a missing Section Library. Without terminal input, a missing Section Library is an error: create it before deploying. The command waits for the revision build to finish and returns success only when the build succeeds.

For the built-in Section Library accounts, the API stores library IDs with a yext_ prefix. When the configured account and universe match a built-in account, deploy adds that prefix to the ID from library.json if needed. For example, bar-social-dining is deployed as yext_bar-social-dining in sandbox account 3343916.

Each layout may include one optional preview image directly in its layout directory. Name the file preview.png, preview.jpg, preview.jpeg, or preview.webp; it must be 1 MiB or smaller. During deployment, the image from the selected Git commit is uploaded to mktgcdn and used as that layout's preview image. Once a layout's preview image is set, it can be overwritten by a new image. If no image is present, that layout's former preview image is used.

Before deploying, create a Yext API App in the Yext platform Developer Console and grant it Section Library API write access and have the API key on hand.

Configuration values resolve in this order: --universe (for the universe only), environment variable, .yextrc in the repository root, then an interactive prompt. --universe and YEXT_UNIVERSE cannot be used together.

Environment variable	.yextrc field	Description
YEXT_ACCOUNT_ID	accountId	Yext account ID
YEXT_UNIVERSE	universe	Yext environment (production or sandbox)
YEXT_API_KEY	apiKey	App API key with Section Library API write access
YEXT_ORIGIN	origin	Git remote name

When stdin is a TTY, deploy prompts for missing values, asks whether to use or replace a complete saved configuration, and offers to save prompted values in .yextrc. Without a TTY, all four values must be present and valid through the environment, .yextrc, or --universe. The command does not prompt or write .yextrc in that mode. For example, an orchestrator can set the four environment variables once and run yextve deploy with detached stdin in each pre-provisioned library repository.

A dirty working tree requires --allow-dirty, and a commit that already has a revision requires --allow-duplicate, when stdin is not a TTY. Interactive deployments continue to ask for confirmation. Both modes wait for the submitted revision build to succeed or fail.

Use --verbose (or -v) to print API request details and response data:

npx yextve deploy --verbose

Convert legacy templates

Use this engineering tool when you convert one or more legacy templates in a starter repository to a Section Library. Run it from the section library repository.

npx --package=@yext/visual-editor@latest yextve convert-template

The default is a dry run. It validates the starter and reports the planned library, layouts, and duplicate component IDs. Add --apply to replace the src/library directory. Add --delete-source with --apply to remove converted src/registry/<template-id> directories after replacement.

npx --package=@yext/visual-editor@latest yextve convert-template \
  --apply --delete-source

If the starter does not contain the base Directory and Locator source, the converter adds it to the converted Section Library. The converter creates one Entity layout per legacy template, keeps the first source for each component ID in sorted template order, and reports all duplicate IDs.

Add Directory and Locator

Run this command from a Section Library repository to add editable Directory and Locator sections and layouts. If src/library/library.json exists, its ID prefixes the generated layout IDs. Otherwise, the IDs are directory and locator.

npx --package=@yext/visual-editor@latest yextve add-directory-locator

The command stops before overwriting existing shared, Directory, or Locator source. Pass --overwrite to replace those files after reviewing the generated output.