Creating a Frontend component
Prerequisites
- GitHub customer repository access
- studio access
- CLI running
A Frontend component consists of 2 parts:
- A schema to make it known to the studio
- 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": []}
Copy this code example, and we'll paste it into the studio in the next section.
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:
- 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.
- Click the Create schema button, this will open the schema editor
- Paste the JSON into the schema editor from the previous section, then click Validate and preview, then Publish and download JSON
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.
- Switch to Site builder, click New, then select Create page folder
- Input a page folder name and click Save
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.
- Select your new page folder, then click New, select Create page version
- Input a page name for your page version, and click Save
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
.
- Click the blue add icon on any of the sections (for example, MAIN), then select a layout element
- Search for the name of the Frontend component you've just created and drag it into your layout element, then click Save
- Click the more icon on your page version, then click 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:
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 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,};
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 Frontend component to production so it can be used to build your pages.