Creating a Frontend component

Information icon

Prerequisites

  • GitHub customer repository access
  • studio access
  • CLI running

A Frontend component consists of 2 parts:

  1. A schema to make it known to the studio
  2. A React component as its code entry point

The schema is created in the studio which then allows a user to place the component onto any page. The server-side renderer mounts the React components whenever the component appears on a page.

By convention, you should create a new directory for your component under packages/<project>/frontend/frontastic/tastics. You can then create sub-directories for categorizing similar components.

For the following example, we'll create the directory packages/<project>/frontend/frontastic/tastics/example/hello-world.

Specifying the component

The simplest possible Frontend component schema consists of a tasticType, a name, and an empty schema (which means there's nothing to configure for this component). category and description are optional but are helpful in the studio.

{
"tasticType": "example/hello-world",
"name": "Hello World",
"category": "Example",
"description": "A very basic frontend component example",
"schema": []
}
Clipboard icon

Copy this code example, and we'll paste it into the studio in the next section.

Information icon

If you want to, you can add the schema file within the directory created for the component.

Creating the component schema

To create the schema, you can do this in the studio. Open your studio and follow the steps below:

  1. Select the Staging environment from the dropdown, go to the Component area
Error icon

If you're using a sandbox, you'll need to select the Development environment.

9745043 Components on the dashboard

  1. Click the Create schema button, this will open the schema editor

eec6c02 Click create schema to create a component

  1. Paste the JSON into the schema editor from the previous section, then click Validate and preview, then Publish and download JSON

ee4951d Paste the JSON click validate then publish

Information icon

If you include the tasticType in the schema, you don't need to add it to the input field.

Place the component on a page

Once the component has been added to the studio, you'll need to check it works on a page so you'll need to create a page folder.

  1. Switch to Site builder, click New, then select Create page folder

075bb5a Switch to site builder then create a new page folder

  1. Input a page folder name and click Save
Information icon

To keep structure to the page folders we recommend creating a top-level page folder named Developer where each developer can have their own page folder-level (usually their name). This helps to avoid disturbances between different developers.

Remember the path to your page folder. You'll need this path to view the page created later on your staging server. For example: /developer/toby.

You'll then need to create a page version within your page folder that'll contain your Frontend component.

  1. Select your new page folder, then click New, select Create page version

3e20817 Select your new page folder and create a new page version

  1. Input a page name for your page version, and click Save
Information icon

Use a descriptive name for your page versions so they're easy to know what they are. For example, we'd call this example page version Hello world component test.

  1. Click the blue add icon on any of the sections (for example, MAIN), then select a layout element

99f3176 Click blue add icon then select a layout element

  1. Search for the name of the Frontend component you've just created and drag it into your layout element, then click Save

0e7c988 Add your component to the page

  1. Click the more icon on your page version, then click Make default

c91b330 Click more icno then select make default

Implement and register the code

On the CLI dashboard, type t to open the staging test URL, then add the path you created earlier (developer/toby). You'll see the page with your brand new Frontend component with an attempt to render it:

12087a5 Frontastics attempt to render Frontastic component

This message guides you to the next step which is implementing the entry React component. As there's no configuration specified in the schema, the corresponding code is rather simple:

import React from 'react';
const HelloWorldTastic = () => {
return <h1>Hello world</h1>;
};
export default HelloWorldTastic;
Clipboard icon

This should be saved as something like packages/<project>/frontend/frontastic/tastics/example/hello-world/index.tsx.

Before you can actually see the component rendered, there's only 1 important step missing: You need to tell renderer that the component identified by example/hello-world (from the schema) can be mounted using the HelloWorldTastic.

To do so, edit the packages/<project>/frontend/frontastic/tastics/index.tsx and add a line like:

// …
import HelloWorldTastic from './example/hello-world';
export const tastics = {
// …
'example/hello-world': HelloWorldTastic,
};
Clipboard icon

As soon as you save this change, the frontend will hot-reload and render the component:

73abd4f Frontastics rendered Frontastic component

Since this is a component without any configuration in studio, you should continue straight away to the creating a configurable component article.

Information icon

Once your component is finished, you'll need to use the environment selector to push your Frontend component to production so it can be used to build your pages.