Blueprint Create Command

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Essential knowledge

Intended Audience:

Technical User

Author:

Marco Heuer

Changed on:

20 Aug 2026

Overview

Learn how to use the `blueprint create` command to generate JSON manifest templates for Fluent Commerce. This article empowers implementing partners to build consistent, repeatable deployment "recipes" that slash environment setup time. For the business, this translates to faster time-to-market and reduced manual configuration errors.Note: The generated file contains placeholder versions (1.0.0) for all modules; you must manually update these to your specific requirements and validate the file before installation to ensure a successful deployment.

Key points

Command: Use `fluent blueprint create --name <name>` to generate a new JSON template.
Pre-populated Content: Includes all 4 reference modules (core, order, inventory, fulfilment) and a custom project module.
Placeholders: All module versions are set to `1.0.0` by default; these must be updated to match your requirements before installation.
Customization: Add organization-specific modules, define conflict rules, and update metadata (description/authors) within the file.
Workflow: Create → Customise → Validate → Install.
Error Prevention: The command will not overwrite existing files.

What does the `blueprint create` command do?

Create a blueprint template file pre-populated with reference modules.The `blueprint create` command generates a new blueprint template file in the current directory. The template includes all reference modules with placeholder versions (1.0.0), placeholder custom module and empty conflicts array.

Command Syntax

`fluent blueprint create --name <name>`

Options

Option	Short	Required	Description
`--name <name>`	`-n`	Yes	Blueprint name (used for filename and internal name field)

Output File Naming

The command generates a file with the pattern: `<name>-1.0.0.json`Examples:

`--name "retail-accelerator"` → `retail-accelerator-1.0.0.json`
`--name "acme"` → `acme-1.0.0.json`
`--name "my-custom-blueprint"` → `my-custom-blueprint-1.0.0.json`

Template Structure

The generated blueprint includes:

name: From `--name` flag
version: Always `"1.0.0"`
description: Placeholder text `"Blueprint description"`
created: Current timestamp in ISO 8601 format
authors: Single placeholder author object
modules: 4 reference modules plus 1 template module, all with placeholder version `1.0.0`:
`core` (v1.0.0)
`order` (v1.0.0)
`inventory` (v1.0.0)
`fulfilment` (v1.0.0)
`{{blueprint-name}}-module` (v1.0.0)
conflicts: Empty array
tags: `["custom"]`

Note: Module versions are placeholders - update to your required versions before installation. The template module (`{{blueprint-name}}-module`) serves as an example - update or remove it based on your needs.

Usage Examples

Basic Usage

`fluent blueprint create --name "retail-accelerator"`
Output:
`Creating blueprint template: retail-accelerator-1.0.0.json`

Blueprint template created successfully

Template includes 5 modules:
- core (v1.0.0)
- order (v1.0.0)
- inventory (v1.0.0)
- fulfilment (v1.0.0)
- retail-accelerator-module (v1.0.0)

Next steps:
1. Edit retail-accelerator-1.0.0.json to customise:
    - Description and metadata
    - Module versions and selection
    - Update template module name
    - Define conflicts
2. Validate: fluent blueprint validate retail-accelerator-1.0.0.json
3. Install: fluent blueprint install retail-accelerator-1.0.0.json

Creating Template for Custom Project

`fluent blueprint create --name "acme-retail-v2"`
Creates `acme-retail-v2-1.0.0.json` with all reference modules.

Quick Start Workflow

`# 1. Create template
`

fluent blueprint create --name "my-blueprint"

`# 2. Edit the generated file
`

vi my-blueprint-1.0.0.json

`# 3. Customise:
#    - Update description and authors
#    - Adjust module versions as needed
#    - Add any custom modules
#    - Define conflicts with incompatible modules
`

`# 4. Install
`

fluent blueprint install my-blueprint-1.0.0.json -p myprofile -r RETAILER01

Generated Template Example

`{`
"name": "retail-accelerator",
"version": "1.0.0",
"description": "Blueprint description",
"created": "2024-01-06T16:30:00.123Z",
"authors": [
   {
     "name": "Your Name",
     "email": "your.email@example.com"
   }
],
"modules": [
   {
     "name": "core",
     "version": "1.0.0"
   },
   {
     "name": "order",
     "version": "1.0.0"
   },
   {
     "name": "inventory",
     "version": "1.0.0"
   },
   {
     "name": "fulfilment",
     "version": "1.0.0"
   },
   {
     "name": "retail-accelerator-module",
     "version": "1.0.0",
     "modulePath": "S3 or local folder path"
   }
],
"conflicts": [],
"tags": ["custom"]
}

Customisation Guide

