Storefront Commands

The Finqu CLI includes a set of commands for developing custom storefronts using Puck editor and Next.js. These commands are grouped under finqu storefront.

Overview

finqu storefront build

Scans your components directory for *.puck.tsx files and generates Puck configuration files.

Usage

finqu storefront build [options]

Options

What it does

1. Scans the components directory for *.puck.tsx files
2. Extracts component metadata (name, category) from each file
3. Generates two Puck configuration files:
   • puck.edit.config.tsx - For the Puck editor (includes "use client" directive)
   • puck.render.config.tsx - For server-side rendering (no client directive, RSC-compatible)

Component File Patterns

The build command supports two component patterns:

Single file components:

components/
  Hero.puck.tsx
  TextBlock.puck.tsx

Folder-based components with variants:

components/
  Marketing/
    Marketing.edit.puck.tsx    # Editor-specific version
    Marketing.render.puck.tsx  # Server render version
    index.ts                   # Re-exports

When using folder-based components:

• The edit config imports from *.edit.puck.tsx files
• The render config imports from *.render.puck.tsx files
• Falls back to the available variant if only one exists

Component Categories

Components can export a category constant to be grouped in the Puck editor:

export const category = "Marketing";
 
export const config: ComponentConfig<HeroProps> = {
  label: "Hero Banner",
  // ...
};

Example

# Build with defaults
finqu storefront build
 
# Custom paths
finqu storefront build --components src/puck-components --output .generated

finqu storefront dev

Starts a development environment with automatic rebuilding and Next.js dev server.

Usage

finqu storefront dev [options]

Options

What it does

1. Runs an initial build to generate Puck configs
2. Starts the Next.js development server
3. Watches for changes to *.puck.tsx files
4. Automatically rebuilds configs when components are added, changed, or removed

Example

# Start dev server with defaults
finqu storefront dev
 
# Custom port
finqu storefront dev --port 4000
 
# Custom paths
finqu storefront dev --components src/components --output .puck

finqu storefront create

Scaffolds a new Finqu storefront project with Next.js, Puck editor, and example components.

Usage

finqu storefront create [project-name] [options]

Arguments

Options

What it does

1. Creates a new directory with the project name
2. Clones the template repository (or uses embedded templates as fallback)
3. Updates package.json with the project name
4. Initializes a fresh git repository

Project Structure

The created project includes:

my-storefront/
├── app/
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Home page with Puck Render
│   └── editor/
│       └── page.tsx        # Puck editor page
├── components/
│   ├── Hero.puck.tsx       # Example Hero component
│   └── TextBlock.puck.tsx  # Example TextBlock component
├── .gitignore
├── next.config.ts
├── package.json
├── tsconfig.json
└── vercel.json

Generated package.json Scripts

{
  "scripts": {
    "dev": "finqu storefront dev",
    "build": "finqu storefront build && next build",
    "start": "next start",
    "lint": "next lint"
  }
}

Example

# Interactive mode (prompts for project name)
finqu storefront create
 
# With project name
finqu storefront create my-storefront
 
# With custom template
finqu storefront create my-store --template https://github.com/org/custom-template.git
 
# Use embedded templates (no git required)
finqu storefront create my-store --embedded

Project Name Requirements

• Must contain only lowercase letters, numbers, and hyphens
• Cannot be empty

Typical Workflow

1. Create a new project:

finqu storefront create my-storefront
cd my-storefront
npm install

2. Start development:

npm dev
# or directly:
finqu storefront dev

3. Add components:

   • Create *.puck.tsx files in the components/ directory
   • The dev server will automatically rebuild the config

4. Build for production:

npm build
# This runs: finqu storefront build && next build

Technical Notes

• The generated config files are placed in .storefront/ by default
• The .storefront/ directory should be added to .gitignore
• The tsconfig.json includes .storefront/**/*.tsx in the TypeScript compilation
• Edit config uses "use client" directive for Puck editor interactivity
• Render config omits the directive to support React Server Components

Next Steps

• Storefront Overview - Learn about building storefronts
• CLI Overview - General CLI documentation
• Configuration - Configuration reference