Fluent Commerce Logo
Docs

Blueprint Config Command

Essential knowledgeCore knowledge to understand Fluent Commerce

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

20 Aug 2026

Overview

Master the `blueprint config` command to automatically generate JSON configuration files for every module in a blueprint. This article teaches implementing partners to prepare retailer-specific settings across multiple environments (dev, staging, prod) before installation.For the business, this ensures consistent environment setups and reduces deployment errors by pre-populating essential placeholders. Note: Generating configs requires retailer-level authentication. Existing files are skipped by default to protect custom edits unless you use the `--force` flag.

Key points

  • Purpose: Generates files named `module.config.<RETAILER>.<module>.json` in your current directory, containing default settings and environment placeholders.
  • Smart Workflow: Use `--module-path` to generate configs from locally downloaded modules—ideal for offline or air-gapped environments.
  • Environment Management: Easily create unique configs for different retailers using the `-r` flag, allowing for seamless multi-environment tracking in Git.
  • Customization: Generated files should be reviewed and edited (e.g., adding integration endpoints) before running the `blueprint install` command.
  • Safety: Use `--force` only when you intend to overwrite existing configs; otherwise, the CLI skips them to preserve your manual customizations.
The `blueprint config` command generates module configuration files for all modules defined in a blueprint.

Syntax

`fluent blueprint config <blueprint> [options]`

Arguments

ArgumentDescriptionRequired
`<blueprint>`Path to blueprint JSON fileYes

Options

OptionDescriptionRequiredDefault
`-p, --profile <profile>`Profile to useNoCurrent active profile
`-r, --retailer <retailer>`Retailer to useNoCurrent active retailer
`--base-dir <directory>`Base directory for extracting modulesNo`/tmp`
`-mp, --module-path <directory>`Local directory containing downloaded modules. Overrides modulePath in blueprint.NoNone
`-f, --force`Overwrite existing config filesNo`false`

Authentication

This command requires: 
  • Retailer-level authentication - Must have valid retailer credentials 
  • Active profile with retailer - Profile must contain retailer settings

How it Works

For each module in the blueprint:
  • Prepare Module - Downloads module if needed (or uses local path) - Extracts to temporary directory - Reads module.json metadata
  • Generate Config - Creates module config JSON file - Names file: `module.config.<RETAILER>.<module-short-name>.json` - Populates with default settings and placeholders
  • Check Existing - If config already exists and `--force` not used: skips and logs - If config exists and `--force` used: overwrites
  • Cleanup - Removes temporary extracted files - Keeps generated config files in current directory

Output

The command displays: 
  • Processing status for each module 
  • Config file creation/skip status 
  • Summary statistics 
  • Final result table

Status Indicators

IconStatusMeaning
`+`CreatedConfig file generated successfully
`-`ExistsConfig already exists, skipped (no --force)
`!`ErrorFailed to generate config

Generated Files

Config files are created in the current working directory:
`module.config.RETAILER01.base-module.json
module.config.RETAILER01.custom-order-module.json
module.config.RETAILER01.payment-extension.json
`

File Naming Pattern

`module.config.<RETAILER-REF>.<MODULE-SHORT-NAME>.json
`
  • `RETAILER-REF` - Retailer reference code (e.g., RETAILER01)
  • `MODULE-SHORT-NAME` - Extracted from module name (e.g., custom-order-module)

Usage Examples

Basic Usage

Generate configs for all modules:
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01
`
Output:
`info: Generating config files for blueprint: retail-order-management
info: Modules to process: 3

info: Processing module: acme/base-module v2.0.0
info:   Config created: module.config.RETAILER01.base-module.json
info: Processing module: acme/custom-order-module v2.5.2
info:   Config created: module.config.RETAILER01.custom-order-module.json
info: Processing module: mycompany/payment-extension v1.8.0
info:   Config created: module.config.RETAILER01.payment-extension.json

info:
info: Summary

┌──────────────────────────────────────┬─────────┬────────────────────────────────────────────────────┐
│ module                               │ status  │ file                                               │
├──────────────────────────────────────┼─────────┼────────────────────────────────────────────────────┤
│ acme/base-module                     │ + Created│ module.config.RETAILER01.base-module.json         │
│ acme/custom-order-module             │ + Created│ module.config.RETAILER01.custom-order-module.json │
│ mycompany/payment-extension          │ + Created│ module.config.RETAILER01.payment-extension.json   │
└──────────────────────────────────────┴─────────┴────────────────────────────────────────────────────┘

