SfSkills Domains Docs GitHub

Home / admin / lightning-bolt-template-authoring

lightning-bolt-template-authoring

Use when an admin or partner needs to package an Experience Cloud (Community) site as a reusable Lightning Bolt Solution for distribution — covers the export workflow from Experience Builder, what gets bundled (ExperienceBundle, custom apps, flow categories, theme, layouts, navigation menus) versus what does NOT (data, CMS content, files), choosing Bolt vs managed package vs unlocked package vs cloning a site, sandbox-to-production promotion, multi-org distribution, AppExchange listing as a Bolt, and template versioning via the LightningBolt metadata `versionNumber`.

Open the skill folder on GitHub

Lightning Bolt Template Authoring

Activate this skill when an Experience Cloud site needs to leave its origin org. A Lightning Bolt is the platform-native way to package an Experience site (ExperienceBundle + theme + supporting metadata) as a template that other orgs or other Experience sites within the same org can stamp out. The skill is about packaging — it is not about building the site itself, nor about distributing CRM functionality (use a managed or unlocked package for that).

Before Starting

Gather this context before scaffolding a Bolt:

Core Concepts

Concept 1 — Bolt vs managed package vs unlocked package vs site clone

Four distribution shapes, four different problem domains. Pick by what is being distributed, not by familiarity:

ShapeDistributesWhen to useSalesforce reference
Lightning Bolt SolutionAn Experience site as a template — the ExperienceBundle (pages, components, layouts, navigation menus), theme, listed flow categories, custom apps, images. NO data, NO CRM functionality.The deliverable is a brandable, configurable Experience site that the target org will instantiate and customize further. Industry-specific community starters, partner-portal templates, branded community kits.LightningBolt metadata; Build a Lightning Bolt Solution guide.
Managed (2GP) packageApex / LWC / Aura / custom objects / fields / permission sets / Flow definitions / data model. Versioned with upgrade path. Optional security review for AppExchange.The deliverable is behavior (an ISV product, a managed extension). Owner retains code; subscriber installs and upgrades.Package2 metadata; 2GP developer guide.
Unlocked packageSame metadata coverage as managed but unlocked — subscriber org owns and can edit installed components. Versioned with upgrade path but not security-reviewed.Internal multi-org reuse where you want package versioning but the subscriber needs to be able to modify. Good for shared cross-BU CRM extensions.Package2 metadata, IsOrgDependent, Container-style scratch org build.
Site clone (in-org only)An Experience site copied to a new site within the same org.One-off reuse within a single org. No need to leave the org boundary.Setup → All Sites → New → Use existing site as template.

A common mistake is reaching for a managed package because that is what the partner team is familiar with. If the deliverable is the look and feel and starting structure of a community site, a Bolt is the right tool — and shipping it as a managed package would force the subscriber into the upgrade-path constraints (no metadata edits without unlocking) that work against site customization, which is the entire point of a template.

A second common mistake is using a Bolt to distribute Apex or a custom object dependency. Bolts cannot carry Apex / custom objects / fields. If the site needs them, the dependency must ship separately. The pattern is: Bolt for the site shape, managed (or unlocked) package for the behavior dependencies, with Bolt installation gated on the package being installed first.

Concept 2 — What is actually inside a Bolt

The LightningBolt metadata definition itself is small — it points at the artifacts that constitute the bundle. The complete inventory:

What is not inside a Bolt:

Concept 3 — Export workflow (Experience Builder → ExperienceBundle → LightningBolt)

The export is two phases. Phase 1 produces the ExperienceBundle. Phase 2 wraps it in LightningBolt metadata and builds the package.

Phase 1 — Export from Experience Builder:

  1. Open the source site in Experience Builder.
  2. From the Settings panel → Developer → "Export as a Template."
  3. Provide a template name, description, summary, image, category (mapped from the industries field).
  4. Salesforce extracts the ExperienceBundle, theme, branding, navigation, and any referenced flow categories / custom apps and stores them as a template in the source org's New Site dialog. At this point the template is reusable inside the same org but has not left.

