npm package: @nother-cms/create-nothercms
Description: Create a new NotherCMS project with one command
Author: NotherCMS Team
Latest version: 0.1.1

# @nother-cms/create-nothercms

Create a new NotherCMS project with one command.

## Quick Start

```bash
npm create @nother-cms/nothercms@latest my-cms-project
cd my-cms-project
pnpm install
pnpm dev:web
```

## What is NotherCMS?

NotherCMS is a headless CMS built on Firebase with a powerful admin UI. It provides:

- **Modern Admin UI** - Built with React and Vite
- **Cloud Functions API** - Serverless backend on Firebase
- **Firestore Database** - Real-time data with strong security
- **Developer-Friendly** - Full source code control and customization
- **Dual Distribution** - As npm package (this) or Firebase Extension

## What This Package Includes

This scaffolder creates a complete NotherCMS project with:

```
my-cms-project/
├── web/              # Admin UI (React + Vite)
├── functions/        # Cloud Functions API
├── shared/           # Shared TypeScript types
├── cli/              # Bootstrap CLI tool
├── docs/             # Project documentation
└── pnpm-workspace.yaml  # Monorepo configuration
```

## Features

- ✅ **One-Command Setup** - Everything configured and ready to go
- ✅ **Modern Stack** - React 18, TypeScript, Vite
- ✅ **Real-time Database** - Firestore with live updates
- ✅ **Secure API** - Cloud Functions with custom security rules
- ✅ **Admin Panel** - Powerful content management interface
- ✅ **Full Source** - Complete control over your codebase

## Requirements

- **Node.js** 18+
- **npm** 9+ (npm create command)
- **Firebase Account** (free tier works!)

## Getting Started

### 1. Create Project

```bash
npm create @nother-cms/nothercms@latest my-cms
cd my-cms
```

The scaffolder will prompt for:
- Firebase Project ID
- Firebase API Key
- Hosting Site ID (optional)
- Cloud Functions Region

### 2. Install Dependencies

```bash
pnpm install
```

### 3. Configure Firebase

Create `.env.local` in the `web/` directory with your Firebase config:

```bash
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_DATABASE_URL=https://your-project.firebaseio.com
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id
```

### 4. Start Development

```bash
# Start admin UI on http://localhost:5175
pnpm dev:web

# In another terminal, start Firebase emulators
pnpm emulators
```

### 5. Deploy

When ready for production:

```bash
# Deploy Cloud Functions
pnpm deploy:functions

# Deploy Admin UI to Firebase Hosting
pnpm deploy:web
```

## Project Structure

### `/web`
React admin UI using Vite. Features:
- Content management interface
- User authentication with Firebase Auth
- Real-time content preview
- Custom field types

**Development:**
```bash
cd web
pnpm dev
```

### `/functions`
Cloud Functions API (Express). Provides:
- RESTful API endpoints
- Data validation and transformation
- Authentication middleware
- CORS and security policies

**Development:**
```bash
pnpm --filter functions build
firebase functions:log --follow
```

### `/shared`
Shared TypeScript types and utilities used by both web and functions.

### `/cli`
Bootstrap CLI for initial setup and project scaffolding.

## Deployment Options

### Firebase Hosting (Recommended)

```bash
firebase deploy --only hosting,functions
```

Supports custom domains via Firebase Console.

### Vercel

```bash
cd web && npm run build
vercel deploy dist/
```

### Netlify

```bash
cd web && npm run build
netlify deploy --prod --dir=dist
```

### Self-Hosted

1. Build: `pnpm build`
2. Upload `web/dist` to your server/CDN
3. Set `VITE_NCMS_API_ORIGIN` to your API URL
4. Functions deploy to Firebase (unchanged)

## Documentation

- **[Architecture Guide](./docs/architecture.md)** - System design and components
- **[API Documentation](./docs/cli-v1-spec.md)** - REST API specification
- **[Data Model](./docs/data-model.md)** - Content types and structure
- **[Security Model](./docs/security-model.md)** - Firestore rules and permissions
- **[Deployment Guide](./docs/deployment-guide.md)** - Full deployment instructions

## Customization

NotherCMS is designed for customization:

### Add Custom Fields

Edit `web/src/components/FieldEditor.tsx` to add custom field types.

### Extend the API

Add new endpoints to `functions/src/api/`.

### Modify Admin UI

Full React codebase - modify components as needed.

### Custom Firestore Rules

Edit `firestore.rules` before deployment.

## Troubleshooting

### Firebase Emulator Issues

```bash
# Clear emulator data
pnpm emulators --export-on-exit
rm -rf .firebase/emulator-storage
```

### Port Already in Use

```bash
# Change port for web
cd web && pnpm dev -- --port 5176

# Check Firebase emulator ports
lsof -i :8080
```

### Google Sign-In Fails

Add your domain to Firebase Auth Authorized Domains:
1. Firebase Console → Authentication → Settings
2. Add your domain under "Authorized domains"
3. Hard refresh browser

## Support

- **GitHub Issues**: [Report bugs](https://github.com/nother-cms/ncms-firebase/issues)
- **Discussions**: [Ask questions](https://github.com/nother-cms/ncms-firebase/discussions)
- **Firebase Docs**: [Firebase Documentation](https://firebase.google.com/docs)

## License

MIT - See LICENSE file in project root

## Next Steps

1. ✅ Project created
2. 📦 Install dependencies: `pnpm install`
3. 🔑 Add Firebase config: Create `.env.local`
4. 🚀 Start developing: `pnpm dev:web`
5. 🌐 Deploy when ready: `pnpm deploy:web && pnpm deploy:functions`

Happy building! 🎉
# Test version bump for GitHub Actions test