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.

1. In the Yext Platform
2. 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:

1. Demo Account - Sign up for a free playground account if you are a first time user.
2. Studio Demo Repo - The Github repo you’ll be cloning.

Running Studio in the Yext Platform

1. Fork this repo to your GitHub account.
2. 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.

3. 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.

   1. In the Admin Console tab that opens, click Apply in the top right.

   2. Enter the account ID of the demo account you’re using. You can find this in the URL /s/<account ID>/....

      

   3. 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.

   4. Continue through the rest of the flow to apply the starter resources to your account.

4. Once the site is deployed, go to the deploy screen and click Code Editor.

5. Click on the pencil icon next to the branch you would like to open.

6. 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

1. Fork this repo to your GitHub account.
2. 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!
3. Ensure you have all development dependencies required for Pages development.
4. Clone the repo you just forked to your account by running git clone <my_new_page_repo>.
5. After cloning the repo, cd into the repository and run npm install.
6. Run yext init -u sandbox <account_id> or yext init <account_id> if connecting to a production account.
7. Run yext resources apply platform-config to fill your sandbox account with dummy data.
8. Authenticate into the account by copying the link shown in the terminal into your browser and clicking “Authorize”.
9. Run npm run studio.
   • If you encounter an issue, try running nvm use 18 and the re-run npm run studio.
10. Wait patiently for Studio to open. Success!

Note

To run Studio in Windows, make sure you are using the latest version of 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:

1. Ensure you are using Node 18. If you use nvm, you can run nvm use 18.
2. 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.

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:

1. Studio: npm registry
2. 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:

1. 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:

1. Install it with npm install [npm-package-name].
2. Add a require statement to the top of your studio.config.ts. Something like const SomePlugin = require("[npm-package-name]").
3. Add the imported plugin to the plugins array in studio.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.