Creating a Frontastic component

👍

Prerequisites

• GitHub customer repository access
• Frontastic studio access
• Frontastic CLI running

A Frontastic 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 React components are mounted by the Frontastic renderer 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 Frontastic 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": []
}

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

👍

Tip

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

❗️

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

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

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

👍

Tip

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

2. Input a page folder name and click Save

👍

Tip

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 Frontastic component.

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

4. Input a page name for your page version, and click Save

👍

Tip

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.

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

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

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

Implement and register the code

On the Frontastic 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 Frontastic component with Frontastic's attempt to render it:

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;

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 teach the Frontastic 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,
};

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

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

📘

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