Creating a new section in the CMS

This guide applies only to stores using the CMS with FastStore versions 3 or 4. For stores using Headless CMS (legacy), please refer to this guide.

When your store requires a layout or behavior not natively available, you can create a new section component tailored to your brand or business rules. A section component gives you full control over the structure and content while integrating with the CMS.

In this guide, you'll learn how to create a new CallToAction section in your FastStore project.

A section is a type of component that contains other components and acts as a dynamic container in page layouts. For more details, see Understanding Components and Sections.

• The CMS must be installed and enabled in your VTEX account. The CMS provides the Admin interface to configure and publish the CallToAction section you built in this guide.

• The Content plugin must be installed on your machine.

1. Open your store project in a code editor.

2. In the folder src/components, create the CallToAction.tsx file.

3. Add the following code to the CallToAction.tsx file:

   
   

   _20

   import React from "react";

   _20

   _20

   export interface CallToActionProps {

   _20

   title: string;

   _20

   link: {

   _20

   text: string;

   _20

   url: string;

   _20

   };

   _20

   }

   _20

   _20

   export default function CallToAction(props: CallToActionProps) {

   _20

   return (

   _20

   <section>

   _20

   <h2>{props.title}</h2>

   _20

   <a href={props.link.url}>{props.link.text}</a>

   _20

   </section>

   _20

   );

   _20

   }

   _20

   _20

   CallToAction.$componentKey = 'CallToAction';

   
   

4. Export the CallToAction component in the index.tsx file.

   
   

   _10

   …

   _10

   import CallToAction from './CallToAction'

   _10

   _10

   export default {

   _10

   …

   _10

   CallToAction

   _10

   }

   
   

5. Create the file for the component that will be a section. In cms/faststore/components, create the cms_component__CallToAction.jsonc file.

6. In the cms_component__CallToAction.jsonc file, add the following:

   
   

   _38

   {

   _38

   "$extends": [

   _38

   "#/$defs/base-component"

   _38

   ],

   _38

   "$componentKey": "CallToAction",

   _38

   "$componentTitle": "Call To Action",

   _38

   "title": "Call To Action",

   _38

   "description": "Get your 20% off on the first purchase!",

   _38

   "type": "object",

   _38

   "required": [

   _38

   "title",

   _38

   "link"

   _38

   ],

   _38

   "properties": {

   _38

   "title": {

   _38

   "title": "Title",

   _38

   "type": "string"

   _38

   },

   _38

   "link": {

   _38

   "title": "Link Path",

   _38

   "type": "object",

   _38

   "required": [

   _38

   "text",

   _38

   "url"

   _38

   ],

   _38

   "properties": {

   _38

   "text": {

   _38

   "title": "Text",

   _38

   "type": "string"

   _38

   },

   _38

   "url": {

   _38

   "title": "URL",

   _38

   "type": "string"

   _38

   }

   _38

   }

   _38

   }

   _38

   }

   _38

   }

   
   

Before syncing your changes with the CMS, run the storefront locally to confirm your new component compiles without errors. This catches typos, missing imports, and invalid schemas before you sync with the CMS.

1. In the project root, start the FastStore development server:

   
   

   _10

   yarn dev

   
   

2. Open the development server in your browser and check the terminal output for compilation errors related to CallToAction.

The section won't render visually yet because it hasn't been added to any page in the CMS. This is done in Step 4. At this point, you're only verifying that the development server starts and that your component code, schema, and registration are valid.

If the development server starts successfully and reports no compilation errors, you're ready to sync your changes with the CMS.

Before syncing, make sure you're logged in to your VTEX account by running in the terminal the vtex login {accountName} command. Change the {accountName} to your store account, for example, vtex login mystore.

From the root of your FastStore project, run:

This single command detects your store's content source, generates the schema from your cms/faststore/components and cms/faststore/pages folders, and uploads it to the CMS — prompting you to confirm the store ID and the schema version before publishing.

Available from FastStore v4.4.0. Stores on earlier versions must upgrade first. See Local setup and development for details on the version prompt and best practices for choosing a version number.

Syncing manually

If you prefer to run each step separately, for example, to preview the generated schema before uploading, or to automate the upload in a CI/CD pipeline, use the individual Content plugin commands instead:

1. Generate the schema:

   
   

   _10

   vtex content generate-schema cms/faststore/components cms/faststore/pages -o cms/faststore/schema.json

   
   

2. Open the schema.json file and check if the section was added to the section list. It should look similar to this:

   
   

   _10

   …

   _10

   {

   _10

   "$ref": "#/components/CallToAction"

   _10

   }

   _10

   …

   
   

3. Upload the schema:

   
   

   _10

   vtex content upload-schema cms/faststore/schema.json

   
   

1. In the Admin, open Storefront > Content, and click an Entry, such as Home, to check whether the component was added.

   

2. Add the component and complete its fields.

3. Click Save.

4. With the FastStore development server still running from Step 2, refresh to preview the CallToAction section rendered with the values you just configured.