Creating a Frontastic component

Quick start guide to working with Frontastic components.

👍

Prerequisites

  • GitHub customer repositoryGitHub customer repository - Where your code lives in GitHub for all your projects, you can have many project folders within your customer repository. access
  • Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. access
  • Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. running

A Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. consists of 2 parts:

  1. A schema to make it known to Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.
  2. A React component as its code entry point

The schema is uploaded to Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. 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 Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`..

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

This should be saved as in packages/<project>/frontend/frontastic/tastics/example/hello-world/schema.json.

👍

Tip

A schema file should always be saved as schema.json within its own directory.

Upload the component schema

You'll then need to upload your schema to the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. To do this, open your Frontastic studio and follow the steps below:

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

❗️

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

  1. Click the add icon, and select your Frontastic component schema file (you can also drag the schema file into your browser)

Place the component on a page

Once the component has been added to the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`., you'll need to check it works on a page so you'll need to create a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code..

  1. Switch to Site builder, click New, then select Create page folder
  1. Input a page folder name and click Save

👍

Tip

To keep structure to the page folders we recommend creating a top-level page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. 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 folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code.. 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 versionpage version - A page can have multiple versions and in different states within a page folder, such as draft, scheduled, live, and so on. within your page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. that'll contain your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code..

  1. Select your new page folder, then click New, select Create page version
  1. 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.

  1. Click the blue add icon on any of the sections (for example, MAIN), then select a layout element
  1. Search for the name of the Frontastic component you've just created and drag it into your layout element, then click Save
  1. Click the more icon on your page version, then click Make default

Implement and register the code

On the Frontastic CLIFrontastic CLI - Our Commandline Interface (CLI) that you can use for frontend development. 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 componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. 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 Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`., you should continue straight away to the creating a configurable Frontastic component article.

📘

Once your component is finished, you'll need to use the environment selector to push your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. to production so it can be used to build your pages.


Did this page help you?