@kevinmarrec/create-app 0.10.1 → 0.12.0

package/template/README.md

@@ -1,15 +1,36 @@
 # 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.
+A full-stack application template with Vue.js frontend, Bun-based API backend, and PostgreSQL database.
 
-## Overview
-
-This template provides a modern full-stack application structure with:
+## Tech Stack
 
-- **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
+### Core Stack
+
+- [Bun](https://bun.sh/) as package manager & runtime
+- [TypeScript](https://www.typescriptlang.org/) as the language
+- [Vue 3](https://vuejs.org/) as frontend framework
+- [Vite](https://vitejs.dev/) as build tool
+- [Vite SSG](https://github.com/antfu-collective/vite-ssg) for static site generation
+- [UnoCSS](https://unocss.dev/) for styling
+- [TanStack Query](https://tanstack.com/query/latest) for data fetching
+- [Unhead](https://unhead.unjs.io/) for head management
+- [Vue I18n](https://github.com/kevinmarrec/vue-i18n) for internationalization
+- [oRPC](https://orpc.dev/) for API layer
+- [Better Auth](https://www.better-auth.com/) for authentication
+- [Pino](https://getpino.io/) for logging
+- [Drizzle ORM](https://orm.drizzle.team/) as SQL-first TypeScript ORM
+- [Valibot](https://valibot.dev/) for validation
+- [PostgreSQL](https://www.postgresql.org/) as database
+- [Docker Compose](https://docs.docker.com/compose/) & [Traefik](https://traefik.io/) for infrastructure
+
+### Development Tools
+
+- [ESLint](https://eslint.org/) & [Stylelint](https://stylelint.io/) for linting
+- [Knip](https://knip.dev/) for detecting unused dependencies, exports, and files
+- [Metabase](https://www.metabase.com/) for Business Intelligence (BI)
+- [Drizzle Studio](https://gateway.drizzle.team/) for database management (web GUI)
+- [Umami](https://umami.is/) for web analytics
+- [Mailpit](https://mailpit.axllent.org/) for email testing
 
 ## Prerequisites
 
@@ -27,14 +48,18 @@ project/
 │   │   ├── auth/            # Authentication setup (Better Auth)
 │   │   ├── database/        # Database schema and migrations (Drizzle)
 │   │   ├── orpc/            # Router definitions (oRPC)
+│   │   ├── utils/           # Utility functions (CORS, logger, etc.)
 │   │   ├── env.ts           # Environment variable loading and validation (Valibot)
 │   │   └── main.ts          # API entry point
 │   └── package.json
 ├── app/                   # Frontend Vue application
+│   ├── public/             # Public static assets
 │   ├── src/
 │   │   ├── components/      # Vue components
 │   │   ├── composables/     # Vue composables (auth, etc.)
 │   │   ├── lib/             # Library utilities (oRPC client)
+│   │   ├── locales/         # Internationalization files (i18n)
+│   │   ├── App.vue          # Main Vue component
 │   │   └── main.ts          # App entry point
 │   └── package.json
 ├── compose.yaml              # Docker Compose configuration
@@ -51,60 +76,40 @@ 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:
+#### API (`api/.env.development`)
 
 ```bash
-# api/.env.development
+ALLOWED_ORIGINS=https://app.dev.localhost
 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`)
+**Required:** `ALLOWED_ORIGINS`, `AUTH_SECRET`, `DATABASE_URL`
 
-#### App Environment Variables
+**Optional:** `LOG_LEVEL` (default: `info`), `HOST` (default: `0.0.0.0`), `PORT` (default: `4000`)
 
-Create a `.env` file in the `app/` directory with the following variables:
+#### App (`app/.env`)
 
 ```bash
-# app/.env
 VITE_API_URL=https://api.dev.localhost
+VITE_ANALYTICS_URL=https://analytics.dev.localhost
+VITE_ANALYTICS_WEBSITE_ID=your-website-id-here
 ```
 
-**Required variables:**
-
-- `VITE_API_URL` - API base URL for the frontend
+**Required:** `VITE_API_URL`, `VITE_ANALYTICS_URL`, `VITE_ANALYTICS_WEBSITE_ID`
 
 ### 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:
+Install [mkcert](https://github.com/FiloSottile/mkcert), then run:
 
 ```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.
+This generates certificates in `.docker/traefik/certs/` and installs the 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.**
@@ -122,209 +127,103 @@ This will generate the certificates in `.docker/traefik/certs/` and install the
 >    - 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):
+### 4. Start Services
 
 ```bash
-docker compose up -d
+bun run dev up -d
 ```
 
-Once the services are running, you can access:
+**Services:**
 
 - Frontend: https://app.dev.localhost
 - API: https://api.dev.localhost
-- Traefik Dashboard: https://traefik.dev.localhost
+- Traefik: https://traefik.dev.localhost
 - Metabase: https://metabase.dev.localhost
+- Drizzle Studio: https://studio.dev.localhost (password: `foobar`)
+- Umami: https://analytics.dev.localhost
+- Mailpit: https://mail.dev.localhost
 
-### 5. Stopping Services
-
-To stop all Docker services:
-
-```bash
-docker compose down
-```
-
-To stop and remove volumes (⚠️ this will delete database data):
+**Stop services:**
 
 ```bash
-docker compose down -v
+bun run dev down          # Stop services
+bun run dev down -v       # Stop and remove volumes (⚠️ deletes data)
 ```
 
-## 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).
+## Scripts
 
-#### API Server
+**Root:**
 
-```bash
-cd api
-bun run dev
-```
-
-The API will run on `http://localhost:4000` (or the port specified in `PORT`).
+- `bun run dev` - Docker Compose shortcut
+- `bun run check` - Run all checks (lint, typecheck, unused deps)
+- `bun run lint` - Run ESLint and Stylelint
+- `bun run update` - Update dependencies
 
-#### Frontend App
+**API (`cd api`):**
 
-```bash
-cd app
-bun run dev
-```
+- `bun run dev` - Dev server (auto-migrations, hot reload)
+- `bun run build` - Build production binary
+- `bun run db:generate` - Generate migrations
+- `bun run db:migrate` - Run migrations
 
-The app will run on `http://localhost:5173` (Vite default port).
+**App (`cd app`):**
 
-### Database Management
+- `bun run dev` - Dev server (HMR)
+- `bun run build` - Build for production
+- `bun run build:analyze` - Build with bundle analyzer
+- `bun run preview` - Preview production build
 
-#### Generate Migrations
+## Database Migrations
 
 After modifying the database schema in `api/src/database/schema/`, generate migrations:
 
 ```bash
-cd api
-bun run db:generate
+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
+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`)
+## Docker Services
 
-- `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:
+- **Traefik** - Reverse proxy (HTTPS termination, routing)
+- **PostgreSQL** - Database (`postgresql://user:password@postgres:5432/app`, port `5432`)
+- **API** - Backend (`/health`, `/auth/*`, `/rpc/*`)
+- **App** - Frontend (Vue + Vite)
+- **Metabase** - BI tool
+- **Drizzle Studio** - DB management (password: `foobar`)
+- **Umami** - Analytics
+- **Mailpit** - Email testing (REST API at `/api/v1/`)
 
-- 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)
+## Production Build
 
-### 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
+**API:**
 
 ```bash
-cd api
-bun run build
+cd api && bun run build
 ```
 
-This creates a compiled binary at `api/dist/api`.
+Output: `api/dist/api`
 
-### Build App
+**App:**
 
 ```bash
-cd app
-bun run build
+cd app && bun run build
 ```
 
-This creates a static site in `app/dist/`.
+Output: `app/dist/`
 
 ## Troubleshooting
 
-### Port Already in Use
-
-If ports 80, 443, or 5432 are already in use, modify the port mappings in `compose.yaml`.
+**Port conflicts:** Modify port mappings in `compose.yaml` if ports 80, 443, or 5432 are in use.
 
-### SSL Certificate Warnings
+**SSL warnings:** Complete [TLS setup](#3-set-up-local-tls-certificates). Without certificates, Traefik may fail to start.
 
-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:
+**View logs:**
 
 ```bash
-docker compose logs -f <service-name>
+bun run dev logs -f <service-name>  # e.g., api, app, traefik
 ```
-
-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/Dockerfile

@@ -0,0 +1,45 @@
+# --- Stage 1: Dependency Installation & Caching (The Build Stage) ---
+
+ARG TARGETARCH
+
+# Use a bun-alpine image for a fast build environment
+FROM oven/bun:1.3.3-slim AS build
+
+# Set the working directory inside the container
+WORKDIR /build
+
+# 1. Copy necessary files for the cache layer
+# IMPORTANT: The path to the root lock file is relative to the Docker build context.
+# If you run 'docker build -f api/Dockerfile .', the context is the root (.).
+# If you run 'docker build api', the context is api (and this approach fails).
+# ASSUMPTION: You are running the build command from the root level.
+
+# Copy workspace root files (This ensures the locked install)
+COPY package.json bun.lock ./
+
+# Copy service package.json files
+COPY api/package.json ./api/package.json
+COPY app/package.json ./app/package.json
+
+# 2. Perform a frozen install
+RUN bun install --filter api --frozen-lockfile
+
+# Copy API source code
+COPY api/ ./api/
+
+# 3. Build the API
+RUN bun --cwd api build --target bun-linux-$TARGETARCH-modern
+
+# --- Stage 2: Final Image (The Runtime Stage) ---
+
+# Use a minimal image for production (less attack surface, smaller size)
+FROM debian:trixie-slim
+
+# Copy the compiled binary from builder stage
+COPY --from=build /build/api/dist/api /usr/local/bin/
+
+# Expose port
+EXPOSE 4000
+
+# Run the binary
+ENTRYPOINT ["/usr/local/bin/api"]

package/template/api/package.json

@@ -10,16 +10,18 @@
   },
   "dependencies": {
     "@libsql/client": "^0.15.15",
-    "@orpc/server": "^1.11.2",
-    "better-auth": "^1.3.34",
+    "@orpc/server": "^1.12.0",
+    "better-auth": "^1.4.3",
     "drizzle-orm": "^0.44.7",
     "pino": "^10.1.0",
-    "valibot": "^1.1.0"
+    "valibot": "^1.2.0"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.2",
+    "@kevinmarrec/tsconfig": "^1.5.8",
+    "@types/bun": "^1.3.3",
     "drizzle-kit": "^0.31.7",
     "pg": "^8.16.3",
-    "pino-pretty": "^13.1.2"
+    "pino-pretty": "^13.1.2",
+    "typescript": "~5.9.3"
   }
 }

package/template/api/src/env.ts

@@ -2,16 +2,29 @@ import * as v from 'valibot'
 
 const schema = v.object({
   auth: v.object({
-    secret: v.string(),
+    secret: v.pipe(
+      v.string(),
+      v.nonEmpty(),
+    ),
   }),
   cors: v.object({
     allowedOrigins: v.pipe(
-      v.optional(v.string(), ''),
+      v.string(),
+      v.nonEmpty(),
       v.transform(input => input.split(',').filter(Boolean)),
+      v.array(v.pipe(
+        v.string(),
+        v.trim(),
+        v.startsWith('https://'),
+      )),
     ),
   }),
   database: v.object({
-    url: v.string(),
+    url: v.pipe(
+      v.string(),
+      v.nonEmpty(),
+      v.startsWith('postgresql://'),
+    ),
   }),
   log: v.object({
     level: v.optional(v.union([
@@ -28,8 +41,8 @@ const schema = v.object({
     host: v.optional(v.string(), '0.0.0.0'),
     port: v.pipe(
       v.optional(v.string(), '4000'),
-      v.decimal(),
-      v.transform(input => Number(input)),
+      v.digits(),
+      v.toNumber(),
     ),
   }),
 })

package/template/api/src/utils/cors.ts

@@ -13,7 +13,7 @@ export function cors(handler: (req: Request) => Promise<Response>) {
       : await handler(req)
 
     if (req.method === 'OPTIONS') {
-      response.headers.append('Access-Control-Allow-Headers', 'Content-Type')
+      response.headers.append('Access-Control-Allow-Headers', 'Content-Type, Authorization, User-Agent')
       response.headers.append('Access-Control-Allow-Methods', 'GET, HEAD, PUT, POST, DELETE, PATCH')
       response.headers.append('Access-Control-Max-Age', '7200') // 2 hours https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Max-Age
     }

package/template/api/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../tsconfig.json",
+  "extends": "@kevinmarrec/tsconfig",
   "compilerOptions": {
     "lib": ["ESNext"]
   }

package/template/app/.env

@@ -1 +1,3 @@
 VITE_API_URL=https://api.dev.localhost
+VITE_ANALYTICS_URL=https://analytics.dev.localhost
+VITE_ANALYTICS_WEBSITE_ID=bcb4bcfc-9f60-4dc1-8fd3-e522e3089c6f

package/template/app/index.html

@@ -6,6 +6,9 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="color-scheme" content="dark light" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="preconnect" href="%VITE_API_URL%" crossorigin />
+    <link rel="dns-prefetch" href="%VITE_ANALYTICS_URL%" />
+    <script defer src="%VITE_ANALYTICS_URL%/script.js" data-website-id="%VITE_ANALYTICS_WEBSITE_ID%"></script>
     <title>Title</title>
   </head>
   <body class="font-sans">

package/template/app/package.json

@@ -10,26 +10,30 @@
   },
   "dependencies": {
     "@kevinmarrec/vue-i18n": "^1.1.3",
-    "@orpc/client": "^1.11.2",
-    "@orpc/tanstack-query": "1.11.2",
-    "@tanstack/query-core": "^5.90.10",
-    "@tanstack/vue-query": "^5.91.2",
+    "@orpc/client": "^1.12.0",
+    "@orpc/tanstack-query": "^1.12.0",
+    "@tanstack/query-core": "^5.90.11",
+    "@tanstack/vue-query": "^5.92.0",
     "@unhead/vue": "^2.0.19",
-    "@vueuse/core": "^14.0.0",
-    "better-auth": "^1.3.34",
-    "unocss": "^66.5.6",
-    "vue": "^3.5.24"
+    "@vueuse/core": "^14.1.0",
+    "better-auth": "^1.4.3",
+    "unocss": "^66.5.9",
+    "vue": "^3.5.25"
   },
   "devDependencies": {
-    "@kevinmarrec/unocss-config": "^1.5.6",
+    "@kevinmarrec/tsconfig": "^1.5.8",
+    "@kevinmarrec/unocss-config": "^1.5.8",
     "@kevinmarrec/vite-plugin-dark-mode": "^1.1.2",
     "@modyfi/vite-plugin-yaml": "^1.1.1",
     "@unhead/addons": "^2.0.19",
-    "@vitejs/plugin-vue": "^6.0.1",
+    "@vitejs/plugin-vue": "^6.0.2",
     "beasties": "^0.3.5",
     "rollup-plugin-visualizer": "^6.0.5",
-    "vite": "^7.2.2",
-    "vite-plugin-vue-devtools": "^8.0.3",
+    "typescript": "~5.9.3",
+    "valibot": "^1.2.0",
+    "vite": "^7.2.4",
+    "vite-plugin-valibot-env": "^1.0.1",
+    "vite-plugin-vue-devtools": "^8.0.5",
     "vite-ssg": "^28.2.2",
     "vite-tsconfig-paths": "^5.1.4"
   }

package/template/app/src/App.vue

@@ -6,11 +6,6 @@ import { useAuth, useContent, useHead, useI18n } from '~/app/composables'
 const { t } = useI18n()
 useHead({
   title: () => t('title'),
-  link: [{
-    rel: 'preconnect',
-    href: new URL(import.meta.env.VITE_API_URL).origin,
-    crossorigin: '',
-  }],
 })
 
 const { user, signIn, signUp, signOut } = useAuth()

package/template/app/src/env.d.ts

@@ -1,8 +1,6 @@
 /// <reference types="vite/client" />
 
-interface ImportMetaEnv {
-  readonly VITE_API_URL: string
-}
+interface ImportMetaEnv extends ViteEnv {}
 
 interface ImportMeta {
   readonly env: ImportMetaEnv

package/template/app/tsconfig.json

@@ -1,6 +1,11 @@
 {
-  "extends": "../tsconfig.json",
+  "extends": "@kevinmarrec/tsconfig",
   "compilerOptions": {
-    "lib": ["ESNext", "DOM", "DOM.Iterable"]
-  }
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "paths": {
+      "~/api/*": ["../api/src/*"],
+      "~/app/*": ["./src/*"]
+    }
+  },
+  "exclude": ["**/dist/**"]
 }