Fluent Commerce Logo
Docs
Help & Feedback

What is a Blueprint?

Essential knowledge

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

20 Aug 2026

Overview

This guide covers the blueprint lifecycle, from design to management, teaching you to deploy pre-configured module collections using the Fluent CLI. Implementing partners gain a consistent, repeatable setup across environments, while businesses benefit from faster deployments and reduced downtime via automated conflict prevention.Key features include Smart Versioning for automatic upgrades and Snapshot Mode for development testing. Note: Production requires exact versions; semver ranges are prohibited to ensure stability.

Key points

  • Accelerator Blueprints: JSON manifest files acting as "recipes" to rapidly deploy pre-configured collections of modules to Fluent Commerce accounts.
  • Core Functions: Enables version-controlled installations, rapid environment setup, and automated conflict management.
  • Module Types: Supports official "Reference" shorthand (core, order, etc.), "Namespaced" organizational modules, and "Custom" modules via S3/HTTPS/Local paths.
  • Snapshot Mode: Specific for development; allows automatic resolution of 4-part build numbers or SNAPSHOT versions for latest-build testing.
  • Smart Deployment: Installation logic automatically handles upgrades and resumes interrupted sessions by skipping identical versions unless --force is used.
  • Lifecycle: Follows a clear path: Design → Validate → Config → Install → Manage.
  • Best Practice Supports official "Reference" shorthand (core, order, etc.), "Name-spaced" organizational modules, and "Custom" modules via S3/HTTPS/Local paths.
An accelerator blueprint is a JSON manifest file that defines a complete, pre-configured collection of modules.Blueprints enable: 
  • Rapid deployment of pre-tested module combinations 
  • Consistent configurations across environments 
  • Version-controlled module installations
  • Conflict management to prevent incompatible module combinations
Think of a blueprint as a "recipe" for setting up a Fluent Commerce account with specific capabilities.A blueprint JSON file contains:

Core Metadata

  • `name` - Blueprint identifier (e.g., "retail-accelerator")
  • `version` - Semantic version (e.g., "1.0.0")
  • `description` - Human-readable description
  • `created` - Creation timestamp (ISO 8601)
  • `updated` - Last update timestamp (optional)

Module Definitions

Array of modules to install, each with: 
  • `name` - Module name, can be: 
    • Reference module shorthand: `"core"`, `"order"`, `"inventory"`, `"fulfilment"` 
    • Fully qualified name: `"fluent-commerce/acme/acme-module-xyz"` 
    • Custom module name: `"my-custom-module"` 
  • `version` - Specific version to install (e.g., "2.5.0") 
  • `modulePath` - (Optional) Custom path to module artifact 
  • `includes` - (Optional) Specific assets to include 
  • `excludes` - (Optional) Specific assets to exclude 
  • `snapshot` - (Optional) Boolean flag to enable snapshot/build version resolution using 4-part versions (default: `false`)

Conflict Management

Array of conflict definitions to prevent incompatible installations: 
  • `name` - Conflicting module/blueprint name 
  • `type` - Either "module" or "blueprint" 
  • `version` - Version constraint (supports semver ranges) 
  • `reason` - Human-readable explanation

Additional Metadata

  • `authors` - Array of author information
  • `type` - Blueprint classification
  • `tags` - Searchable labels
For development and testing workflows, blueprints support automatic resolution of snapshot and build versions using the `snapshot` flag.

When to Use Snapshot Mode

Use the `snapshot` flag when: 
  • Working with development versions marked as `SNAPSHOT` 
  • Testing release candidate (RC) builds that use 4-part version build numbers (e.g., `2.5.0.1`, `2.5.0.25`) 
  • Need to always use the latest build for a specific base version 
  • Want automatic updates to the newest development version without changing the blueprint.

How Snapshot Resolution Works

When `snapshot: true` is set on a module:
  • Base Version Required: Specify exact base version (e.g., `"2.5.0"`)
  • S3 Modules Only: Only works for modules with `modulePath` starting with `s3://`
  • Resolution Priority: 
    • First: Looks for `{version}-SNAPSHOT` (case insensitive) 
    • Second: Finds latest `{version}.XXX` by build number (4th identifier) 
    • Never: Does NOT match the exact release version `{version}`

Example Usage

