# 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.

| Option                    | Description                           | Default       |
| ------------------------- | ------------------------------------- | ------------- |
| `-c, --components <path>` | Path to the components directory      | `components`  |
| `-o, --output <path>`     | Output directory for generated config | `.storefront` |

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.

```bash
finqu storefront create [project-name] [options]
```

| Argument         | Description                                      |
| ---------------- | ------------------------------------------------ |
| `[project-name]` | Project name; if omitted, the CLI prompts for it |

| Option                  | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `-t, --template <url>`  | Git repository URL to use as a template                |
| `-b, --branch <branch>` | Branch to clone; defaults to `main`                    |
| `--embedded`            | Use embedded templates instead of cloning a repository |

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

```text
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

```json
{
  "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

```bash
# 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.

```bash
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.

```bash
finqu storefront dev [options]
```

| Option                | Description                     | Default |
| --------------------- | ------------------------------- | ------- |
| `-p, --port <number>` | Port for the Next.js dev server | `3000`  |

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

```bash
# 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

```text
components/
  Hero.puck.tsx
  TextBlock.puck.tsx
```

### Folder-based components

```text
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:

```tsx
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](/build-with-finqu/storefront/overview) - Learn about building storefronts
- [CLI Overview](./overview) - General CLI documentation
- [Configuration](./configuration) - Configuration reference