info: + Created: 3
info: - Skipped: 0
info: [SUCCESS] (blueprintConfig) Generated config files for 3 modules (0 skipped, 0 errors)
`

Skip Existing Configs

Without `--force`, existing configs are skipped:
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01
`
Output:
`info: Processing module: acme/base-module v2.0.0
info:   Config already exists (use --force to overwrite): module.config.RETAILER01.base-module.json
info: Processing module: acme/custom-order-module v2.5.2
info:   Config created: module.config.RETAILER01.custom-order-module.json
...
info: + Created: 1
info: - Skipped: 2
`

Force Overwrite

Regenerate all configs, overwriting existing:
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01 --force
`
Output:
`info: Processing module: acme/base-module v2.0.0
info:   Overwriting existing config file
info:   Config created: module.config.RETAILER01.base-module.json
`

Custom Base Directory

Use custom directory for module extraction:
`fluent blueprint config accelerator.json \
 -p myprofile \
 -r RETAILER01 \
 --base-dir /var/tmp/modules
`

Generate from Local Modules

Generate configs from locally downloaded modules instead of downloading them:
`# Step 1: Download all modules to local directory
fluent blueprint download accelerator.json -o ./modules

# Step 2: Generate configs from local directory
fluent blueprint config accelerator.json -p myprofile -r RETAILER01 --module-path ./modules
`
Output:
`info: Using local module path: /path/to/modules
info: Generating config files for blueprint: retail-order-management
info: Modules to process: 3

info: Processing module: acme/base-module v2.0.0
info:   Using local module: acme-base-module-2.0.0.zip
info:   Config created: module.config.RETAILER01.base-module.json
`
Benefits of local module path: 
  • Offline capability - Generate configs without internet connection 
  • Faster processing - No download time 
  • Version control - Keep specific module versions locally 
  • Air-gapped environments - Work in restricted networks 
  • Consistency - Same modules across multiple config generations
Notes: 
  • Module filenames must match the pattern: `<module-name-with-dashes>-<version>.zip` 
  • Example: `acme-base-module-2.0.0.zip` 
  • Slashes in module names are replaced with dashes 
  • If `--module-path` is specified, it overrides any `modulePath` in the blueprint 
  • The directory must exist and contain all required module archives 
  • Missing modules will cause config generation to fail for that module

Different Retailer Per Environment

Generate configs for multiple environments:
`# Development environment
fluent blueprint config accelerator.json -p dev -r DEV01

# Staging environment
fluent blueprint config accelerator.json -p staging -r STAGE01

# Production environment
fluent blueprint config accelerator.json -p prod -r PROD01
`
This creates retailer-specific configs:
`module.config.DEV01.base-module.json
module.config.STAGE01.base-module.json
module.config.PROD01.base-module.json
`

Use Cases

Pre-Installation Configuration

Generate and customise configs before installation:
`# Step 1: Generate default configs
fluent blueprint config accelerator.json -p myprofile -r RETAILER01

# Step 2: Review and edit configs
vi module.config.RETAILER01.*.json

# Step 3: Install with custom configs
fluent blueprint install accelerator.json -p myprofile -r RETAILER01
`

Offline Workflow with Local Modules

Download modules once, then generate configs and install offline:
`# Step 1: Download all modules to local directory (requires internet)
fluent blueprint download accelerator.json -o ./modules

# Step 2: Generate configs from local modules (offline)
fluent blueprint config accelerator.json -p myprofile -r RETAILER01 --module-path ./modules

# Step 3: Review and customise configs
vi module.config.RETAILER01.*.json

# Step 4: Install from local modules (offline)
fluent blueprint install accelerator.json -p myprofile -r RETAILER01 --module-path ./modules
`

Multi-Environment Setup

Create configs for all environments:
`# Generate for dev
fluent blueprint config blueprint.json -p dev -r DEV

# Generate for staging
fluent blueprint config blueprint.json -p staging -r STAGE

# Generate for production
fluent blueprint config blueprint.json -p prod -r PROD

# Customise per environment
# Edit each set of configs with environment-specific values
`

Config Version Control

Track config changes in git:
`# Generate configs
fluent blueprint config accelerator.json -p myprofile -r RETAILER01

# Add to git
git add module.config.*.json
git commit -m "Add module configs for v1.0.0"

# Update blueprint to v2.0.0
fluent blueprint config accelerator-v2.json -p myprofile -r RETAILER01 --force

# Review changes
git diff module.config.*.json
`

Selective Config Generation

Generate config for specific module subset:
`# Create custom blueprint with subset of modules
jq '.modules = [.modules[0], .modules[2]]' full-blueprint.json > subset.json

