@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

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:

bun add -d @pyck/workflow-preview

Then use the CLI directly:

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):

{
  "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:

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

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):

npm publish --access public