create-rykira-app 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# create-rykira-app
+
+A powerful, production-ready full-stack starter template generator.
+
+## Features
+
+- **Monorepo**: Powered by Turborepo and pnpm workspaces.
+- **Frontend**: Next.js 15 (App Router), React 19, Tailwind CSS v4.
+- **UI Library**: Shared Shadcn/UI component library.
+- **Backend**: Express.js with TypeScript, Zod validation.
+- **Infrastructure**: 
+  - Docker Compose for Dev & Prod.
+  - Traefik v3 Reverse Proxy with Let's Encrypt.
+  - Postgres & Redis.
+- **Deployment**: Ready for Coolify or manual VPS deployment.
+
+## Usage
+
+Run the following command to scaffold a new project:
+
+```bash
+npx create-rykira-app my-app
+```
+
+Follow the interactive prompts to customize your project:
+- Project Name
+- Description
+- Author
+- Include/Exclude Admin Panel
+- Include/Exclude Express API
+
+## Getting Started
+
+Once created:
+
+```bash
+cd my-app
+pnpm install
+cp .env.example .env
+# Update .env variables if needed
+pnpm dev
+```
+
+## Deployment
+
+Refer to `plan.md` (included in the template) or the generated README for detailed deployment instructions.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import ora from 'ora';
+import Handlebars from 'handlebars';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+program
+  .name('create-rykira-app')
+  .description('Scaffold a new Rykira Starter Package project')
+  .version('1.0.0')
+  .argument('[project-directory]', 'Directory to create the project in')
+  .action(async (projectDirectory) => {
+    console.log(chalk.bold.blue('🚀 Welcome to Rykira Starter App Generator!'));
+
+    let targetDir = projectDirectory;
+
+    if (!targetDir) {
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'projectName',
+          message: 'What is the name of your project?',
+          default: 'my-rykira-app',
+          validate: (input) => {
+            if (/^([a-z0-9\-\_\.]+)$/.test(input)) return true;
+            return 'Project name may only include lower-case letters, numbers, dashes, underscores, and dots.';
+          },
+        },
+      ]);
+      targetDir = answers.projectName;
+    }
+
+    const rootDir = path.resolve(process.cwd(), targetDir);
+
+    if (fs.existsSync(rootDir)) {
+      console.error(chalk.red(`Error: Directory ${targetDir} already exists.`));
+      process.exit(1);
+    }
+
+    const promptAnswers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Project description:',
+        default: 'A modern full-stack application',
+      },
+      {
+        type: 'input',
+        name: 'author',
+        message: 'Author name:',
+        default: 'Rykira User',
+      },
+      {
+        type: 'confirm',
+        name: 'includeAdmin',
+        message: 'Include Admin Panel?',
+        default: true,
+      },
+      {
+        type: 'confirm',
+        name: 'includeApi',
+        message: 'Include Express API?',
+        default: true,
+      },
+    ]);
+
+    const spinner = ora(`Creating project in ${chalk.green(rootDir)}...`).start();
+
+    try {
+      // Copy template files
+      const templateDir = path.resolve(__dirname, '../template');
+      await fs.copy(templateDir, rootDir, {
+        filter: (src) => {
+          // Avoid copying node_modules
+          return !src.includes('node_modules');
+        }
+      });
+
+      // Process Handlebars templates
+      const packageJsonPath = path.join(rootDir, 'package.json');
+      const packageJsonContent = await fs.readFile(packageJsonPath, 'utf-8');
+      const template = Handlebars.compile(packageJsonContent);
+      const result = template({
+        projectName: path.basename(rootDir),
+        projectDescription: promptAnswers.description,
+        authorName: promptAnswers.author,
+      });
+      await fs.writeFile(packageJsonPath, result);
+
+      // Handle Admin Panel removal
+      if (!promptAnswers.includeAdmin) {
+        spinner.text = 'Removing Admin Panel...';
+        await fs.remove(path.join(rootDir, 'apps/admin'));
+        await fs.remove(path.join(rootDir, 'infrastructure/docker/Dockerfile.admin'));
+        // Note: You might need to clean up pnpm-workspace.yaml or turbo.json if strict
+      }
+
+      // Handle API removal
+      if (!promptAnswers.includeApi) {
+        spinner.text = 'Removing Express API...';
+        await fs.remove(path.join(rootDir, 'apps/api'));
+        await fs.remove(path.join(rootDir, 'infrastructure/docker/Dockerfile.api'));
+      }
+      
+      // Update Compose files with project name
+      const composeProdPath = path.join(rootDir, 'infrastructure/docker/compose.prod.yml');
+      const composeDevPath = path.join(rootDir, 'infrastructure/docker/compose.dev.yml');
+      
+      const updateComposeFile = async (filePath) => {
+          if (fs.existsSync(filePath)) {
+              const content = await fs.readFile(filePath, 'utf-8');
+              const composeTemplate = Handlebars.compile(content);
+              const composeResult = composeTemplate({
+                  projectName: path.basename(rootDir)
+              });
+              await fs.writeFile(filePath, composeResult);
+          }
+      };
+
+      await updateComposeFile(composeProdPath);
+      await updateComposeFile(composeDevPath);
+
+
+      spinner.succeed(chalk.green('Project created successfully!'));
+      
+      console.log('\nNext steps:');
+      console.log(chalk.cyan(`  cd ${targetDir}`));
+      console.log(chalk.cyan('  pnpm install'));
+      console.log(chalk.cyan('  cp .env.example .env'));
+      console.log(chalk.cyan('  pnpm dev'));
+
+    } catch (error) {
+      spinner.fail(chalk.red('Failed to create project'));
+      console.error(error);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/deployment.md

@@ -0,0 +1,168 @@
+# Deployment Guide
+
+This guide covers how to deploy the Rykira Starter Package application using Coolify (automated) or manually using Docker and Traefik on a VPS.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Environment Configuration](#environment-configuration)
+- [Option 1: Deploy with Coolify (Recommended)](#option-1-deploy-with-coolify-recommended)
+- [Option 2: Manual Deployment (Docker & Traefik)](#option-2-manual-deployment-docker--traefik)
+- [Post-Deployment Verification](#post-deployment-verification)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+- **Domain Name**: A domain name pointing to your server IP (e.g., `example.com`, `*.example.com`).
+- **VPS/Server**: A server running Ubuntu 22.04/24.04 (minimum 2GB RAM, 2 vCPUs recommended).
+- **Git Repository**: Your project pushed to a Git provider (GitHub, GitLab, etc.).
+
+---
+
+## Environment Configuration
+
+All deployments require a `.env` file. Use the `.env.example` as a template.
+
+### Required Variables
+
+```env
+# Domain Configuration
+DOMAIN=example.com
+ACME_EMAIL=admin@example.com
+
+# Postgres Configuration
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=secure_password_here
+POSTGRES_DB=rykira
+
+# Redis Configuration
+REDIS_PASSWORD=secure_redis_password_here
+
+# Database Connection Strings (Internal Docker Network)
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379
+
+# App Secrets
+NEXTAUTH_SECRET=generate_a_long_random_string
+auth_secret=generate_a_long_random_string
+```
+
+---
+
+## Option 1: Deploy with Coolify (Recommended)
+
+Coolify is an open-source, self-hostable Heroku alternative that makes deployment easy.
+
+### Step 1: Prepare Your Project
+1. Ensure `nixpacks.toml` files exist in `apps/web`, `apps/admin`, and `apps/api` (included in this template).
+2. Push your code to a GitHub repository.
+
+### Step 2: Configure Coolify
+1. **Create a Project** in your Coolify dashboard.
+2. **Add a Resource**: Select **Git Repository** (Private or Public).
+3. **Select Repository**: Choose your project repo.
+
+### Step 3: Add Services
+You will deploy each app as a separate resource, or use a Docker Compose stack.
+
+#### Method A: Docker Compose Stack (Easiest)
+1. In Coolify, select **Docker Compose**.
+2. Paste the contents of `infrastructure/docker/compose.prod.yml`.
+3. **IMPORTANT**: Replace `{{projectName}}` with your actual project name in the Compose file content before pasting, or ensure you set it as a variable if Coolify supports it.
+4. Go to **Environment Variables** in Coolify and add all variables from your `.env` file.
+5. Click **Deploy**.
+
+#### Method B: Individual Services (Nixpacks)
+1. **Web App (`apps/web`)**:
+   - **Build Pack**: Nixpacks
+   - **Base Directory**: `/`
+   - **Build Command**: `pnpm install && pnpm turbo build --filter=web...`
+   - **Start Command**: `pnpm start:web`
+   - **Environment Variables**: Add all required envs.
+   - **Domains**: Set to `https://app.example.com`.
+
+2. **API (`apps/api`)**:
+   - **Build Pack**: Nixpacks
+   - **Base Directory**: `/`
+   - **Build Command**: `pnpm install && pnpm turbo build --filter=api...`
+   - **Start Command**: `node apps/api/dist/index.js`
+   - **Environment Variables**: Add all required envs.
+   - **Domains**: Set to `https://api.example.com`.
+
+3. **Database & Redis**:
+   - Use Coolify's **Databases** tab to provision PostgreSQL and Redis.
+   - Update your App's `DATABASE_URL` and `REDIS_URL` to point to these internal Coolify databases.
+
+---
+
+## Option 2: Manual Deployment (Docker & Traefik)
+
+This method gives you full control using standard Docker Compose and Traefik v3 as a reverse proxy.
+
+### Step 1: Server Setup
+1. SSH into your server.
+2. Clone your repository:
+   ```bash
+   git clone https://github.com/your/repo.git my-app
+   cd my-app
+   ```
+3. Run the setup script to install Docker and configure UFW firewall:
+   ```bash
+   chmod +x infrastructure/scripts/setup-server.sh
+   ./infrastructure/scripts/setup-server.sh
+   ```
+   *You may need to log out and log back in for Docker group changes to take effect.*
+
+### Step 2: Traefik Initialization
+1. Initialize the ACME JSON file for SSL certificates:
+   ```bash
+   chmod +x infrastructure/scripts/init-traefik.sh
+   ./infrastructure/scripts/init-traefik.sh
+   ```
+
+### Step 3: Deploy
+1. Create your `.env` file:
+   ```bash
+   cp .env.example .env
+   nano .env
+   # Fill in your secrets and domain
+   ```
+2. Run the deployment script:
+   ```bash
+   chmod +x infrastructure/scripts/deploy.sh
+   ./infrastructure/scripts/deploy.sh
+   ```
+
+### Step 4: Verify
+- Check running containers: `docker compose ps`
+- View logs: `docker compose logs -f`
+
+---
+
+## Post-Deployment Verification
+
+1. **Check Health**:
+   - Visit `https://api.example.com/health` (should return JSON status).
+2. **Check SSL**:
+   - Visit `https://app.example.com` - ensure lock icon is present.
+3. **Database Connection**:
+   - Verify the API can read/write to the database (try logging in or creating a user).
+
+---
+
+## Troubleshooting
+
+### "Acme.json permission denied"
+- Run: `chmod 600 infrastructure/traefik/acme.json`
+
+### "Gateway Timeout" (504)
+- Check if the app container is running: `docker compose ps`
+- Check logs: `docker compose logs web`
+- Ensure the port in `compose.prod.yml` matches the app's listening port (default 3000 for web, 4000 for api).
+
+### Database Connection Error
+- Ensure `DATABASE_URL` is using the container name `postgres` (not `localhost`) if running inside Docker.
+- Check if Postgres is healthy: `docker compose ps postgres`
+

package/how-to-deploy-package.md

@@ -0,0 +1,132 @@
+# How to Deploy as an NPM Package
+
+This guide explains how to package, test, and publish the `create-rykira-app` CLI tool to the npm registry.
+
+## Prerequisites
+
+- **npm Account**: Create one at [npmjs.com](https://www.npmjs.com/).
+- **Login**: Run `npm login` in your terminal.
+
+## Package Configuration
+
+Ensure `package.json` in the root is configured correctly (already done in this template):
+
+```json
+{
+  "name": "create-rykira-app",
+  "version": "1.0.0",
+  "bin": {
+    "create-rykira-app": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "project.json",
+    "plan.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+  // ... dependencies
+}
+```
+
+**Critical Files to Include**:
+- `bin/`: The executable CLI logic.
+- `template/`: The actual starter project files.
+- `project.json` & `plan.md`: Metadata and docs.
+
+**Critical Files to Ignore (`.npmignore`)**:
+- `node_modules`
+- `.git`
+- `.env`
+- `test-project` (local test folders)
+
+---
+
+## Testing Locally
+
+Before publishing, always test the package locally to ensure it works as expected.
+
+### 1. Link the Package
+Run this in the project root:
+```bash
+npm link
+```
+This makes the `create-rykira-app` command available globally on your machine, pointing to your local code.
+
+### 2. Test the Command
+Go to a temporary directory and run:
+```bash
+create-rykira-app my-test-project
+```
+- Verify all prompts appear.
+- Verify the directory is created.
+- Verify files are copied correctly.
+- Verify Handlebars replacements (Project Name in `package.json`, `docker-compose.yml`) worked.
+- Verify optional modules (Admin, API) were removed if deselected.
+
+### 3. Unlink
+After testing, remove the global link:
+```bash
+npm unlink -g create-rykira-app
+```
+
+---
+
+## Publishing to NPM
+
+### 1. Version Management
+Update the version number in `package.json` according to SemVer:
+```bash
+npm version patch # 1.0.0 -> 1.0.1
+# or
+npm version minor # 1.0.0 -> 1.1.0
+# or
+npm version major # 1.0.0 -> 2.0.0
+```
+
+### 2. Publish
+Run the publish command:
+```bash
+npm publish --access public
+```
+*Note: The `--access public` flag is required for scoped packages (`@username/package`), but good practice generally.*
+
+---
+
+## Quality Assurance Checklist
+
+- [ ] **Clean Install**: `npm install` runs without errors in the generated project.
+- [ ] **Scripts Work**: `pnpm dev`, `pnpm build` work in the generated project.
+- [ ] **Docker Compose**: `docker compose up` works in the generated project.
+- [ ] **Template Integrity**: No `node_modules` or `.git` folders inside the `template/` directory before publishing (npm usually ignores them, but double-check).
+- [ ] **Executable**: `bin/cli.js` has `#!/usr/bin/env node` at the top and is executable (`chmod +x`).
+
+---
+
+## Continuous Delivery (Optional)
+
+You can automate publishing using the included GitHub Actions workflow (`.github/workflows/release.yml` - *to be created if desired*).
+
+Example `release.yml`:
+```yaml
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "create-rykira-app",
+  "version": "1.0.0",
+  "description": "CLI to scaffold Rykira Starter Package",
+  "bin": {
+    "create-rykira-app": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.15",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module"
+}

package/starter-usage.md

@@ -0,0 +1,132 @@
+# Starter Usage Guide
+
+This guide provides a detailed overview of the Rykira Starter Package monorepo structure, development workflow, and how to use the included packages.
+
+## Monorepo Structure
+
+This project uses [Turborepo](https://turbo.build/) and [pnpm workspaces](https://pnpm.io/workspaces) to manage multiple applications and packages in a single repository.
+
+```
+.
+├── apps/                   # Application source code
+│   ├── web/                # Next.js public-facing app
+│   ├── admin/              # Next.js admin dashboard
+│   └── api/                # Express.js backend API
+├── packages/               # Shared libraries
+│   ├── ui/                 # Shadcn/UI component library
+│   ├── eslint-config/      # Shared ESLint configurations
+│   └── typescript-config/  # Shared TypeScript configurations
+├── infrastructure/         # Deployment & DevOps configs
+│   ├── docker/             # Dockerfiles & Compose files
+│   ├── scripts/            # Helper bash scripts
+│   └── traefik/            # Traefik proxy config
+└── package.json            # Root configuration
+```
+
+---
+
+## Setting Up Development Environment
+
+### Prerequisites
+- Node.js >= 18
+- pnpm >= 9 (`npm install -g pnpm`)
+- Docker & Docker Compose (optional, for local DB/Redis)
+
+### Installation
+
+1. **Install Dependencies**:
+   ```bash
+   pnpm install
+   ```
+
+2. **Environment Variables**:
+   Copy the example file:
+   ```bash
+   cp .env.example .env
+   ```
+   *Note: The default `.env` is configured to work out-of-the-box with the local Docker setup.*
+
+3. **Start Infrastructure (DB & Redis)**:
+   Start Postgres and Redis containers in the background:
+   ```bash
+   ./infrastructure/scripts/dev.sh
+   ```
+   *Or manually: `docker compose -f infrastructure/docker/compose.dev.yml up -d`*
+
+4. **Start Applications**:
+   Run all apps in development mode:
+   ```bash
+   pnpm dev
+   ```
+   
+   - **Web**: http://localhost:3000
+   - **Admin**: http://localhost:3001
+   - **API**: http://localhost:4000
+
+---
+
+## Package Usage Guide
+
+### 1. UI Package (`packages/ui`)
+A shared component library built with [Shadcn/UI](https://ui.shadcn.com/) and Tailwind CSS v4.
+
+- **Location**: `packages/ui/src/components`
+- **Usage in Apps**:
+  ```tsx
+  import { Button } from "@workspace/ui/components/button";
+  
+  export default function Page() {
+    return <Button>Click me</Button>;
+  }
+  ```
+- **Adding New Components**:
+  Currently, you manually add Shadcn components to `packages/ui/src/components`.
+  *Tip: You can run `npx shadcn@latest add [component]` inside the `packages/ui` folder if configured.*
+
+### 2. Apps (`web`, `admin`)
+Next.js 15 applications using the App Router.
+
+- **Styling**: Tailwind CSS v4 is configured. It imports the shared config from `@workspace/ui`.
+- **Fetching Data**:
+  You can fetch data directly from the DB (Server Components) or call the Express API.
+
+### 3. API (`apps/api`)
+Express.js backend with TypeScript.
+
+- **Endpoints**: Defined in `src/server.ts` or router files.
+- **Validation**: Uses `zod` for request validation.
+- **Database**: Connects to Postgres using `pg` or an ORM (Prisma/Drizzle recommended to be added).
+
+---
+
+## Development Workflow
+
+### Adding Dependencies
+To add a dependency to a specific app (e.g., `web`):
+```bash
+pnpm add [package-name] --filter web
+```
+To add to the root workspace:
+```bash
+pnpm add [package-name] -w
+```
+
+### Running Commands
+- **Build all**: `pnpm build`
+- **Lint all**: `pnpm lint`
+- **Typecheck**: `pnpm typecheck`
+- **Run command on specific app**: `pnpm --filter web run [command]`
+
+### Database Management
+The starter uses a raw Docker Postgres container.
+- **Connect**: Use a GUI like DBeaver or TablePlus with credentials from `.env`.
+- **Persistence**: Data is stored in the `postgres_data` Docker volume.
+
+---
+
+## Best Practices
+
+1. **Shared Code**: Put reusable logic (utilities, types, constants) in a `packages/core` or `packages/lib` package (create one if needed) to share between API and Frontend.
+2. **Environment Variables**: Always validate env vars (e.g., using `t3-env` or `zod`) at the start of your application.
+3. **Type Safety**: Share TypeScript interfaces/types via a shared package to ensure contract safety between API and Frontend.
+

package/template/.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+.git
+.gitignore
+.env
+.env.local
+.next
+dist
+coverage
+turbo
+Dockerfile
+docker-compose.yml

package/template/.env.example

@@ -0,0 +1,20 @@
+# Domain Configuration
+DOMAIN=localhost
+# ACME Email for Let's Encrypt
+ACME_EMAIL=admin@example.com
+
+# Postgres Configuration
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=rykira
+
+# Redis Configuration
+REDIS_PASSWORD=
+
+# Database Connection Strings (Docker Internal)
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+REDIS_URL=redis://redis:6379
+
+# App Secrets (Generate strong random strings for production)
+NEXTAUTH_SECRET=changeme
+auth_secret=changeme

package/template/.eslintrc.js

@@ -0,0 +1,13 @@
+// Root-level ESLint config for a Turborepo workspace.
+// App/package lint rules live in each workspace's eslint.config.js.
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  root: true,
+  ignorePatterns: [
+    "**/node_modules/**",
+    "**/.next/**",
+    "**/dist/**",
+    "**/.turbo/**",
+    "**/coverage/**",
+  ],
+}