@kevinmarrec/create-app 0.8.0 → 0.10.0

package/README.md

@@ -16,4 +16,8 @@ CLI that scaffolds an opinionated [Bun](https://bun.sh) & [Vue](https://vuejs.or
 
 ```sh
 bun create @kevinmarrec/app
+# OR
+bunx @kevinmarrec/create-app
 ```
+
+After scaffolding, see the generated `README.md` in your project root for detailed setup instructions, including environment configuration, Docker setup, and development workflows.

package/dist/index.js

@@ -8,7 +8,7 @@ import { x } from "tinyexec";
 import fs from "node:fs/promises";
 
 //#region package.json
-var version = "0.8.0";
+var version = "0.10.0";
 
 //#endregion
 //#region src/utils/fs.ts

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kevinmarrec/create-app",
   "type": "module",
-  "version": "0.8.0",
-  "packageManager": "bun@1.3.1",
+  "version": "0.10.0",
+  "packageManager": "bun@1.3.2",
   "description": "CLI that scaffolds an opinionated Bun & Vue fullstack application.",
   "author": "Kevin Marrec <kevin@marrec.io>",
   "license": "MIT",
@@ -18,8 +18,8 @@
   ],
   "workspaces": [
     "template",
-    "template/client",
-    "template/server"
+    "template/api",
+    "template/app"
   ],
   "bin": {
     "create-app": "dist/index.js"
@@ -39,7 +39,7 @@
     "check:unused": "knip -n",
     "lint": "bun run check:eslint && bun run check:stylelint",
     "lint:inspect": "bunx @eslint/config-inspector",
-    "playground": "bun --cwd template dev",
+    "playground": "bun run scripts/transform-compose.ts | docker compose -f -",
     "release": "bumpp",
     "update": "bunx taze -I -rwi",
     "test": "vitest",
@@ -53,20 +53,18 @@
   },
   "devDependencies": {
     "@faker-js/faker": "^10.1.0",
-    "@kevinmarrec/eslint-config": "^1.5.4",
-    "@kevinmarrec/stylelint-config": "^1.5.4",
-    "@kevinmarrec/tsconfig": "^1.5.4",
-    "@types/bun": "^1.3.1",
-    "@vitest/coverage-v8": "^4.0.7",
+    "@kevinmarrec/eslint-config": "^1.5.6",
+    "@kevinmarrec/stylelint-config": "^1.5.6",
+    "@kevinmarrec/tsconfig": "^1.5.6",
+    "@types/bun": "^1.3.2",
+    "@vitest/coverage-v8": "^4.0.9",
     "bumpp": "^10.3.1",
     "eslint": "^9.39.1",
-    "filesize": "^11.0.13",
-    "knip": "^5.67.1",
+    "knip": "^5.69.1",
     "stylelint": "^16.25.0",
-    "tinyglobby": "^0.2.15",
-    "tsdown": "^0.16.0",
+    "tsdown": "^0.16.4",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.7",
-    "vue-tsc": "^3.1.3"
+    "vitest": "^4.0.9",
+    "vue-tsc": "^3.1.4"
   }
 }

package/template/.docker/traefik/bin/install_cert

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -e
+
+CERTS_DIR="$(cd "$(dirname "$0")/../certs" && pwd)"
+
+if ! command -v mkcert >/dev/null 2>&1; then
+  echo "Error: mkcert is not installed." >&2
+  echo "Please install mkcert before running this script." >&2
+  echo "See https://github.com/FiloSottile/mkcert#installation for installation instructions." >&2
+  exit 1
+fi
+
+mkdir -p "$CERTS_DIR"
+
+mkcert -install 2> /dev/null
+
+mkcert -cert-file "$CERTS_DIR/dev.localhost.crt" -key-file "$CERTS_DIR/dev.localhost.key" "dev.localhost" "*.dev.localhost"

