@fivora/cli

Official developer CLI for creating, initializing, testing, validating, and packaging Fivora templates.

Installation

You can run commands directly using npx:

npx @fivora/cli <command>

Or install globally:

npm install -g @fivora/cli

Or install as a project devDependency:

npm install -D @fivora/cli

The CLI command is available as fivora.

Commands

1. fivora init (Configure an Existing Project)

Converts any existing Next.js project into a compliant Fivora template:

# Inside your existing Next.js project directory:
npx @fivora/cli init
# or if installed globally / locally:
fivora init

What it does automatically:

• Scans src/app, app, and pages to discover your existing routes (e.g. /products, /about, /contact).
• Generates fivora-template.json (Version 2 strict visual editing contract) with detected pages.
• Generates src/data/site-data.json for merchant branding, navigation labels, and editable copy.
• Injects npm scripts (lab, validate, zip, package:template) into package.json.
• Installs @fivora/editable-components and @fivora/cli.
• Checks next.config to verify output: 'export' for static export builds.

Options:

• --skip-install – Skip automatic npm install of dependencies.

2. fivora create <project-name> (Start from Scratch)

Scaffolds a brand-new, production-ready Fivora store with Next.js App Router, Tailwind/CSS, and editable components pre-configured:

fivora create my-store
cd my-store
npm run dev

3. fivora lab [path] (Visual Editing Lab)

Starts the local Fivora Visual Editing Lab. It boots your Next.js store inside an interactive editor simulation so you can test merchant visual click-to-edit interactions and field highlights before uploading.

fivora lab .
# Or via npm script:
npm run lab

Options:

• --api-port <port> – Controller API port (default: 4174)
• --preview-port <port> – Template dev server port (default: 4173)
• --skip-install – Do not install missing dependencies automatically

4. fivora validate [path] (Contract Preflight Validation)

Runs strict preflight compliance checks against the Fivora template contract:

• Manifest Validation: Ensures fivora-template.json satisfies contract version 2.
• Probe Fixture Test: Verifies that all data-preview-field-path annotations render without breaking.
• Empty-State Safety: Verifies the template does not crash when merchant content is empty or omitted.
• Unselected Page Link Filtering: Verifies links to optional unselected pages are cleanly filtered.

fivora validate .
# Or via npm script:
npm run validate

Options:

• --skip-install – Skip dependency installation during check
• --skip-build – Skip building output directory
• --json – Output results as structured JSON

5. fivora zip [path] (Clean 1-Click Packaging)

Packages your template into an upload-ready .zip file for the Fivora Developer Portal.

fivora zip .
# Or via npm script:
npm run zip

Automatic Exclusions: Strips out heavy and private files automatically:

• node_modules/
• .next/ and .turbo/
• .git/
• .env* files
• Temporary logs and build caches

Output is saved as fivora-template.zip in your project root.

6. fivora update [path] (Update Fivora Dependencies)

Updates @fivora/editable-components and @fivora/cli to their latest versions:

fivora update
# Or via npm script:
npm run update:fivora

What it does:

• In standard/published projects: Runs npm install @fivora/editable-components@latest @fivora/cli@latest.
• In local development workspaces: Automatically detects file: package paths (or with --local flag) and re-links directly against local package folders.

Options:

• --local / -l (optional --local=<path>) – Re-link against a local workspace for developing packages locally (defaults to /mnt/GAMES/GitHub/fivora_package).

Template Manifest (fivora-template.json)

The template manifest declares template metadata, pages, and editable schema:

{
  "framework": "nextjs-static-export",
  "version": 2,
  "visualEditing": {
    "contractVersion": 1,
    "mode": "strict",
    "controlOnlyPaths": []
  },
  "siteDataFile": "src/data/site-data.json",
  "outputDirectory": "out",
  "installCommand": "npm install",
  "buildCommand": "npm run build",
  "basePathEnvVar": "NEXT_PUBLIC_SITE_BASE_PATH",
  "pages": [
    { "id": "home", "label": "Home", "route": "/", "required": true },
    { "id": "products", "label": "Products", "route": "/products" },
    { "id": "contact", "label": "Contact", "route": "/contact", "required": true }
  ],
  "editorSchema": {
    "version": 1,
    "sections": []
  }
}

Troubleshooting

Error: Template manifest is missing or invalid

Your project is missing fivora-template.json. Run:

npx @fivora/cli init

This will automatically generate the manifest and site data for your project.

Error: Template manifest framework must be "nextjs-static-export"

Make sure your next.config.ts or next.config.js specifies static export:

const nextConfig = {
  output: 'export',
};
export default nextConfig;

License

MIT © Fivora