`{`
 "name": "development-accelerator",
 "version": "1.0.0",
 "modules": [
   {
     "name": "acme/custom-order-module",
     "version": "2.5.0",
     "modulePath": "s3://my-bucket/modules/",
     "snapshot": `true
`   }
 ]
}
Behaviour: 
  • If location contains: `acme-custom-order-module-2.5.0-SNAPSHOT.zip` → Uses SNAPSHOT version - If location contains: `acme-custom-order-module-2.5.0.125.zip`, `acme-custom-order-module-2.5.0.100.zip` → Uses 2.5.0.125 (highest) 
  • If location contains only: `acme-custom-order-module-2.5.0.zip` → Fails (release version not used in snapshot mode) 
  • If `snapshot: false` or omitted: Downloads exactly `acme-custom-order-module-2.5.0.zip`

Important Notes

  • Development Only: Snapshot mode is intended for development/testing, not production
  • Exact Base Version: The `version` field must be an exact version (e.g., `"2.5.0"`), not a range
  • Path Required: Works with S3 paths (`s3://bucket/path/`) or file system paths (`/local/modules/`)
  • Build Numbers: Use 4-part version format where 4th number is the build number (e.g., `2.5.0.1`, `2.5.0.25`)
  • Case Insensitive: SNAPSHOT matching is case-insensitive (`-SNAPSHOT`, `-snapshot`, `-Snapshot` all work)
Blueprints support three types of modules, each with different naming conventions and download behaviours.

Reference Modules

Fluent Commerce provides reference modules that can be specified using shorthand names in blueprints. These are core platform modules maintained by Fluent Commerce.

Supported Reference Modules

ShorthandDownloads AsFull Name
`core``fc-module-core-{version}.zip``fluent-commerce/core`
`order``fc-module-order-{version}.zip``fluent-commerce/order`
`inventory``fc-module-inventory-{version}.zip``fluent-commerce/inventory`
`fulfilment``fc-module-fulfilment-{version}.zip``fluent-commerce/fulfilment`

Example Usage

`{`
 "name": "platform-essentials",
 "version": "1.0.0",
 "modules": [
   {
     "name": "core",
     "version": "2.2.1"
   },
   {
     "name": "order",
     "version": "2.5.2"
   },
   {
     "name": "inventory",
     "version": "1.8.3"
   }
 ]
}

Download Behaviour

Reference modules are automatically downloaded from Fluent Commerce's official repository:
`https://downloads.fluentcommerce.com/v1.0.0/modules/fluent-commerce/{name}/{version}`
Example: - Blueprint specifies: `"name": "core", "version": "2.2.1"` - CLI downloads from: `https://downloads.fluentcommerce.com/v1.0.0/modules/fluent-commerce/core/2.2.1` - Saved as: `fc-module-core-2.2.1.zip`

Important Notes

  • CLI Maintenance: The list of reference modules is maintained in the CLI codebase as a constant array
  • No Auto-Discovery: New reference modules require a CLI update to be supported
  • Shorthand Only: Reference modules must use shorthand names (e.g., `"core"`, not `"fluent-commerce/core"`)
  • Version Support: Supports exact versions (e.g., `"2.2.1"`) or `"latest"` keyword

Name-spaced Modules

Name-spaced modules are saved with sanitised names: - Blueprint: hierarchical naming. These use fully qualified names with organisational prefixes (e.g., `acme/`, `mycompany/extensions/`).

Example Usage

`{`
 "modules": [
   {
     "name": "acme/custom-order-module",
     "version": "2.5.2"
   },
   {
     "name": "mycompany/payment-extension",
     "version": "1.8.0"
   }
 ]
}

File Naming