package/template/.docker/traefik/bin/uninstall_cert

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e
+
+CERTS_DIR="$(cd "$(dirname "$0")/../certs" && pwd)"
+
+mkcert -uninstall 2> /dev/null || true
+
+rm -f "$CERTS_DIR"/*.crt "$CERTS_DIR"/*.key 2> /dev/null || true

package/template/.docker/traefik/dynamic/tls.yml

@@ -0,0 +1,4 @@
+tls:
+  certificates:
+    - certFile: /certs/dev.localhost.crt
+      keyFile: /certs/dev.localhost.key

package/template/.github/scripts/build-stats.md.ts

@@ -0,0 +1,71 @@
+import * as fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { parseArgs } from 'node:util'
+
+import { filesize } from 'filesize'
+import { x } from 'tinyexec'
+import { glob } from 'tinyglobby'
+
+interface FileStats {
+  file: string
+  size: number
+}
+
+async function getFileStats(directory: string) {
+  const fileStats: FileStats[] = []
+
+  for (const file of await glob(['**/*'], { cwd: directory })) {
+    const size = fs.statSync(path.join(directory, file)).size
+    fileStats.push({
+      file,
+      size,
+    })
+  }
+
+  fileStats.sort((a, b) => {
+    // Sort so that files starting with 'assets/' come first
+    if (a.file.startsWith('assets/') && !b.file.startsWith('assets/')) return -1
+    if (!a.file.startsWith('assets/') && b.file.startsWith('assets/')) return 1
+
+    // Within that, files ending with '.js' come first
+    if (a.file.endsWith('.js') && !b.file.endsWith('.js')) return -1
+    if (!a.file.endsWith('.js') && b.file.endsWith('.js')) return 1
+
+    // Otherwise sort alphabetically
+    return a.file.localeCompare(b.file)
+  })
+
+  return fileStats
+}
+
+async function generateFileStatsMarkdown(directory: string) {
+  const fileStats = await getFileStats(directory)
+  return [
+    '| File | Size |',
+    '| :--- | ---: |',
+    ...fileStats.map(file => `| ${file.file} | ${filesize(file.size)} |`),
+  ].join('\n')
+}
+
+async function main() {
+  const { positionals: [directory] } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+  })
+
+  if (!directory) {
+    process.stdout.write('Usage: analyze <directory>\n')
+    process.exit(1)
+  }
+
+  await x('bun', ['run', 'build'], { nodeOptions: { cwd: directory } })
+
+  const markdownTable = await generateFileStatsMarkdown(path.join(directory, 'dist'))
+  process.stdout.write(`${markdownTable}\n`)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/template/.github/workflows/ci.yml

@@ -24,3 +24,19 @@ jobs:
 
       - name: Type check
         run: bun run check:types
+  project-size:
+    name: Analyze project build size
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Bun
+        uses: kevinmarrec/workflows/setup-bun@v1
+
+      - name: Check api build size
+        run: |
+          echo "## API" >> $GITHUB_STEP_SUMMARY
+          bun run .github/scripts/build-stats.md.ts api >> $GITHUB_STEP_SUMMARY
+
+      - name: Check app build size
+        run: |
+          echo "## App" >> $GITHUB_STEP_SUMMARY
+          bun run .github/scripts/build-stats.md.ts app >> $GITHUB_STEP_SUMMARY

package/template/.gitignore

@@ -1,4 +1,6 @@
+*.crt
 *.db*
+*.key
 *.local
 *.log
 *.sqlite

package/template/.npmrc

@@ -1,4 +1,3 @@
 public-hoist-pattern[]=@types*
 public-hoist-pattern[]=*eslint*
 public-hoist-pattern[]=*stylelint*
-public-hoist-pattern[]=pino-pretty

package/template/.vscode/settings.json

@@ -67,6 +67,6 @@
   "i18n-ally.enabledFrameworks": ["vue"],
   "i18n-ally.keystyle": "nested",
   "i18n-ally.localesPaths": [
-    "client/src/locales"
+    "app/src/locales"
   ]
 }

package/template/README.md