# Generate configs only for those modules
fluent blueprint config subset.json -p myprofile -r RETAILER01
`
Generated config files contain:
`{
 "name": "acme/custom-order-module",
 "version": "2.5.2",
 "includeAssets": [],
 "excludeAssets": [],
 "assetFolder": "modules/custom-order-module",
 "retailer": {
   "ref": "RETAILER01",
   "name": "Retailer Name"
 },
 "account": {
   "id": 123,
   "name": "Account Name"
 },
 "placeholders": {
   "RETAILER_REF": "RETAILER01",
   "ACCOUNT_ID": "123"
 }
}
`

Config File Structure

Generated config files contain:`{
 "name": "acme/custom-order-module",
 "version": "2.5.2",
 "includeAssets": [],
 "excludeAssets": [],
 "assetFolder": "modules/custom-order-module",
 "retailer": {
   "ref": "RETAILER01",
   "name": "Retailer Name"
 },
 "account": {
   "id": 123,
   "name": "Account Name"
 },
 "placeholders": {
   "RETAILER_REF": "RETAILER01",
   "ACCOUNT_ID": "123"
 }
}`

Key Fields

  • name - Module identifier
  • version - Module version
  • includeAssets - Assets to include (if specified in blueprint)
  • excludeAssets - Assets to exclude (if specified in blueprint)
  • retailer - Retailer information from profile
  • account - Account information from profile
  • placeholders - Key-value pairs for variable substitution

Post Generation Steps

1. Review Configs

`# List generated configs
ls -la module.config.*.json

# Review a config
cat module.config.RETAILER01.custom-order-module.json | jq .
`

2. Customise Settings

Edit configs to add: 
  • Environment-specific values 
  • Custom placeholders
  • Asset filters
  • Integration endpoints

3. Validate Configs

`# Check JSON syntax
for f in module.config.*.json; do
 echo "Validating $f"
 jq . "$f" > /dev/null && echo "+ Valid" || echo "! Invalid"
done
`

4. Backup Configs

`# Create backup before installation
tar czf configs-backup-$(date +%Y%m%d).tar.gz module.config.*.json`

Common Scenarios

Scenario 1: Fresh Setup

Situation: First time generating configs
`fluent blueprint config accelerator.json -p myprofile -r RETAILER01
`
Result: All configs created successfullyNext: Review and customise configs, then install

Scenario 2: Regenerate One Config

Situation: Need to regenerate single module config
`# Delete the config
rm module.config.RETAILER01.custom-order-module.json

# Regenerate all (only missing one will be created)
fluent blueprint config accelerator.json -p myprofile -r RETAILER01
`
Result: Only missing config is regenerated

Scenario 3: Update All Configs

Situation: Blueprint updated, need fresh configs
`fluent blueprint config accelerator-v2.json -p myprofile -r RETAILER01 --force
`
Result: All configs overwritten with new defaultsWarning: Custom edits will be lost - backup first!

Error Handling

Module Download Failed

Error:
`error: Failed to prepare module: acme/custom-order-module
`
Solutions: 
  • Check network connectivity 
  • Verify module exists in repository 
  • Check module version is valid 
  • Try with `--base-dir` to use different temp location

Invalid Blueprint

Error:
`error: Blueprint file not found: accelerator.json
`
Solution: Verify blueprint file path

Missing Authentication

Error:
`error: Retailer configuration required
`
Solutions: 
  • Specify retailer: `-r RETAILER01` 
  • Set active retailer: `fluent profile use myprofile -r RETAILER01` 
  • Check profile: `fluent profile list`

Permission Denied

Error:
`error: EACCES: permission denied, open 'module.config.RETAILER01.base-module.json'
`
Solutions: 
  • Check write permissions in current directory 
  • Run from writable directory 
  • Check disk space

Best Practices

Before Generation

  • Validate blueprint with `validate` command
  • Review blueprint with `describe` command
  • Check existing configs to avoid accidental overwrites
  • Backup current configs if regenerating
  • Ensure correct profile/retailer for target environment

After Generation

  • Validate JSON syntax of all configs
  • Review placeholder values for correctness
  • Customise per environment as needed
  • Test in non-production first
  • Version control configs for tracking changes

Multi-Environment

  • Use consistent naming for environments (dev, staging, prod)
  • Separate configs by retailer reference
  • Document customisations in comments or README
  • Automate config generation in CI/CD pipelines

Related Commands