npm package: @pyck/workflow-preview
Description: CLI for previewing and building Pyck workflow UIs. Auto-discovers web components and mobile widgets from a `workflows/` directory, serves them in a dev preview with HMR, and produces Module Federation remotes for production.
Latest version: 0.2.19

# @pyck/workflow-preview

CLI for previewing and building Pyck workflow UIs. Auto-discovers web components and mobile widgets from a `workflows/` directory, serves them in a dev preview with HMR, and produces Module Federation remotes for production.

## Quick start

```bash
bun install
task dev -- --workflows /path/to/workflows
```

Opens `http://localhost:4173` with:

- Index page listing all discovered workflows grouped by name
- Web component previews rendered in a phone-sized container
- Mobile widget previews rendered live via embedded rfw-preview
- HMR for instant feedback on code changes

## Tasks

| Task | Description |
|------|-------------|
| `task dev` | Start preview dev server |
| `task build` | Build static preview site to `dist/web/` |
| `task build:mf` | Build Module Federation remote to `dist/mf/` |
| `task build:flutter` | Rebuild mobile preview (requires Docker, rarely needed) |
| `task test` | Run tests |
| `task lint` | Run linter |

Pass CLI flags after `--`, e.g. `task dev -- --port 3000 --workflows ./workflows`.

## Usage as npm package

Install as a dev dependency in a customer project:

```bash
bun add -d @pyck/workflow-preview
```

Then use the CLI directly:

```bash
bunx @pyck/workflow-preview dev --workflows ./workflows
bunx @pyck/workflow-preview build
bunx @pyck/workflow-preview build:mf
```

Or add to `package.json` scripts (short form works once installed):

```json
{
  "scripts": {
    "preview": "workflow-preview dev",
    "build:mf": "workflow-preview build:mf"
  }
}
```

## CLI options

| Flag | Default | Description |
|------|---------|-------------|
| `--port <n>` | `4173` | Dev server port |
| `--workflows <path>` | `./workflows` | Path to workflows directory |
| `--outdir <path>` | `dist/web` or `dist/mf` | Output directory for builds |
| `-h, --help` | | Show help |

## Workflow directory structure

The CLI expects workflows organized like this:

```
workflows/
  001-demo-workflow/
    web/
      verify-item-details/
        main.tsx              # React component (default export)
      info-needs-correction/
        main.tsx
    mobile/
      verify-item-details.rfwtxt   # RFW widget definition
      info-needs-correction.rfwtxt
  002-another-workflow/
    web/
      ...
```

Web components should default-export a component that accepts `PyckComponentProps<T>` from `@pyck/sdk`.

## How it works

- **Discovery**: `import.meta.glob` with a `@workflows` Vite alias pointing at your workflows directory
- **Dep resolution**: A Vite plugin ensures bare imports from workflow files (`react`, `@pyck/react`, etc.) resolve through your project's `node_modules`, preventing duplicate instances
- **PandaCSS**: A temporary config is generated at startup that scans both the preview app and your workflow files for `@pyck/styled-system` utility usage
- **Mobile preview**: The pre-built rfw-preview Flutter web app is served at `/mobile/` and renders `.rfwtxt` widgets live via iframe
- **MF build**: Uses `@module-federation/vite` with auto-discovered exposes and shared React singletons

## Rebuilding mobile preview

The mobile preview (Flutter web build) is checked into `static/mobile/`. It only needs rebuilding when the Dart source in `flutter/` changes:

```bash
task build:flutter
```

This runs a Docker build using the `ghcr.io/pyck-ai/baseimages/flutter` image. The output is cached by go-task (skipped if `flutter/` sources haven't changed).

## Peer dependencies

Your project needs these installed:

```
react >= 19
react-dom >= 19
@pyck/react >= 0.2
@pyck/styled-system >= 0.2
@pyck/sdk >= 0.1
@pyck/panda-preset >= 0.2
```

## Releasing

```bash
npm version patch   # 0.2.0 -> 0.2.1 (bug fix)
npm version minor   # 0.2.0 -> 0.3.0 (new feature)
npm version major   # 0.2.0 -> 1.0.0 (breaking change)
git push && git push --tags
```

`npm version` bumps `package.json`, commits, and creates a git tag in one step. Pushing the tag triggers CI which publishes to npm.

To publish manually (without CI):

```bash
npm publish --access public
```