Phase 2 — Wrap as a LightningBolt and package for distribution:

  1. Retrieve the LightningBolt and ExperienceBundle metadata via SFDX (sf project retrieve start --metadata LightningBolt:<name> and the corresponding ExperienceBundle).
  2. Edit LightningBolt-meta.xml to set description, summary, industries, flowCategories, images, templateApi, versionNumber.
  3. To distribute internally: deploy the metadata bundle to the target org via change set, SFDX, or unmanaged package. The Bolt then appears in Setup → All Sites → New → Use as a template.
  4. To distribute via AppExchange: log into the partner Business Org, create an AppExchange Bolt listing (separate flow from a managed-package listing), and submit. The listing flow is documented in the partner Salesforce community.

The "Export as a Template" UI step does the heavy lifting of converting an in-org site into a reusable template. The LightningBolt metadata wrap is what lets you ship that template out of the org. Skipping Phase 2 leaves the template inside the source org only.

Concept 4 — Versioning, upgrades, and the fork model

LightningBolt.versionNumber is a string field for human-readable version labeling ("1.0", "2.3", etc.). It does not establish an upgrade relationship between Bolt versions in the way a managed package does.

Concretely:

This is fine for templates intended as starting points — partner portal kits, industry community starters. It is the wrong shape for operationally-shared sites where downstream changes must propagate. For the latter case, a managed package containing a custom Lightning page reference (and treating the Experience site itself as a thin wrapper) is closer to what you want.

versionNumber is still worth setting accurately because:

  1. Confirm Bolt is the right shape. Walk through Core Concept 1 with the requester. If the deliverable is "a starting community site," continue. If it is "behavior" (Apex, custom objects), pivot to devops/managed-package-development or devops/unlocked-package-development. If it is "this single site, copied to one other org," use devops/experience-cloud-deployment-admin instead.
  2. Inventory dependencies on the source site. Run scripts/check_lightning_bolt_template_authoring.py against the retrieved metadata of the source org. Confirm: ExperienceBundle exists; the listed flowCategories map to real Flow metadata; any custom apps / themes referenced are present; no Apex or custom objects the site relies on are missing from the package plan. Output a dependency map showing what needs to ship in the Bolt vs what needs to ship separately as a managed/unlocked package.
  3. Export the site as a template from Experience Builder (Settings → Developer → Export as a Template). Verify the template appears in Setup → All Sites → New → "Use existing template." This is the in-org checkpoint before adding the LightningBolt wrap.
  4. Author the LightningBolt metadata. Retrieve the auto-generated LightningBolt-meta.xml via SFDX, then fill in description, summary, industries, flowCategories (must match the Flow metadata categories shipped with the bundle), images, templateApi (must match the source site's runtime — webruntime for LWR, aura for Customer Service / Partner Central), and versionNumber.
  5. Promote sandbox → production for the source-of-truth Bolt. Deploy the LightningBolt + ExperienceBundle + Theme + Flow (any in the listed categories) + CustomApplication (any referenced) to the production org via change set or SFDX. Production is now the shipping origin. Confirm the Bolt appears in Setup → All Sites → New in production.
  6. Pick the distribution channel and ship. Three options: (a) deploy directly to each target org (multi-org internal); (b) wrap in an unmanaged or unlocked package and distribute the package artifact (multi-org with version artifacts); (c) submit as an AppExchange Bolt listing (external distribution). Document which channel is used in the change record so future updates follow the same path.
  7. Define the version policy. Document in the skill / handoff: what triggers a versionNumber bump, whether existing instantiations are expected to upgrade (no — they are forks), and how downstream orgs should track which version they installed. If downstream upgrades matter, layer a managed package on top for the parts that need true upgrade semantics.

Package files