Storefront Commands

Use finqu storefront to scaffold a storefront project, generate Puck configuration from your components, and run the development workflow with automatic rebuilding.

Typical Workflow

1. Create a project with finqu storefront create my-storefront.
2. Install dependencies with npm install.
3. Run finqu storefront dev.
4. Add or update *.puck.tsx components.
5. Build for production with finqu storefront build && next build.

Shared Paths and Output

finqu storefront build and finqu storefront dev both scan a components directory and write generated config files to an output directory.

The generated config directory should usually be added to .gitignore, and tsconfig.json should include .storefront/**/*.tsx so the generated files are typechecked.

Create a Project

finqu storefront create

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

finqu storefront create [project-name] [options]

What the command does:

1. Creates a new project directory.
2. Copies the template files, either from git or the embedded template.
3. Updates package.json with the project name.
4. Initializes a fresh git repository.

Example project structure

my-storefront/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── editor/
│       └── page.tsx
├── components/
│   ├── Hero.puck.tsx
│   └── TextBlock.puck.tsx
├── .gitignore
├── next.config.ts
├── package.json
├── tsconfig.json
└── vercel.json

Generated scripts

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

Project names must use lowercase letters, numbers, and hyphens.

Examples

# Interactive mode
finqu storefront create
 
# Create a named project
finqu storefront create my-storefront
 
# Use a custom template
finqu storefront create my-store --template https://github.com/org/custom-template.git
 
# Use embedded templates
finqu storefront create my-store --embedded

Build and Develop

finqu storefront build

Generates Puck configuration files from your component files.

finqu storefront build [options]

It scans for *.puck.tsx files, extracts component metadata, and generates:

• puck.edit.config.tsx for the Puck editor
• puck.render.config.tsx for rendering, including React Server Components

finqu storefront dev

Runs the storefront development workflow with automatic rebuilding and the Next.js dev server.

finqu storefront dev [options]

This command:

1. Runs an initial build.
2. Starts the Next.js development server.
3. Watches *.puck.tsx files for changes.
4. Rebuilds generated config when components are added, changed, or removed.
5. Hot reloads the browser.

If the chosen port is already in use, the CLI automatically picks the next available port.

Examples

# Build with defaults
finqu storefront build
 
# Custom input and output paths
finqu storefront build --components src/puck-components --output .generated
 
# Start dev server with defaults
finqu storefront dev
 
# Start dev server on a custom port
finqu storefront dev --port 4000
 
# Custom paths while developing
finqu storefront dev --components src/components --output .puck

Component Discovery

Both build and dev use the same component scanning rules.

Single-file components

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

Folder-based components

components/
  Marketing/
    Marketing.edit.puck.tsx
    Marketing.render.puck.tsx
    index.ts

With folder-based components:

• The edit config imports from *.edit.puck.tsx
• The render config imports from *.render.puck.tsx
• If only one variant exists, the CLI falls back to the available file

Component categories

You can export a category constant to group components in the Puck editor:

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

The generated edit config uses "use client" for editor interactivity. The render config omits it to support React Server Components.

Next Steps

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