Getting Started with Flex Components#

Each Flex Component is defined by a flex.json file, which acts as the blueprint for the component’s structure, behavior, and configuration in Miva’s Page Builder system.

This file controls:

How your component is rendered and categorized
What inputs users configure in the Admin
Which templates, scripts, and styles are used
What assets are copied to the store during import

Folder Structure#

Your component folder should follow this convention:

my-component/
├── flex.json
├── src/
│   ├── templates/
│   │   ├── init.mvt
│   │   └── instance.mvt
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   └── script.js
│   └── images/
│       └── placeholder.jpg

flex.json must be at the top level of the archive when packaging.

Sample `flex.json`#

{
  "code": "example-hero",
  "name": "Example: Hero Banner",
  "type": "component",
  "managed": false,
  "version": "1.0.0",
  "resourcegroup_code": "example-hero",
  "category": "image-text",
  "initialization_template": "src/templates/init.mvt",
  "instance_template": "src/templates/instance.mvt",
  "scripts": [
    {
      "filepath": "src/js/script.js",
      "resource_code": "example-hero"
    }
  ],
  "styles": [
    {
      "filepath": "src/css/styles.css",
      "resource_code": "example-hero"
    }
  ],
  "properties": [
    {
      "code": "headline",
      "prompt": "Headline Text",
      "type": "text"
    },
    {
      "code": "image",
      "prompt": "Main Image",
      "type": "image"
    }
  ],
  "advanced_properties": [
    {
      "code": "color",
      "prompt": "Background Color",
      "type": "color"
    }
  ],
  "defaults": {
    "headline": {
      "value": "Welcome to Our Store"
    },
    "advanced": {
      "color": {
        "value": "#ffffff"
      }
    }
  },
  "images": [
    {
      "source_filepath": "src/images/placeholder.jpg",
      "destination_filepath": "graphics/%STORE_ID%/hero.jpg"
    }
  ],
  "depends": {
    "mmx-base": "=10.11.03",
    "mmx-button": "=10.11.03",
    "mmx-hero": "=10.11.03",
    "mmx-text": "=10.11.03"
  },
  "sample_data_types": [
    {
      "type": "product",
      "conditions": {}
    },
    {
      "type": "category",
      "conditions": {
        "category_code": "featured"
      }
    }
  ]
}

Required Fields#

Field	Description
`code`	Unique identifier for the component (used as namespace and in Page Builder metadata)
`name`	Display name in Page Builder
`type`	`"component"` for user-facing UI elements and `"library"` for non user-facing
`managed`	Boolean; if `true`, the component is read-only in Page Builder
`version`	Semantic version (e.g., `1.0.0`)
`resourcegroup_code`	Used to associate scripts/styles with a named group
`instance_template`	Path to the `.mvt` file rendered for each instance
`properties`	An array of user-editable inputs shown in the Page Builder interface

Optional Fields#

Field	Description
`initialization_template`	Template rendered once per page load for shared styles/scripts
`scripts`	JavaScript resource(s) to load; each object includes `filepath`, `resource_code`, and optional attributes
`styles`	CSS resource(s) to load; each object includes `filepath`, `resource_code`, and optional attributes
`category`	Used for grouping in Page Builder (`banner`, `carousel`, `text`, `product`, `image`, `video`, `utility`, `navigation`, etc.)
`advanced_properties`	Properties shown under the “Advanced” tab in the UI
`defaults`	Default values for `properties` and `advanced_properties`, using the same `code` structure
`images`	Array of file references to be copied to the store filesystem during install
`depends`	Array of Flex Component codes and versions this component depends on (for component chaining or extensions)
`sample_data_types`	Determines when and how Miva displays sample/mock data in Page Builder for the component

Scripts and Styles#

You can define multiple script and style files. Miva will automatically output them if used in the component.

"scripts": [
  {
    "filepath": "src/js/script.js",
    "resource_code": "example-hero",
    "attributes": [
      { "name": "type", "value": "module" }
    ]
  }
],
"styles": [
  {
    "filepath": "src/css/styles.css",
    "resource_code": "example-hero"
  }
]

Images#

The images field defines which assets will be copied to the store on import.

Field Reference#

Field	Description
`source_filepath`	Relative to root of the Flex Component archive
`destination_filepath`	Destination path on the store, typically `graphics/%STORE_ID%/...`

Example

"images": [
  {
    "source_filepath": "src/images/placeholder.jpg",
    "destination_filepath": "graphics/%STORE_ID%/hero.jpg"
  }
]

Use these values in your component’s property defaults:

"defaults": {
  "image": {
    "value": "graphics/%STORE_ID%/hero.jpg"
  }
}

Component Dependencies#

Flex Components can optionally declare dependencies on other components.

"depends": [
  { "code": "mmx-carousel-core", "version": "1.2.0" }
]

This is used to require another component be present and up to date — often helpful when using a shared base component (like MMX Core modules).

PageBuilder Preview Fields#

Use preview_component_selector to improve real-time visual editing when using the PageBuilder Inspector tool. The setting identifies the root DOM element of your Flex Component during preview. This is crucial when using the PageBuilder inspector tool.

Example:

"preview_component_selector": "[data-component='%component_code%']"

Available Tokens#

Token	Description
`%component_code%`	Replaced with the `code` from your component
`%sequence_item_code%`	Replaced with the PageBuilder sequence code
`%element_code%`	Optional; used for field-level targeting

Sample Data Types#

The sample_data_types array allows you to control whether Miva will prepopulate a component with sample data when used in PageBuilder, based on the data context.

Example

"sample_data_types": [
  {
    "type": "product",
    "conditions": {}
  },
  {
    "type": "category",
    "conditions": {
      "category_code": "featured"
    }
  }
]

Supported Types#

product
category
order
payment
search

Why Use It?

Helps designers and admins see how the layout behaves without needing to assign real data first
Useful for default template testing and placeholder logic

Versioning Notes#

The version field is required and must follow semver formatting.
Updates to version allow admin to see whether a newer version of a component is available (especially important for managed components or versioned imports).

Best Practices#

Use consistent naming across code, resourcegroup_code, and filenames.
Include only relevant files in your .tar.bz2.
Do not include dev-only files (e.g., .git, .DS_Store, node_modules).
Use sample_data_types to improve design-time previewing for empty sequences.