Get Started with Studio (Preview Feature) | Yext Hitchhikers Platform
Introduction
Studio is a web development tool that makes it easy to design, build, and manage websites in a no-code visual editor. While most other what-you-see-is-what-you-get (”WYSIWYG”) editors de-prioritize the developer experience, Studio works well with a development workflow by generating React components under the hood. As users make changes in the visual interface, Studio is writing human-readable React components. Developers can easily modify the React source code and collaborate with non-coders in building web pages.
Studio is a tool that lets Admins and Developers alike build React applications with ease. For now, we’re focused on Applications corresponding to a Site, but that may change in the future. Here’s a screenshot of Studio in action:
Studio Compatibility
In order to use Studio, a site must be built in Pages, using the newest architecture. Please note that Classic Pages sites are not able to leverage Studio. To verify what type of Yext site you have, check out this page .
In order for a Pages site to work with Studio, components must follow certain conventions and the repository must include configuration files. During the Feature Preview period, we recommend that you build all Studio sites using this starter repository . If you have not started a site using the Studio starter, your site will not be compatible with Studio.
Once Studio moves out of Feature Preview, you will be able to take current Pages sites and make them compatible with Studio.
Set up your Studio Repository
There are two ways to run Studio. We’ll walk through instructions for both below.
- In the Yext Platform
- Locally (on your own computer)
Choose whichever one is easiest for you. If you are not familiar with running code locally on your computer, we recommend using the Yext Platform to run Studio.
Here are some useful resources to keep handy:
- Demo Account - Sign up for a free playground account if you are a first time user.
- Studio Demo Repo - The Github repo you’ll be cloning.
Running Studio in the Yext Platform
- Fork this repo to your GitHub account.
- Deploy that site on Yext (deploy directions
here
).
- If your account is empty, your deploy may fail, but don’t worry. This site contains dummy
localData
to ensure your site builds and to help you visualize your site. Note: this may not match content in the Yext Platform.
- If your account is empty, your deploy may fail, but don’t worry. This site contains dummy
While you’re waiting for your account to deploy, let’s fill your account with dummy data. Navigate to Apps > Solutions and click on the Studio Pages Starter Resources tile. Then click View Solution.
- In the Admin Console tab that opens, click Apply in the top right.
Enter the account ID of the demo account you’re using. You can find this in the URL
/s/<account ID>/...
.In the middle of the modal, click Start Authorization Flow. You may need to sign in here. Then close the tab when you see the “Authorization complete!” message.
Continue through the rest of the flow to apply the starter resources to your account.
Once the site is deployed, go to the deploy screen and click Code Editor.
Click on the pencil icon next to the branch you would like to open.
Click View Live Preview.
- If the preview initially gives an error, the server may not have loaded yet. Wait for 30 seconds to one minute and try again.
Running Studio Locally
- Fork this repo to your GitHub account.
- Deploy that site on Yext (deploy directions
here
).
- If your account is empty, your deploy may fail, but don’t worry. We’ll get some dummy data in your account soon!
- Ensure you have all development dependencies required for Pages development.
- Clone the repo you just forked to your account by running
git clone <my_new_page_repo>
. - After cloning the repo,
cd
into the repository and runnpm install
. - Run
yext init -u sandbox <account_id>
oryext init <account_id>
if connecting to a production account. - Run
yext resources apply platform-config
to fill your sandbox account with dummy data. - Authenticate into the account by copying the link shown in the terminal into your browser and clicking “Authorize”.
- Run
npm run studio
.- If you encounter an issue, try running
nvm use 18
and the re-runnpm run studio
.
- If you encounter an issue, try running
- Wait patiently for Studio to open. Success!
Studio
and Studio-Plugin
. You can run the following command to keep up to date: npm install @yext/studio-plugin@latest @yext/studio@latest
. Windows is not supported on versions below 0.12.0 for Studio or Studio plugin.
Troubleshooting Setup
If you encounter any issues, make sure to try the following:
- Ensure you are using Node 18. If you use
nvm
, you can runnvm use 18
. - Ensure your account has at least one product entity. Make sure you have successfully applied the resources in
platform-config
to your account, as your site is expecting some data from the platform.- You can run
yext resources apply platform-config
to push the dummy data into your account.
- You can run
Updating Studio Version
While Studio is in preview, you will likely want to upgrade your version of Studio to the newest version to take advantage of new product features. It is possible that some of these versions will introduce breaking changes while Studio is in preview, so be mindful when updating.
There are two important packages that require updating, and you can see their most recent versions on the npm registry by following the links below:
- Studio: npm registry
- Studio-Plugin: npm registry
To update to the latest version of Studio, run the following command:
npm install @yext/studio-plugin@latest @yext/studio@latest
To update your version to a specific version, modify the package.json
file to the most recent version. This change will often look like the following:
...
"@yext/studio": "0.n.0", // Change the version here
"@yext/studio-plugin": "0.n.0", // Change the version here
...
Once the versions are updated, re-run npm install
to ensure you pull down the newest version.
Limitations
As a preview feature, Studio has certain limitations. As of version 0.12.0
, the following limitations should be noted:
- To use a component in Studio, the following conditions must be met:
- The name of the component must match exactly the name of the component file.
- The component must be exported as the default export.
- The component must export an interface with naming convention:
<component>Props
.
Manage Pages
Your site currently has one page: product
. This page is actually an entity template. Studio has chosen a random entity to render the preview you see. You’ll want to add more pages, which can be either static or entity templates. Learn more about static and entity templates in the
Overview of Templates unit
.
From this page, there are several actions you can take to manage your pages:
- Add a new page by using the
+
icon. A modal will appear, prompting you to select a “Static Page” or “Entity Page.”- If you select “Static Page,” you will be prompted to give the page a name and specify its URL slug.
- If you select “Entity Page,” you are first able to specify entity IDs, entity types, or saved filter IDs. Then, you can specify the page name or its URL slug.
- Under the hood, a new TSX file is generated in the
src/templates
directory of your repo. If you created an entity page, this template will include a Stream based on the specifications you submitted.
- Remove a page by clicking the
x
icon associated with it. - Toggle between different site pages in the editor by clicking on the desired page name under the Pages header. A checkmark will appear to indicate which page is active in Studio’s Edit Mode.
Manage Components
Adding and Removing a Component
Now that you have a page, you probably want to do some things with it. Specifically, you’ll want to add components to it. Once you’ve set the desired page to active, click the Insert icon in the top-left and you will see a drop-down like the following:
These are the various components built in to the starter repo that can be added to your page. For now, you can ignore containers. Those will be described later. Once you select a component, it will appear in the middle preview pane and on the left-hand side under Layers.
In the Layers pane, you can re-order the components on the page by simply clicking and dragging them.
Remove components by selecting them and then clicking the X
that appears next to it.
Configuring Components on a Page
To configure the Component, click on it under the Layers section. That should highlight it in the page preview. Additionally, Properties will appear on the right-hand side that you can populate for the component. For example, when you fill in the name
property of the banner, a title appears for the banner in the preview pane.
Manage Content
There are several ways to update content on components and pages:
- Manually hardcode: Add content manually by filling in the property values directly as we did above.
- Map to Content fields: Tie content to the platform to streamline content updates. See Stream-Powered Properties section below.
- Map to globally set Site Settings: Tie content to common values that can be accessed anywhere on the site. See Site Settings-Powered Properties section below.
Stream-Powered Properties
For a Stream to power component property values and allow you to tie values to Content fields, additional setup needs to be done first outside of Studio by a developer. Check out this developer section below on Stream-Powered Properties .
Once you set up stream-powered properties for a page, you’ll notice a + appear on the right side of property value fields. Clicking this opens up the Field Picker which allows you to embed Content fields in the component property value.
As you can see in the screenshot below, setting the value property as [[name]] - [[c_ability]]
(the field names filled in automatically when you pick the fields from the Field Picker list), updated the preview to show the preview name as “Armada ARV 100 Skis - Intermediate-Advanced”. The content was pulled from these fields on the sample entity.
Site Settings-Powered Properties
Websites frequently have content shared across pages. You can use the Content to maintain attributes that are accessible to all pages within a site. For example, when you click on the Site Settings tab in the right pane, you’ll see there’s a Primary Global Color and an Experience Key. Both of these properties are defined globally so that any page and component can access them.
To use these Site Settings, you’ll need additional setup done by a developer. Check out this developer section below on Site Settings .
Once a developer has set up these variables, you’ll find them under this tab for every component you click into. You can modify them for the whole site and also use them in your components.
File History and Committing Changes
What if you make a mistake in the Editor? Say removing a Page accidentally, updating a component’s properties incorrectly, etc. By maintaining a history of your edits, Studio provides powerful Undo functionality. You can undo actions one at a time, until you return to the desired state. Likewise, Studio has Redo functionality. Both features are accessed in the top-right, using these buttons:
Once you’re happy with the changes made during your session, you can commit them to your site.
If you are running Studio locally, you can click the Save button on the top-right. This will make all updates to the necessary TSX files in your local repo. Note that Studio does not write to any files until Save is invoked. The preview is actually powered by a virtual representation of the site. Then, to commit your changes to your Github repo, click the Deploy button.
If you are running Studio in the Yext Platform, you will not see a Save button. Instead, you can directly commit your changes to your Github repo using the Deploy button.
Stream-Powered Properties (Developer)
For a Stream to power component property values and allow you to tie values to Content fields, additional setup needs to be done first outside of Studio by a developer.
Firstly, the developer needs to manually update the page’s TSX file to resemble a PagesJS Template. This allows the page to accept a Stream document
and scaffolds a Stream Configuration for the page/template. The modifications would look something like:
export const config: TemplateConfig = {
stream: {
$id: "my-stream-id-1",
fields: [],
// Defines the scope of entities that qualify for this stream.
filter: {
entityTypes: ["location"],
},
// The entity language profiles that documents will be generated for.
localization: {
locales: ["en"],
primary: false,
},
},
};
const Component: Template<TemplateRenderProps> = ({document, props: ComponentProps}) => ...
export default Component;
The fields
attribute of the Stream Configuration can be populated from the UI. If someone were to use document.address
as the value for an Expression
property, Studio would addend "address"
to the fields
array. All other aspects of the Stream (localization
, filter
, etc.) must be configured directly in the file by the developer.
Once a field value is used for a property and the above setup is complete, the page becomes an entity template, so it’s no longer static. A user can select Content fields to embed in property values by using the field picker.
Check out the stream-powered properties section above for more details on managing stream-powered properties.
Site Settings (Developer)
Often, you will want to have attributes that are accessible to all pages within a Site. Site Settings (attributes) can be used within properties in a similar way to Streams data. For example, you can specify siteSettings.["Global Colors"].primary
and the corresponding Site Settings value will be passed to the component.
In Classic Pages, these were known as Site Attributes. In Pages, we usually recommend adding these attributes to a site entity that stores
globl data
. Studio provides an additional mechanism for supplying these values: the src/siteSettings.ts
file. We cannot rely exclusively on a site entity because Studio can be used outside of PagesJS.
The siteSettings.ts
file is initially set up by the developer:
export interface SiteSettings {
attribute1: string,
attribute2: number,
primaryColor: HexColor,
}
export default {
attribute1: 'Hello World',
attribute2: 1,
primaryColor: '#AABBCC',
}
The SiteSettings
interface defines what attributes are available site-wide. Optionally, defaults can be provided using the default export.
With this file in place, a user can edit the values of the settings directly in Studio. To do so, click on the Site Settings tab in the right-hand panel:
Check out the site settings-powered properties section above for more details on managing site settings-powered properties.
Authoring New Components (Developer)
Developers have the ability to craft new Components that can then be used in Studio. As an example, an admin might ask for a net-new piece of functionality on the page. The developer would create the corresponding component, which the admin could then use. Authoring a component is fairly simple. It starts with adding a new TSX file to src/components
. The file will have the form:
export interface SomeComponentProps {
prop1: string,
prop2?: number,
...
};
export default function SomeComponent(props: SomeComponentProps) {
return (
<div>
...
</div>
);
}
Optionally, the developer can specify initial values for the component’s properties. In the same file, they’d add something like:
export const initialProps: SomeComponentProps = {
prop1: 'Hello World'
};
When the new component is added to a page, the Properties tab on the right-hand side will be seeded with the defaults.
We’ve already added a few custom components to the starter for you. For example, a Banner component that can be used to prominently display an entity’s address. Additionally, we have added an Entity Result Card and CTA in case you want to add Search functionality. You can use these components as a guide when writing your own.
Importing Component Libraries (Developer)
uthoring is one way to register new components with Studio. An easier way, one that promotes wider re-use, is to import an NPM package containing custom Studio components. These packages are called Studio Plugins. A plugin’s entry point is structured like:
import { PluginConfig } from "@yext/studio-plugin";
export * from "./components";
const PluginConfig: PluginConfig = {
name: "[npm-package-name]",
components: {
SomeComponent: "src/components/SomeComponent.tsx",
AnotherComponent: "src/components/AnotherComponent.tsx"
},
};
export default PluginConfig;
To use a Plugin:
- Install it with
npm install [npm-package-name]
. - Add a
require
statement to the top of yourstudio.config.ts
. Something likeconst SomePlugin = require("[npm-package-name]")
. - Add the imported plugin to the
plugins
array instudio.config.ts
.
Now, all components in the plugin will be available for use in Studio.
We’ve published a Plugin library, @yext/studio-plugin-search-ui-react
, to power a basic Universal Search. The library exports three components: SearchBar
, UniversalResults
, and ResultsCount
.
To use these components, first add a SearchProvider
component to the page, which can be found under the Containers category. This is necessary so that the Search components can properly interact with one another.