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 browser through Codespaces
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 Codespaces 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. You can get a free.
2. Studio Demo Repo - The Github repo you’ll be cloning.

Running Studio in Codespaces

1. Fork this repo to your GitHub account.
2. Deploy that site on Yext.
   • If your account is empty, your deploy may fail, but don’t worry. We’ll get some dummy data in your account soon!
3. Once your site is deployed, click “view repository in GitHub” on the deploys screen.
4. In Github, press the green “Code” button and click to make a new Codespace.
   • Once created, the Codespace will have a unique identifier that you can open in the future.
5. Wait until everything is finished installing - this can sometimes take a minute or two.
6. If the terminal is not open, press CTRL+` to open a new terminal.
7. In the terminal, run yext init -u sandbox <account_id> to connect to your sandbox account. If using a production account run yext init <account_id>.
8. Authenticate into the account by copying the link shown in the terminal into your browser and clicking “Authorize”.
9. Next run yext resources apply platform-config to fill your sandbox account with dummy data.
10. Return to Codespaces and run npm run studio.
    • If you encounter an issue, try running nvm use 18 and the re-run npm run studio.
11. Wait patiently for Studio to open. Success!

Running Studio Locally

1. Fork this repo to your GitHub account.
2. Deploy that site on Yext.
   • 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!

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 Knowledge Graph
   • 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 your versions, 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.7.0, the following limitations should be noted:

1. To use a component in Studio, the following conditions must be met:
   1. The name of the component must match exactly the name of the component file.
   2. The prop interface must be of the form <ComponentName>Props.
   3. The component must be exported as the default export.
2. Component interfaces cannot accept complex types. They must use Javascript/Typescript primitives (e.g. number, string, etc).
3. All templates must first be created in code to ensure they follow the proper format for a PagesJS template before they can be edited in Studio. This document explains the requirements for a properly formed PagesJS template.

Manage Pages

Your site currently has one page: product. This page is actually an entity template. Studio’s 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 name your new page. Under the hood, a new TSX file is generated in the src/templates directory of your repo.
• 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 and modules. Those will be described later. Once you select a component, such as Banner, 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 Knowledge Graph fields: Tie content to the Knowledge Graph to streamline content updates.
• Map to globally set Site Settings: Tie content to common values that can be accessed anywhere on the site.

Stream-Powered Properties

For a Stream to power component property values and allow you to tie values to Knowledge Graph 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 Knowledge Graph 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 Knowledge Graph 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 click the Save button on the top-right. This will make all updates to the necessary TSX files in the 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.

To commit your changes to your Github repo, click the Deploy button.

Stream-Powered Properties (Developer)

For a Stream to power component property values and allow you to tie values to Knowledge Graph fields, additional setup needs to be done first outside of Studio by a developer.

Firstly, the developer would need 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 Knowledge Graph 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. One is a Banner, to prominently display an Entity’s address. We also 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.