# Harmonic SaaS

A production-ready Nuxt Layer providing core SaaS functionality - authentication, database management, internationalization, and more. Build your next SaaS application on a solid, extensible foundation.

[![npm version](https://img.shields.io/npm/v/@vernaillen/harmonic-saas.svg)](https://www.npmjs.com/package/@vernaillen/harmonic-saas)
[![License](https://img.shields.io/npm/l/@vernaillen/harmonic-saas.svg)](https://github.com/vernaillen/harmonic-saas/blob/main/LICENSE)

## Features

✨ **Authentication** - Email/password, OAuth (GitHub, Google), magic links, passkeys
🗄️ **Database** - PostgreSQL with Drizzle ORM, extensible schema
🌍 **Internationalization** - Dutch & English, easy to add more languages
🎨 **Modern UI** - Nuxt UI with Tailwind CSS v4
📧 **Email Integration** - Resend for transactional emails
🧪 **Testing** - Comprehensive E2E tests with Playwright
🔒 **Security** - Email verification, password reset, account management
📦 **Layer-based** - Extend and customize without forking

## Quick Start

### Installation

```bash
# Install the layer
pnpm add @vernaillen/harmonic-saas

# Or with npm
npm install @vernaillen/harmonic-saas
```

### Configuration

Add the layer to your `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  extends: ['@vernaillen/harmonic-saas']
})
```

### Environment Setup

Create a `.env` file with required variables:

```bash
# Database
NUXT_DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Authentication (Better Auth)
NUXT_BETTER_AUTH_SECRET=your-secret-key
NUXT_BETTER_AUTH_URL=http://localhost:3000

# OAuth Providers (optional)
NUXT_GITHUB_CLIENT_ID=your-github-client-id
NUXT_GITHUB_CLIENT_SECRET=your-github-client-secret
NUXT_GOOGLE_CLIENT_ID=your-google-client-id
NUXT_GOOGLE_CLIENT_SECRET=your-google-client-secret

# Email (Resend or SMTP)
NUXT_RESEND_API_KEY=your-resend-api-key
NUXT_FROM_EMAIL=noreply@yourdomain.com
NUXT_APP_NAME=Your App Name

# CORS Configuration (Production only)
# Comma-separated list of allowed origins for API access
# Capacitor app origins are always allowed automatically
ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
```

See [Email Integration Guide](./docs/content/en/3.guides/1.email-integration.md) for detailed email setup.

**Security Note:** In production, CORS is restricted to origins listed in `ALLOWED_ORIGINS` plus Capacitor app origins. See [CORS Configuration Guide](./docs/content/en/7.security-cors.md) for details.

### Firebase Setup (Android/iOS)

If you're building mobile apps with Capacitor and using Firebase (for push notifications, etc.):

⚠️ **IMPORTANT**: The `android/app/google-services.json` file contains sensitive API keys and should **NEVER** be committed to version control.

1. Download your `google-services.json` from [Firebase Console](https://console.firebase.google.com/)
2. Place it in `android/app/google-services.json` (already in `.gitignore`)
3. See [Firebase Setup Guide](./android/FIREBASE_SETUP.md) for detailed instructions

### Database Setup

```bash
# Generate migrations
pnpm db:generate

# Run migrations
pnpm db:migrate

# Or push schema directly in development
pnpm db:push
```

### Development

```bash
# Start development server
pnpm dev

# Run tests
pnpm test

# Run E2E tests
pnpm test:e2e

# Lint code
pnpm lint

# Type check
pnpm typecheck
```

## Technology Stack

- **Framework:** Nuxt 4 with Vue.js and TypeScript
- **Database:** PostgreSQL with Drizzle ORM
- **Authentication:** Better Auth
- **UI:** Nuxt UI with Tailwind CSS v4
- **Email:** Resend
- **Testing:** Vitest + Playwright
- **Package Manager:** pnpm

## Architecture

### Layer-Based Design

Harmonic SaaS is a **Nuxt Layer** - a reusable, composable foundation that you extend rather than fork. Your application inherits all the core functionality while maintaining full customization control.

```
your-app/
├── nuxt.config.ts          # extends: ['@vernaillen/harmonic-saas']
├── app/
│   ├── pages/              # Your custom pages
│   └── components/         # Your custom components
└── server/
    ├── api/                # Your custom API routes
    └── database/           # Extend the schema
```

### Extending the Database Schema

```typescript
// server/database/registerTables.ts
import { registerTables } from '@vernaillen/harmonic-saas/server/database'
import { myCustomTable } from './schema'

registerTables({
  customTable: myCustomTable
})
```

### Protected Routes

Routes in `/app/pages/dashboard/` are automatically protected. To make a page public:

```vue
<script setup lang="ts">
definePageMeta({ auth: false })
</script>
```

## Documentation

- 📖 [Full Documentation](./docs/) - Comprehensive guides and references
- 🚀 [E2E Testing Guide](./docs/content/en/4.testing/1.e2e-quick-start.md) - Getting started with tests
- 📧 [Email Integration](./docs/content/en/3.guides/1.email-integration.md) - Email setup guide
- 🧑‍💻 [CLAUDE.md](./CLAUDE.md) - Developer onboarding and architecture
- 📝 [CHANGELOG.md](./CHANGELOG.md) - Version history

## Development Workflow

### Working on the Layer

The `.playground` directory is your development environment for testing the layer:

```bash
# Start .playground development server
pnpm dev

# This boots the .playground directory which imports the layer
```

### Testing

```bash
# Unit tests
pnpm test

# E2E tests
pnpm test:e2e

# Test coverage
pnpm coverage
```

See [Testing Documentation](./docs/content/en/4.testing/) for detailed testing documentation.

### Quality Assurance

```bash
# Run all checks before committing
pnpm lint          # ESLint with stylistic rules
pnpm typecheck     # TypeScript type checking
pnpm test          # Run test suite
pnpm coverage      # Ensure test coverage
```

### Release Process

```bash
# Full release workflow
pnpm release       # Lint + coverage + version bump + publish
```

This runs the complete release workflow including linting, testing, coverage checks, and publishing to NPM.

## Project Structure

```
harmonic-saas/
├── app/                    # Frontend application
│   ├── components/         # Vue components
│   ├── composables/        # Composable functions
│   ├── middleware/         # Route middleware
│   └── pages/              # Application pages
├── server/                 # Backend API
│   ├── api/                # API routes
│   ├── database/           # Database schema & utilities
│   └── utils/              # Server utilities
├── emails/                 # Email templates (Vue Email)
├── docs/                   # Documentation site (Nuxt Content)
│   ├── content/en/         # English documentation
│   │   ├── guides/         # Setup guides
│   │   ├── testing/        # Testing documentation
│   │   └── reference/      # Reference materials
│   └── public/             # Static assets
├── test/                   # Test suites
│   ├── e2e/                # Playwright E2E tests
│   └── unit/               # Vitest unit tests
├── i18n/                   # Internationalization
│   └── locales/            # Language files
└── .playground/            # Development environment
```

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

## License

[MIT License](./LICENSE)

## Links

- [NPM Package](https://www.npmjs.com/package/@vernaillen/harmonic-saas)
- [GitHub Repository](https://github.com/vernaillen/harmonic-saas)
- [Documentation](./docs/)

---

Built with ❤️ using Nuxt 4 and Better Auth