Namespaced modules are saved with sanitised names: - Blueprint: `"acme/custom-order-module"` - Saved as: `acme-custom-order-module-2.5.2.zip` - Pattern: Replace `/` and `\` with `-`

Custom Modules

Custom modules are third-party or organisation-specific modules. These require explicit `modulePath` definitions.

Example Usage

`{`
 "modules": [
   {
     "name": "my-custom-module",
     "version": "1.0.0",
     "modulePath": "https://example.com/modules/my-custom-module-1.0.0.zip"
   },
   {
     "name": "internal-module",
     "version": "2.1.0",
     "modulePath": "s3://my-bucket/modules/internal-module-2.1.0.zip"
   }
 ]
}

Supported Module Paths

  • HTTPS: `https://example.com/path/to/module.zip`
  • S3: `s3://bucket-name/path/to/module.zip`
  • Local file: `/absolute/path/to/module.zip`
  • Local folder: `/path/to/modules/` (CLI constructs filename from name + version)

1. Design Phase

Create blueprint JSON file defining: - Required modules and versions - Module filters (includes/excludes) - Conflict rules

2. Validation Phase

Use `blueprint validate` to: - Validate blueprint structure and business rules - Check semantic versioning constraints - Verify module paths and URLsUse `blueprint describe` to: - Preview module list - Check metadata - Review conflicts

3. Configuration Phase

Use `blueprint config` to: - Generate module config files - Customise per-environment settings - Prepare for installation

4. Installation Phase

Use `blueprint install` to: - Install all modules sequentially - Handle conflicts and duplicates - Track installation progress

5. Management Phase

Use `blueprint list` to: - View installed blueprints - Track module inventory - Plan upgrades

Smart Version Comparison

Installation intelligently compares module versions using semantic versioning: - Upgrades: Automatically installs newer versions without `--force` - Same Version: Skips already-installed modules (use `--force` to reinstall) - Downgrades: Blocks older versions (requires explicit `--force` for safety)This enables efficient blueprint updates - only changed modules are reinstalled.

Smart Resume

If installation is interrupted: 
  • Re-run the same command 
  • Already-installed modules are automatically skipped based on version 
  • Installation continues from where it left off 
  • Use `--force` to reinstall all modules regardless of version

Selective Module Installation

Install specific modules or exclude modules using CLI flags: 
  • `--include "module1,module2"`: Install only specified modules from blueprint 
  • `--exclude "module1,module2"`: Install all modules except specified ones 
  • Cannot use both --include and --exclude together 
  • Follows same pattern as `module install` command
Use cases: 
  • Incremental rollout (install modules one at a time) 
  • Testing specific modules before full deployment 
  • Excluding test/demo modules in production 
  • Debugging problematic modules

Conflict Prevention

Blueprints define conflicts to prevent: 
  • Incompatible module versions 
  • Deprecated module installations 
  • Duplicate functionality 
  • Breaking configuration changes

Version Control

Module versions must be exact (no ranges allowed): Exact: `"2.5.0"` - Install exactly version 2.5.0 (allowed)

Conflict Versions

  • Exact: `"2.5.0"` - Install exactly version 2.5.0 (allowed)
  • Latest: `"latest"` - Install newest available version (allowed)
  • Ranges NOT allowed: `"^2.5.0"`, `"~2.5.0"`, `">=2.5.0"` (not allowed)

Selective Installation

Control which module assets are installed: 
  • Include filters: Only install specified assets 
  • Exclude filters: Skip specified assets 
  • Per-module control: Different filters for each module
CommandPurposeAuthentication Required
`blueprint create`Create blueprint templateNo
`blueprint validate`Validate blueprint fileNo
`blueprint list`Show installed blueprintsYes (account)
`blueprint describe`Preview blueprint detailsNo
`blueprint download`Download module archivesNo
`blueprint config`Generate module configsYes (retailer)
`blueprint install`Install all modulesYes (retailer)

New Environment Setup

`# 1. Describe blueprint to verify contents
`fluent blueprint describe accelerator.json

`# 2. Generate config files for modules
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01

`# 3. Review and customise generated configs
`ls -la *.json

`# 4. Install all modules
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01

Resume Interrupted Installation

`# Installation failed on module 5 of 10
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01

`# Re-run same command - modules 1-4 are skipped, resumes from module 5
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01

Force Reinstall

`# Reinstall all modules, even if already installed
`fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --force

Check What's Installed

`# List all blueprints in account
`fluent blueprint list -p myprofile

Blueprint Design

  • Use specific versions for production blueprints
  • Document conflicts with clear reasoning
  • Test blueprints in non-production environments first
  • Version blueprints using semantic versioning
  • Include metadata for discoverability

Module Selection

  • Start with core modules as dependencies
  • Exclude test data in production blueprints
  • Document asset filters in blueprint description
  • Group related modules into focused blueprints

Installation Strategy

  • Preview with describe before installing
  • Generate configs first to review settings
  • Use dry-run mode to validate without installing
  • Keep logs of installation output
  • Test in lower environments before production
Marco Heuer

Marco Heuer

Building Blocks
Building Blocks
Packages & Modules
All UI Components
Workflows
Settings
Interface Contracts
All Rules
By Type
All Types
Knowledge Tracks
Extend Knowledge
Glossary
All How-to Guides
Sitemap
Topics
Use Cases
Helpful Resources
Platform Limits
Support Policy
Service Level Agreement (SLA) - Enterprise
Deprecation Policy
Extend Knowledge Content – Terms and Conditions
System and Organization Controls (SOC) 3 Report
Data Privacy Addendum
Security Policy
Quick Links
For Partners
Customer Resources
Webinars and Events
Certifications
Training Resources
Knowledge Tracks
Builders Portal
Product Update Newsletter
Industry Blogs & Events Newsletter
Trust Center Portal

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Fluent Logo