After generating the template, customise these fields:

1. Metadata

Update blueprint information:
`{`
"name": "retail-accelerator",
"version": "1.0.0",
"description": "Complete retail solution with order and inventory management",
"authors": [
   {
     "name": "ACME Corp",
     "email": "support@acme.com",
     "web": "https://acme.com"
   }
],
"tags": ["retail", "order-management", "inventory"]
}

2. Module Selection

Important: The template includes placeholder version `1.0.0` for all reference modules. You must update these to your required versions before installation.Adjust module versions or remove unneeded modules:
`{`
"modules": [
   {
     "name": "core",
     "version": "2.2.1"

`// Updated from 1.0.0 placeholder
`

   },
   {
     "name": "order",
     "version": "2.5.3"

`// Updated from 1.0.0 placeholder
`

}

`// Removed inventory and fulfilment
`

]
}

3. Add Custom Modules

Include your organisation's modules:
`{`
"modules": [
   {
     "name": "core",
     "version": "2.2.1"

`// Updated from placeholder
`

   },
   {
     "name": "{{name}}-module",
     "version": "1.5.0",
     "excludes": ["test-data"]
   }
]
}
Example with actual values:
`{`
"modules": [
   {
     "name": "core",
     "version": "2.2.1"
   },
   {
     "name": "acme/order-module",
     "version": "1.5.0",
     "excludes": ["test-data"]
   }
]
}

4. Define Conflicts

Specify incompatible modules:
`{`
"conflicts": [
   {
     "name": "legacy-order-module",
     "type": "module",
     "version": "*",
     "reason": "Replaced by new order module"
   }
]
}

Error Handling

Missing Name

Error:
`error: required option '-n, --name <name>' not specified`

Usage: fluent blueprint create --name <name>
Exit Code: 1Solution: Provide the `--name` option

File Already Exists

Error:
`error: File already exists: retail-accelerator-1.0.0.json`
Use a different name or remove the existing file
Exit Code: 2Solution: Either: - Choose a different name - Remove the existing file - Rename the existing file

Write Permission Error

Error:
`error: Failed to create blueprint template`
EACCES: permission denied, open 'retail-accelerator-1.0.0.json'
Exit Code: 3Solution: - Check directory write permissions - Ensure sufficient disk space - Verify directory exists

Exit Codes

Code	Meaning
0	Template created successfully
1	Missing required `--name` option
2	File already exists (won't overwrite)
3	File write error (permissions, disk space, etc.)

Best Practices

Blueprint Design

Start with reference modules and add custom modules incrementally
Use semantic versioning for your blueprints
Document customisations in the description field
Test in non-production environments first
Version control your blueprint files

Customisation Workflow

Create template with this command
Update metadata immediately (description, authors)
Adjust module versions to match your requirements
Add custom modules specific to your implementation
Define conflicts to prevent incompatible installations
Validate before deployment

Naming Conventions

Use descriptive names that indicate purpose
Include version or variant in name if managing multiple versions
Use lowercase with hyphens for consistency
Examples: `retail-base`, `b2c-complete`, `warehouse-management`

Related Commands

validate - Validate blueprint before installation
describe - Preview blueprint contents before installation
install - Install modules from the blueprint
config - Generate module configuration files
list - View installed blueprints

Common Workflows

Creating an Organisation-Specific Blueprint

`# 1. Create base template
`

fluent blueprint create --name "acme-retail"

`# 2. Customise template
`

cat > acme-retail-1.0.0.json << 'EOF'
{
"name": "acme-retail",
"version": "1.0.0",
"description": "ACME Corp retail solution with custom order processing",
"created": "2024-01-06T16:30:00.123Z",
"authors": [
   {
     "name": "ACME Corp",
     "email": "platform@acme.com",
     "web": "https://acme.com/platform"
   }
],
"modules": [
   {
     "name": "core",
     "version": "2.2.1"
   },
   {
     "name": "order",
     "version": "2.5.3"
   },
   {
     "name": "acme/order-module",
     "version": "1.5.0"
   }
],
"conflicts": [],
"tags": ["acme", "retail", "custom"]
}
EOF

`# 3. Install across environments
`

fluent blueprint install acme-retail-1.0.0.json -p dev -r DEV01
fluent blueprint install acme-retail-1.0.0.json -p staging -r STAGE01
fluent blueprint install acme-retail-1.0.0.json -p prod -r PROD01

Creating a Minimal Blueprint

`# 1. Create template
`

fluent blueprint create --name "minimal-base"

`# 2. Edit to remove unneeded modules
# Keep only core and one domain module
`

`# 3. Use as base for specific implementations`