After completing the Getting started with CMS guide, you can start adding and updating the component schemas that define what content editors can manage in the CMS Admin.

This guide covers the daily workflow for adding or changing a component, along with best practices for schema management.

Make sure you have completed all steps in the Getting started with CMS guide, including:

• VTEX IO CLI and Content plugin installed.
• CMS Admin app (vtex.admin-content-platform-ui) is installed in your account.
• CMS folder structure scaffolded in your storefront project (cms/{storeId}/components/ and cms/{storeId}/pages/).

The cycle you will repeat every time you add or change a component is:

1. Edit a .jsonc schema file in the cms/{storeId}/components/ directory.
2. Sync the schema to CMS using the CLI.
3. Verify the component appears correctly in the CMS Admin.

The following sections walk through each step in detail.

Open your store code in a code editor of your preference and create a .jsonc file inside the components/ folder. The filename must follow the pattern cms_component__{componentKey}.jsonc.

For example, to create a Hero Banner component in a FastStore project, create the file cms/faststore/components/cms_component__heroBanner.jsonc:

Each schema must include:

• $extends: References the base component definition.
• $componentKey: A unique identifier for the component.
• $componentTitle: The display name editors will see in the CMS Admin.
• properties: The fields editors can fill in, each with a type and title.

For the full schema reference, including all field types, available widgets, and how sections differ from components, refer to Understanding components and sections.

After saving your schema file, sync it to CMS. The command depends on your storefront technology.

Run the following command from the root of your FastStore project:

This command auto-detects the FastStore version from package.json, generates the schema, and uploads it in a single step.

Use the individual Content plugin commands:

Regardless of the command used, the CLI will:

1. Detect the content source and generate the schema.
2. Prompt you for the store ID to associate the schema with.
3. Show the current published version and suggest the next version number.
4. Ask you to confirm before uploading.

The CLI follows semantic versioning (major.minor.patch). When prompted, choose a version type based on the nature of your change:

Change type	Version bump	Example
New optional field or component added	Minor	1.5.0 → 1.6.0
Bug fix or small correction	Patch	1.5.0 → 1.5.1
Breaking change (removed or renamed field)	Major	1.5.0 → 2.0.0

Always review your schema before confirming the upload. If you release a new schema version that is not a pre-release (for example, 1.6.0 instead of 1.6.0-beta), it will replace the current production schema. To test changes without affecting production, append a pre-release tag such as -beta to the version (e.g., 1.6.0-beta.1).

After confirmation, the CLI uploads the schema and prompts you to delete the local schema.json file. This file is a generated artifact and does not need to be committed to your repository, so you can safely delete it or keep it for debugging purposes.

After syncing, do the following to check the new component:

1. Open the Admin and go to Storefront > Content > All Content.
2. Navigate to any page (for example, the Home page), and check the section picker. Your new component, in this case, Hero Banner, should appear as an available option with the fields you defined.

If the component does not appear, refer to the Troubleshooting CMS schema sync errors guide.

Adding a new optional field to an existing component is a safe, non-breaking change. Existing content entries simply won't have a value for the new field, and editors can populate it when needed.

Removing or renaming a field that already has saved content will break validation for those entries. Before removing a field, either clear the affected content first or deprecate the field by marking it as optional and hidden, then remove it in a future release once no content references it.

The default generate-schema command produces a delta schema that references the storefront base definitions. If something behaves unexpectedly, generate a fully inlined schema for inspection:

This output includes all inherited definitions resolved inline, making it easier to spot issues.

Since schema files define what data your frontend components receive, keep the cms/ folder in the same repository as your component source code (e.g., src/components/). A pull request that adds a new frontend component should include the corresponding schema file so both stay in sync through code review.

The upload-schema command prompts for confirmation by default. To skip the prompt in a CI/CD pipeline, pass the -y flag:

This is useful for automating schema deployments as part of your build and release process.