@flowcreate/create-flowcreate-app

CLI tool to scaffold new FlowCreate applications.

Usage

Create a new FlowCreate app with a single command:

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

npx @flowcreate/create-flowcreate-app my-awesome-app

Template

Specify a template to use (default: default):

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:

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:

cd my-app
npm install
npm run dev

Your FlowCreate app will be running at http://localhost:3000.

Try It Out

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

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:

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:

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:

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

# Use the default template (omit --template flag)
npx @flowcreate/create-flowcreate-app my-app

Installation Issues

If you encounter installation issues:

# 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
• @flowcreate/core API Reference
• Examples

License

MIT © FlowCreate Contributors