create-questpie-app/README.md

Bootstrap a new QUESTPIE Studio application with your choice of template and packages

# create-questpie-app

Bootstrap new QUESTPIE applications with your choice of template and packages.

## Usage

### 🚀 Create New Application

```bash
# Interactive mode (recommended)
npx create-questpie-app
# or
npm create questpie-app
# or
yarn create questpie-app
# or
bunx create-questpie-app

# With project name
npx create-questpie-app my-awesome-app

# Non-interactive mode
npx create-questpie-app my-app --template web --packages "ai,blog,store" --token "your-token"
```

## Development Commands

Once you've created a project, it includes its own CLI for development tasks:

```bash
cd my-app

# Create a new module
bun run cli create-module my-feature --description "My awesome feature"

# Create a simple package
bun run cli create-package my-utils --description "Utility functions"

# Sync environment variables
bun run cli sync-env --verbose
```

## Options

| Option                  | Alias | Description                      | Default               |
| ----------------------- | ----- | -------------------------------- | --------------------- |
| `--template <template>` | `-t`  | Template to use (admin, web)     | `web`                 |
| `--packages <packages>` | `-p`  | Comma-separated list of packages | Interactive selection |
| `--token <token>`       |       | QUESTPIE registry token          | Prompted              |
| `--skip-install`        |       | Skip package installation        | `false`               |
| `--skip-git`            |       | Skip git initialization          | `false`               |

## Templates

### Web Template (`web`)
Full-stack web application with frontend components, includes:
- **Core packages**: `@questpie/core`,  `@questpie/web`
- Next.js app router with internationalization (next-intl)
- Tailwind CSS with theme support
- Frontend and admin routes
- TypeScript configuration optimized for production

### Admin Template (`admin`)
Admin panel and dashboard application, includes:
- **Core packages**: `@questpie/core`,
- Next.js app router focused on admin functionality
- PayloadCMS admin interface
- Clean dashboard structure
- TypeScript configuration optimized for admin workflows

## Module vs Package

### 🔧 **Modules**
Full-featured QUESTPIE modules with:
- PayloadCMS integration (collections, endpoints, globals)
- Frontend components (optional)
- Backend functionality (optional)
- Database migrations
- Module registration system
- Perfect for: business features, integrations, full-stack functionality

### 📦 **Packages**
Simple utility packages with:
- TypeScript build system
- Basic package structure
- No PayloadCMS dependencies
- Perfect for: utilities, types, shared constants, helper functions

## Available Packages

The CLI dynamically fetches packages from the QUESTPIE registry based on your access permissions. Common packages include:

**Core Packages (Required)**
- `@questpie/core` - Core QUESTPIE functionality

**Optional Packages**
- `@questpie/web` - Web frontend components and utilities
- `@questpie/ai` - AI integration and chat functionality
- `@questpie/blog` - Blog content management
- `@questpie/bookings` - Booking and scheduling system
- `@questpie/customers` - Customer management
- `@questpie/deployment` - Deployment automation and tools
- `@questpie/petguide` - Pet guide content management
- `@questpie/pricing` - Pricing and billing management
- `@questpie/search` - Search functionality
- `@questpie/store` - E-commerce store functionality
- `@questpie/venue-finder` - Venue discovery and management

**Note**: Your actual available packages depend on your account permissions. The CLI will only show packages you have access to.

## Registry Authentication

QUESTPIE packages are published to a private registry. You'll need a registry token to access them:

1. Contact your team admin to obtain a registry token
2. The CLI will prompt for the token during setup
3. The token is stored in `.npmrc` in your project directory

## What's Created

The CLI creates a complete turborepo project structure:

```
my-app/
├── apps/
│   └── my-app/              # Your chosen template
├── packages/                # (empty, ready for your packages)
├── package.json             # Root workspace configuration
├── turbo.json               # Turborepo configuration
├── biome.json               # Linting and formatting
├── .npmrc                   # Private registry configuration
├── .gitignore               # Git ignore rules
└── README.md                # Project documentation
```

## Next Steps

### After creating a new application:

1. **Setup environment variables**:
   ```bash
   cd my-app
   cp apps/my-app/.env.example apps/my-app/.env
   # Edit .env with your database and other settings
   ```

2. **Install dependencies** (if skipped):
   ```bash
   bun install
   ```

3. **Start development server**:
   ```bash
   bun run dev
   ```

4. **Access your application**:
   - **Frontend**: http://localhost:3000
   - **Admin Panel**: http://localhost:3000/admin

### After creating modules/packages:

1. **Import your module**:
   ```typescript
   // In your app's payload.config.ts
   import { MyFeatureModule } from '@questpie/my-feature/my-feature.module'

   export default definePayloadConfig(
     defineModule(() => ({
       imports: [
         // ... other modules
         MyFeatureModule,
       ],
     })),
     // ... config
   )
   ```

2. **Use your package**:
   ```typescript
   // Anywhere in your project
   import { myUtility } from '@questpie/my-utils'
   ```

## Environment Variables

Your project requires these environment variables:

```env
# Database (Required)
DATABASE_URI=postgresql://user:password@localhost:5432/questpie
DIRECT_URL=postgresql://user:password@localhost:5432/questpie

# PayloadCMS (Required)
PAYLOAD_SECRET=your-secret-key
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000

# Optional Services
REDIS_URL=redis://localhost:6379
EMAIL_FROM=noreply@yourdomain.com
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-password
```

## Troubleshooting

### Registry Authentication Issues

If you encounter authentication errors:
1. Verify your registry token is valid (the CLI validates tokens in real-time)
2. Check that `.npmrc` exists in your project root
3. Ensure your account has access to required core packages (`@questpie/core`)
4. Contact your administrator if you need access to additional packages

### API Connection Issues

If you encounter package fetching errors:
1. Check your network connection
2. Verify the QUESTPIE packages service is accessible
3. Try again later if the service is temporarily unavailable
4. Contact support if the issue persists

### Build Issues

If you encounter TypeScript or build errors:
1. Ensure all dependencies are installed: `bun install`
2. Generate types: `bun run generate:types`
3. Check that your database connection is configured

### Package Issues

If specific QUESTPIE packages aren't working:
1. Verify the package is included in your `package.json`
2. Check that the module is imported in `payload.config.ts`
3. Ensure the package version is compatible

## Contributing

This CLI is part of the QUESTPIE ecosystem. For issues or contributions:

- 📖 [Documentation](https://docs.questpie.com)
- 💬 [Discord Community](https://discord.gg/questpie)
- 🐛 [GitHub Issues](https://github.com/questpie/questpie)

## License

MIT