Local Components

Local components are React components provided by your application (the host site or app) that scheduled content code can use, rather than components fetched from the Visual Experience Engine.

---

Overview

There are two main ways to use local components:

1. Web: window.cmsDependencies – Provide React components from your site's bundle so scheduled content templates can reference them.
2. Web: Component metadata type – Select Components from the Visual Experience Engine Components section in scheduled content templates (Visual Experience Engine-managed but referenced locally in the template).

---

Web: Host-Provided Dependencies (window.cmsDependencies)

When the BILDIT web script interprets scheduled content code, it can resolve require() calls to components you provide. Your site exposes these before the BILDIT script loads by setting window.cmsDependencies.

How It Works

1. Set window.cmsDependencies on your page before loading the BILDIT script.
2. Each key is a module name (the string used in require()).
3. Each value is { module: YourReactComponent, globalName?: string }.
4. The web script merges cmsDependencies into its dependency config when interpreting scheduled content code.
5. When scheduled content code references that module name, it receives your component.

Setup

<!-- Your site's HTML - before the BILDIT script -->
<script>
  window.cmsDependencies = {
    MyCustomButton: {
      module: MyCustomButton,  // Your React component
      globalName: 'MyCustomButton'
    },
    SharedIcon: {
      module: IconComponent
    }
  };
</script>
<script src="https://bildit-cdn.bilditon.com/cms-client/bildit.min.js"></script>

For a framework like Next.js or React:

// In your _app.js, layout, or equivalent - before BILDIT loads
import MyCustomButton from '@/components/MyCustomButton'
import SharedIcon from '@/components/SharedIcon'

if (typeof window !== 'undefined') {
  window.cmsDependencies = {
    MyCustomButton: { module: MyCustomButton },
    SharedIcon: { module: SharedIcon }
  }
}

Using in Scheduled Content Templates

In a scheduled content template (Templates), reference the module by the same key:

// Banner template uses require-style resolution
const MyButton = require('MyCustomButton').default || require('MyCustomButton')

const Banner = () => (
  <div>
    <MyButton label="Shop Now" />
  </div>
)

export default Banner

Scheduled content code is compiled to UMD/AMD format. The dependency array in the compiled output is resolved using cmsDependencies. The key in cmsDependencies must match the dependency name in the compiled code. The web script merges cmsDependencies into its dependency config when interpreting scheduled content code.

---

Using Next.js and Other Libraries in cmsDependencies

The web script includes built-in stubs for next/link and next/image so scheduled content templates can use them even when the host site does not provide them. For plain <a> behavior and basic <img>, the stubs are sufficient.

To use the real Next.js components (client-side navigation, image optimization, etc.), expose them via window.cmsDependencies. Your entries override the built-in stubs.

Next.js Link

Provide the real Link component so scheduled content gets client-side routing:

// In your Next.js _app.js, layout.tsx, or equivalent - before BILDIT loads
import Link from 'next/link'

if (typeof window !== 'undefined') {
  window.cmsDependencies = {
    ...window.cmsDependencies,
    'next/link': { module: Link },
  }
}

Scheduled content templates that import next/link will now use your Link component. Prefetching, shallow routing, and other Next.js Link behavior will work as expected.

Next.js Image

Provide the real Image component for optimized images:

import Image from 'next/image'

if (typeof window !== 'undefined') {
  window.cmsDependencies = {
    ...window.cmsDependencies,
    'next/image': { module: Image },
  }
}

Combining Multiple Dependencies

Merge your dependencies with any existing ones (e.g. from other scripts):

// Next.js App Router (app/layout.tsx or similar)
import Link from 'next/link'
import Image from 'next/image'
import MyCustomButton from '@/components/MyCustomButton'

if (typeof window !== 'undefined') {
  window.cmsDependencies = {
    ...(window.cmsDependencies || {}),
    'next/link': { module: Link },
    'next/image': { module: Image },
    MyCustomButton: { module: MyCustomButton },
  }
}