@@ -0,0 +1,330 @@
+# Project Template
+
+A full-stack application template with a Vue.js frontend, Bun-based API backend, PostgreSQL database, and Docker Compose setup for local development.
+
+## Overview
+
+This template provides a modern full-stack application structure with:
+
+- **Frontend (app)**: Vue 3 application with Vite, UnoCSS, TypeScript, and TanStack Query
+- **Backend (api)**: Bun-based API server with oRPC, Better Auth, and Drizzle ORM
+- **Database**: PostgreSQL with Drizzle migrations
+- **Infrastructure**: Docker Compose with Traefik reverse proxy, PostgreSQL, and Metabase
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) (v1.3 or later)
+- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
+- [Node.js LTS](https://nodejs.org/en/download/) (for compatibility)
+- [mkcert](https://github.com/FiloSottile/mkcert) (for local TLS certificates)
+
+## Project Structure
+
+```
+project/
+├── api/                   # Backend API server
+│   ├── src/
+│   │   ├── auth/            # Authentication setup (Better Auth)
+│   │   ├── database/        # Database schema and migrations (Drizzle)
+│   │   ├── orpc/            # Router definitions (oRPC)
+│   │   ├── env.ts           # Environment variable loading and validation (Valibot)
+│   │   └── main.ts          # API entry point
+│   └── package.json
+├── app/                   # Frontend Vue application
+│   ├── src/
+│   │   ├── components/      # Vue components
+│   │   ├── composables/     # Vue composables (auth, etc.)
+│   │   ├── lib/             # Library utilities (oRPC client)
+│   │   └── main.ts          # App entry point
+│   └── package.json
+├── compose.yaml              # Docker Compose configuration
+└── package.json              # Root workspace configuration
+```
+
+## Getting Started
+
+### 1. Install Dependencies
+
+```bash
+bun install
+```
+
+### 2. Set Up Environment Variables
+
+> **Note**: If `.env.development` (API) or `.env` (App) files already exist in the template, you may skip this step. Otherwise, create them as described below.
+
+#### API Environment Variables
+
+Create a `.env.development` file in the `api/` directory with the following variables:
+
+```bash
+# api/.env.development
+AUTH_SECRET=your-secret-key-here
+DATABASE_URL=postgresql://user:password@postgres:5432/app
+ALLOWED_ORIGINS=https://app.dev.localhost
+LOG_LEVEL=info
+HOST=0.0.0.0
+PORT=4000
+```
+
+**Required variables:**
+
+- `AUTH_SECRET` - Secret key for authentication encryption
+- `DATABASE_URL` - PostgreSQL connection string
+
+**Optional variables:**
+
+- `ALLOWED_ORIGINS` - Comma-separated list of allowed CORS origins (default: empty)
+- `LOG_LEVEL` - Logging level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`, or `silent` (default: `info`)
+- `HOST` - Server host (default: `0.0.0.0`)
+- `PORT` - Server port (default: `4000`)
+
+#### App Environment Variables
+
+Create a `.env` file in the `app/` directory with the following variables:
+
+```bash
+# app/.env
+VITE_API_URL=https://api.dev.localhost
+```
+
+**Required variables:**
+
+- `VITE_API_URL` - API base URL for the frontend
+
+### 3. Set Up Local TLS Certificates
+
+To access the HTTPS URLs (`https://*.dev.localhost`), you need to set up trusted local TLS certificates using [mkcert](https://github.com/FiloSottile/mkcert).
+
+Check their [installation guide](https://github.com/FiloSottile/mkcert#installation) for detailed instructions on installing mkcert.
+
+Then, run the following command to generate the certificates:
+
+```bash
+.docker/traefik/bin/install_cert
+```
+
+This will generate the certificates in `.docker/traefik/certs/` and install the mkcert root CA into your system trust store.
+
+> [!IMPORTANT]
+> If your system is running on WSL and you are using Firefox or Zen Browser, **you must import the mkcert root CA into your browser trust store.**
+>
+> 1. Find the root CA file path:
+>    ```bash
+>    echo "wslpath -w $(mkcert -CAROOT)/rootCA.pem"
+>    # \\wsl.localhost\Ubuntu\home\user\.local\share\mkcert\rootCA.pem
+>    ```
+> 2. Import the root CA file into your browser trust store:
+>    - **Settings** -> **Privacy & Security**.
+>    - **Certificates** -> **View Certificates...**
+>    - **Authorities** tab -> **Import...**
+>    - Select the rootCA.pem file (using the path found above)
+>    - Check **"Trust this CA to identify websites"**
+>    - Click **OK**
+
+### 4. Start Docker Services and Access the Application
+
+Start all services (Traefik, PostgreSQL, Metabase, API, and App):
+
+```bash
+docker compose up -d
+```
+
+Once the services are running, you can access:
+
+- Frontend: https://app.dev.localhost
+- API: https://api.dev.localhost
+- Traefik Dashboard: https://traefik.dev.localhost
+- Metabase: https://metabase.dev.localhost
+
+### 5. Stopping Services
+
+To stop all Docker services:
+
+```bash
+docker compose down
+```
+
+To stop and remove volumes (⚠️ this will delete database data):
+
+```bash
+docker compose down -v
+```
+
+## Development
+
+### Running Services Locally (without Docker)
+
+You can also run the services locally without Docker. Note that you'll still need PostgreSQL running (either locally or via Docker).
+
+#### API Server
+
+```bash
+cd api
+bun run dev
+```
+
+The API will run on `http://localhost:4000` (or the port specified in `PORT`).
+
+#### Frontend App
+
+```bash
+cd app
+bun run dev
+```
+
+The app will run on `http://localhost:5173` (Vite default port).
+
+### Database Management
+
+#### Generate Migrations
+
+After modifying the database schema in `api/src/database/schema/`, generate migrations:
+
+```bash
+cd api
+bun run db:generate
+```
+
+#### Run Migrations
+
+Migrations run automatically when starting the API in dev mode. To run manually:
+
+```bash
+cd api
+bun run db:migrate
+```
+
+## Available Scripts
+
+### Root Level Scripts
+
+- `bun run check` - Run all checks (ESLint, Stylelint, unused dependencies, TypeScript)
+- `bun run lint` - Run linting (ESLint and Stylelint)
+- `bun run lint:inspect` - Open ESLint config inspector
+- `bun run update` - Update dependencies
+
+### API Scripts (`cd api`)
+
+- `bun run dev` - Start development server with hot reload
+- `bun run build` - Build production binary
+- `bun run db:generate` - Generate database migrations
+- `bun run db:migrate` - Run database migrations
+
+### App Scripts (`cd app`)
+
+- `bun run dev` - Start development server with HMR (Hot Module Replacement)
+- `bun run build` - Build for production (static site)
+- `bun run build:analyze` - Build with bundle analyzer
+- `bun run preview` - Preview production build
+
+## Docker Compose Services
+
+### Traefik
+
+Reverse proxy and load balancer that handles:
+
+- HTTPS termination
+- SSL certificate management (requires certificates in `.docker/traefik/certs/`)
+- Routing to services based on hostnames
+- Dashboard accessible at https://traefik.dev.localhost
+
+### PostgreSQL
+
+Database service with:
+
+- Default database: `app`
+- Default user: `user`
+- Default password: `password`
+- Port: `5432`
+- Persistent volume: `postgres_data`
+
+### Metabase
+
+Business intelligence tool for data visualization and analytics with:
+
+- Persistent volume: `metabase_data`
+- Accessible via Traefik at https://metabase.dev.localhost (runs on port `3000` internally)
+
+### API
+
+Backend API service running Bun with:
+
+- Hot reload enabled
+- Automatic database migrations on startup
+- Health check endpoint: `/health`
+- Auth endpoints: `/auth/*`
+- RPC endpoints: `/rpc/*`
+- Accessible via Traefik at https://api.dev.localhost (runs on port `4000` internally)
+
+### App
+
+Frontend Vue application with:
+
+- Vite dev server
+- Hot module replacement
+- Accessible via Traefik at https://app.dev.localhost (runs on port `5173` internally)
+
+## Environment Variables
+
+For detailed environment variable setup, see [Set Up Environment Variables](#2-set-up-environment-variables) in the Getting Started section.
+
+**Quick reference:**
+
+- **API** (`.env.development`): `AUTH_SECRET` (required), `DATABASE_URL` (required), `ALLOWED_ORIGINS`, `LOG_LEVEL`, `HOST`, `PORT`
+- **App** (`.env`): `VITE_API_URL` (required)
+
+## Building for Production
+
+### Build API
+
+```bash
+cd api
+bun run build
+```
+
+This creates a compiled binary at `api/dist/api`.
+
+### Build App
+
+```bash
+cd app
+bun run build
+```
+
+This creates a static site in `app/dist/`.
+
+## Troubleshooting
+
+### Port Already in Use
+
+If ports 80, 443, or 5432 are already in use, modify the port mappings in `compose.yaml`.
+
+### SSL Certificate Warnings
+
+If you see SSL certificate warnings when accessing `https://*.dev.localhost` URLs, ensure you have completed the [Local TLS Setup](#3-set-up-local-tls-certificates) to generate trusted certificates using mkcert.
+
+**Note**: Without proper certificates, Traefik may fail to start or services may not be accessible via HTTPS.
+
+### Service Logs
+
+To view logs for a specific service:
+
+```bash
+docker compose logs -f <service-name>
+```
+
+For example:
+
+- `docker compose logs -f api` - View API logs
+- `docker compose logs -f app` - View app logs
+- `docker compose logs -f traefik` - View Traefik logs
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Language**: TypeScript
+- **Frontend**: Vue 3, Vite, UnoCSS, TanStack Query
+- **Backend**: Bun, oRPC, Better Auth, Drizzle ORM
+- **Database**: PostgreSQL
+- **Infrastructure**: Docker Compose, Traefik

package/template/api/.env.development

@@ -0,0 +1,4 @@
+ALLOWED_ORIGINS="https://app.dev.localhost"
+AUTH_SECRET="D0QykrmzDgVrP4GCKkFPT1CB1UplFk4bhIJk92SUtSQ="
+DATABASE_URL="postgresql://user:password@postgres:5432/app"
+NODE_ENV="development"

package/template/{server → api}/package.json

@@ -1,24 +1,25 @@
 {
-  "name": "server",
+  "name": "api",
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "bun --watch --no-clear-screen src/main.ts",
-    "build": "bun build src/main.ts --compile --minify --sourcemap --outfile dist/server",
+    "dev": "bun run db:migrate 1> /dev/null && bun --watch --no-clear-screen src/main.ts | pino-pretty",
+    "build": "bun build src/main.ts --compile --minify --sourcemap --outfile dist/api",
     "db:generate": "bun --bun run drizzle-kit generate --config src/database/drizzle/config.ts",
     "db:migrate": "bun --bun run drizzle-kit migrate --config src/database/drizzle/config.ts"
   },
   "dependencies": {
-    "@orpc/server": "^1.10.4",
+    "@libsql/client": "^0.15.15",
+    "@orpc/server": "^1.11.2",
     "better-auth": "^1.3.34",
     "drizzle-orm": "^0.44.7",
     "pino": "^10.1.0",
     "valibot": "^1.1.0"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.3.13",
-    "@types/bun": "^1.3.1",
-    "drizzle-kit": "^0.31.6",
+    "@types/bun": "^1.3.2",
+    "drizzle-kit": "^0.31.7",
+    "pg": "^8.16.3",
     "pino-pretty": "^13.1.2"
   }
 }

package/template/{server → api}/src/auth/index.ts

@@ -2,10 +2,13 @@ import { betterAuth } from 'better-auth'
 import { type DB, drizzleAdapter } from 'better-auth/adapters/drizzle'
 import type { BaseLogger } from 'pino'
 
+import { env } from '../env'
+
 export function createBetterAuth({ db, logger }: { db: DB, logger: BaseLogger }) {
   return betterAuth({
     basePath: '/auth',
-    trustedOrigins: import.meta.env.ALLOWED_ORIGINS.split(','),
+    secret: env.auth.secret,
+    trustedOrigins: env.cors.allowedOrigins,
     database: drizzleAdapter(db, {
       provider: 'pg',
       usePlural: true,

package/template/{server → api}/src/database/drizzle/config.ts

@@ -1,10 +1,11 @@
 import { defineConfig } from 'drizzle-kit'
 
+import { env } from '../../env'
+
 export default defineConfig({
   casing: 'snake_case',
   dialect: 'postgresql',
-  driver: 'pglite',
-  dbCredentials: { url: import.meta.env.DATABASE_URL },
+  dbCredentials: { url: env.database.url },
   schema: 'src/database/schema',
   out: 'src/database/migrations',
 })

package/template/{server → api}/src/database/index.ts

@@ -1,11 +1,13 @@
-import { PGlite } from '@electric-sql/pglite'
-import { logger } from '@server/utils/logger'
-import { drizzle } from 'drizzle-orm/pglite'
+import { drizzle } from 'drizzle-orm/bun-sql'
 
+import { env } from '../env'
+import { logger } from '../utils/logger'
 import * as schema from './schema'
 
 export const db = drizzle({
-  client: new PGlite(import.meta.env.DATABASE_URL),
+  connection: {
+    url: env.database.url,
+  },
   casing: 'snake_case',
   schema,
   logger: {