npm package: @flowcreate/create-flowcreate-app
Description: CLI tool to scaffold new FlowCreate applications
Author: FlowCreate Contributors
Latest version: 0.1.5

# @flowcreate/create-flowcreate-app

CLI tool to scaffold new FlowCreate applications.

## Usage

Create a new FlowCreate app with a single command:

```bash
npx @flowcreate/create-flowcreate-app my-app
```

This will:
1. Create a new directory called `my-app`
2. Copy the FlowCreate template files
3. Set up a working Express server with TypeScript
4. Include an example order workflow

## Options

### Project Name

The project name is required and will be used as:
- The directory name
- The package name in `package.json`

```bash
npx @flowcreate/create-flowcreate-app my-awesome-app
```

### Template

Specify a template to use (default: `default`):

```bash
npx @flowcreate/create-flowcreate-app my-app --template default
```

Currently available templates:
- `default` - Express server with order workflow example

## What's Included

The generated project includes:

### Project Structure

```
my-app/
├── src/
│   └── index.ts          # Main application file
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # Project documentation
```

### Dependencies

- **@flowcreate/core** - Core FlowCreate library
- **express** - Web framework
- **typescript** - TypeScript compiler
- **ts-node** - TypeScript execution for development

### Scripts

- `npm run dev` - Start development server with hot reload
- `npm run build` - Build for production
- `npm start` - Run production build
- `npm test` - Run tests (placeholder)

### Example Workflow

The template includes a complete order management workflow:

```typescript
const orderFlow = {
  initial: 'pending',
  states: {
    pending: { events: { pay: 'paid', cancel: 'cancelled' } },
    paid: { events: { ship: 'shipped', refund: 'refunded' } },
    shipped: { events: { deliver: 'delivered', return: 'returned' } },
    delivered: { events: { return: 'returned' } },
    cancelled: { events: {} },
    refunded: { events: {} },
    returned: { events: { refund: 'refunded' } }
  }
};
```

## Getting Started

After creating your app:

```bash
cd my-app
npm install
npm run dev
```

Your FlowCreate app will be running at `http://localhost:3000`.

### Try It Out

```bash
# Create an order and pay for it
curl -X POST http://localhost:3000/flows/orders/order-123/events/pay \
  -H "Content-Type: application/json" \
  -d '{"actorId":"user-1"}'

# Ship the order
curl -X POST http://localhost:3000/flows/orders/order-123/events/ship \
  -H "Content-Type: application/json" \
  -d '{"actorId":"warehouse-1"}'

# Check the current state
curl http://localhost:3000/flows/orders/order-123/state
```

## Customization

### Add New Workflows

Edit `src/index.ts` and add new state machine definitions:

```typescript
const ticketFlow = {
  initial: 'open',
  states: {
    open: { events: { assign: 'assigned', close: 'closed' } },
    assigned: { events: { resolve: 'resolved', close: 'closed' } },
    resolved: { events: { reopen: 'open', close: 'closed' } },
    closed: { events: {} }
  }
};

const middleware = createExpressMiddleware({
  flows: {
    orders: orderFlow,
    tickets: ticketFlow  // Add your new workflow
  },
  storage
});
```

### Change Storage Backend

Replace `InMemoryStorage` with a persistent storage adapter:

```typescript
import { SupabaseStorage } from '@flowcreate/core';
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_KEY!
);

const storage = new SupabaseStorage(supabase);
```

### Customize Actor ID Extraction

Modify how actor IDs are extracted from requests:

```typescript
const middleware = createExpressMiddleware({
  flows: { orders: orderFlow },
  storage,
  actorIdExtractor: (req) => {
    // Extract from JWT, session, or custom header
    return req.user?.id || req.headers['x-user-id'] || 'anonymous';
  }
});
```

## Requirements

- Node.js >= 18.0.0
- npm >= 9.0.0

## Troubleshooting

### Directory Already Exists

If you see an error about the directory already existing:

```bash
# Use a different name
npx @flowcreate/create-flowcreate-app my-app-v2

# Or remove the existing directory
rm -rf my-app
npx @flowcreate/create-flowcreate-app my-app
```

### Template Not Found

If you see an error about the template not being found:

```bash
# Use the default template (omit --template flag)
npx @flowcreate/create-flowcreate-app my-app
```

### Installation Issues

If you encounter installation issues:

```bash
# Clear npm cache
npm cache clean --force

# Try with latest npm
npm install -g npm@latest

# Use npx with latest version
npx @flowcreate/create-flowcreate-app@latest my-app
```

## Learn More

- [FlowCreate Documentation](https://github.com/unt1tler/flowcreate)
- [@flowcreate/core API Reference](../core/README.md)
- [Examples](https://github.com/unt1tler/flowcreate/tree/main/examples)

## License

MIT © FlowCreate Contributors