Other Libraries

The same pattern works for any library your scheduled content templates reference. The key must match the module specifier used in the compiled scheduled content code (e.g. next/link, react, @/components/Button). Common examples:

Key	Purpose
next/link	Client-side navigation
next/image	Optimized images
react	React (usually already provided by the script)
Custom key	Your own components

Fallback When Not Provided

If you do not provide next/link or next/image, the web script uses minimal stubs:

• next/link – Renders as <a href={href}> (no client-side routing)
• next/image – Renders as <img src={src}> (no optimization)

---

Scheduling Local Components

You can schedule which components are exported from cmsDependencies by computing the value based on the current date, campaign, or other criteria. The same scheduled content template can then receive different components depending on when the page loads.

How It Works

The web script reads window.cmsDependencies when each scheduled content item renders. By setting it before the BILDIT script loads (or before the relevant scheduled content mounts), you control which components are available. Compute the value based on your schedule and assign the result to window.cmsDependencies.

Best Practices

• Set before BILDIT loads – For the most reliable behavior, populate cmsDependencies before the BILDIT script runs.
• Stable keys – Use the same dependency key (e.g. SeasonalCTA) in both your schedule logic and the scheduled content template; only the module you assign changes.
• Fallbacks – Always provide a default component so scheduled content never references a missing dependency.

---

Web: Component Metadata Type (Visual Experience Engine Components)

Scheduled content templates can declare metadata of type Component to let editors choose a Component from the Visual Experience Engine Components section. The selected component's compiled code is inlined when the scheduled content is saved.

In the Template

// @type=Component
// @placeholder='Select a component'
const Footer = $(Footer:Component);

const Banner = () => (
  <div>
    <Footer />
  </div>
);

export default Banner;

• $(Footer:Component) – Declares a slot named Footer of type Component.
• The Visual Experience Engine form for scheduled content shows a Select component dropdown populated from the app's Components.
• The chosen component's compiled code is evaluated and inlined into the scheduled content at save time.

Restrictions

• Components must exist in the Components section of the Visual Experience Engine.
• Only one platform target is used for web; Components are typically configured for web if they're used in web scheduled content.
• The replace-template-values logic skips Component-type metadata during client-side interpretation (it's resolved server-side when the scheduled content is saved).

---

Web: Base Component (HOC)

A Component in the Visual Experience Engine with isConfigTemplate: true is the default HOC for web scheduled content. It is fetched via the remote-baseComponent API.

• API: GET /remote-baseComponent?key=YOUR_API_KEY
• Returns: Raw JSX code of the HOC (transpiled for web).
• Purpose: Wrap all dynamically loaded scheduled content components with shared behavior (e.g. analytics, theming, error boundaries).

Configuration is done in the Visual Experience Engine by marking the appropriate Component with the Default switch in templates.

---

Mobile: Components from Visual Experience Engine

On mobile, components are always loaded from the Visual Experience Engine via the remote-component API. There is no window.cmsDependencies equivalent. To reuse app-side code:

• Publish it as a Component in the Visual Experience Engine, or
• Bundle it in your app and reference it through whatever module system your app uses for non-Visual Experience Engine screens.

---

Summary

Context	Mechanism	Purpose
Web – host site	window.cmsDependencies	Use your site's React components inside scheduled content templates
Web – Visual Experience Engine	$(name:Component) metadata	Let editors pick Components from the Visual Experience Engine to embed in scheduled content
Web – default wrapper	isConfigTemplate Component	HOC that wraps all web scheduled content
Mobile	remote-component API	Load components from the Visual Experience Engine; no host-provided local components

---

Key Takeaway

Local components in BILDIT refer mainly to web: set window.cmsDependencies before loading the script to expose your components to scheduled content code. For Visual Experience Engine-managed components, use the Component metadata type in templates and choose from the Components section when editing scheduled content.