@ghentcdh/crouton-core 0.0.1-alpha.82 → 0.0.1-alpha.83

package/agent-docs/1.getting-started/index.md

@@ -0,0 +1,194 @@
+---
+description: Scaffold a new Crouton project with create-crouton, or add Crouton to an existing NestJS + Vue app using add-crouton.
+---
+
+# Getting started
+
+> Last verified against crouton `0.0.1-alpha.81`
+
+Two ways to start with crouton: **create a new project** from scratch, or **add crouton** to an existing one.
+
+## @ghentcdh/create-crouton
+
+Scaffold a complete crouton project — a NestJS backend with Prisma, pre-configured datasource, Docker Compose, and optionally an Nx monorepo layout with a Vue frontend.
+
+```sh
+npm create @ghentcdh/crouton my-app
+# or
+npx @ghentcdh/create-crouton my-app
+```
+
+### Local development
+
+To test a locally built version of the CLI:
+
+```sh
+# Build and link globally
+pnpm nx build create-crouton
+pnpm link ./packages/create-crouton --global
+
+# Now use it anywhere
+create-crouton my-test-app --prefix split
+```
+
+Or run directly without linking:
+
+```sh
+pnpm nx build create-crouton
+node packages/create-crouton/dist/index.js my-test-app
+```
+
+### Flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--nx` | prompt | Use Nx monorepo layout (backend + frontend + shared libs). |
+| `--no-nx` | — | Skip Nx layout (scaffold a regular single-app project). |
+| `--no-frontend` | — | Skip Vue frontend generation (Nx layout only). |
+| `--no-postgres` | — | Skip PostgreSQL setup (Prisma schema, adapter, Docker). |
+| `--sample` | — | Include a sample resource. |
+| `--pm <manager>` | prompt | Package manager: `pnpm`, `npm`, `yarn`, or `bun`. |
+| `--no-install` | — | Skip dependency installation. |
+| `--no-git` | — | Skip `git init`. |
+| `--no-docker` | — | Skip Docker files (Dockerfile, compose.yml). |
+| `--prefix <name>` | prompt | Subfolder prefix for apps/config (e.g. `split`). Implies Nx layout. |
+| `--db-url <url>` | prompt | Database connection URL. |
+| `-y, --yes` | — | Accept all defaults (non-interactive). |
+| `--force` | — | Overwrite existing files. |
+
+### Layouts
+
+#### Regular (single app)
+
+A standalone NestJS backend — best for APIs, small projects, or when you already have a separate frontend.
+
+```
+my-app/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── data-sources/default/
+│   │   ├── data-source.json
+│   │   └── index.ts
+│   └── resources/          # generated by `crouton update resources`
+├── prisma/default/
+│   ├── schema.prisma
+│   └── prisma.config.ts
+├── crouton.json
+├── crouton.enums.json
+├── package.json
+├── compose.yml
+└── .env
+```
+
+#### Nx monorepo
+
+A full-stack workspace with separate backend and frontend apps, shared generated types, and workspace-level tooling.
+
+```
+my-app/
+├── apps/
+│   ├── backend/
+│   │   ├── src/
+│   │   │   ├── main.ts
+│   │   │   └── app/
+│   │   │       ├── app.module.ts
+│   │   │       ├── data-sources/default/
+│   │   │       └── resources/
+│   │   └── package.json
+│   └── frontend/           # Vue + Vite (skipped with --no-frontend)
+│       ├── src/
+│       │   ├── main.ts
+│       │   └── App.vue
+│       └── package.json
+├── generated/default/
+│   ├── types/               # crouton-prisma zod output
+│   └── client/              # Prisma client output
+├── prisma/default/
+├── crouton.json
+├── nx.json
+├── pnpm-workspace.yaml
+└── package.json
+```
+
+#### Nx monorepo with prefix
+
+When using `--prefix split`, apps and generated code live under a subfolder. This is useful when the Nx workspace also contains non-crouton projects.
+
+```
+my-app/
+├── split/
+│   ├── apps/
+│   │   ├── backend/
+│   │   └── frontend/
+│   ├── generated/default/
+│   │   ├── types/
+│   │   └── client/
+│   ├── prisma/default/
+│   └── crouton.json
+├── nx.json
+├── tsconfig.base.json
+├── pnpm-workspace.yaml
+└── package.json
+```
+
+### What happens after scaffolding
+
+The CLI runs these steps automatically (unless skipped via flags):
+
+1. **`git init`** — initialises a repository with an initial commit.
+2. **`<pm> install`** — installs all dependencies.
+3. **`crouton update resources`** — introspects the database and generates resource CRUD (best-effort; warns on failure if DB is not running).
+
+Then follow the printed next-steps:
+
+```sh
+docker compose up -d          # start postgres
+pnpm prisma:migrate           # create initial migration
+crouton update resources      # generate resource CRUD from your schema
+pnpm dev                      # start dev server
+```
+
+When using a prefix, add the `--prefix` flag:
+
+```sh
+crouton update resources --prefix split
+```
+
+## @ghentcdh/add-crouton
+
+Add crouton to an **existing** NestJS project — regular or Nx. This command is additive: it never overwrites existing files.
+
+```sh
+npx @ghentcdh/add-crouton
+# or from outside the project:
+npx @ghentcdh/add-crouton --cwd /path/to/project
+```
+
+### Flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--cwd <dir>` | `.` | Project directory. |
+| `--backend <app>` | auto-detect | Backend app name (Nx only). |
+| `--frontend <app>` | auto-detect | Frontend app name (Nx only). |
+| `--no-frontend` | — | Skip frontend detection. |
+| `--pm <manager>` | auto-detect | Package manager. |
+| `--no-install` | — | Skip dependency installation. |
+| `--no-docker` | — | Skip Docker file generation. |
+| `-y, --yes` | — | Accept all defaults (non-interactive). |
+
+### What it does
+
+1. **Detects project type** — checks for `nx.json` at or above the current directory to distinguish Nx workspaces from regular projects.
+2. **Discovers apps** (Nx only) — scans `apps/` subdirs, classifies them as backend (`@nestjs/core` in deps) or frontend (`vue`/`vite` in deps), and prompts which to use.
+3. **Detects package manager** — from lockfile presence (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb).
+4. **Scans dependencies** — reports missing backend deps (`@ghentcdh/crouton-api`, `@ghentcdh/crouton-core`, `prisma`, etc.).
+5. **Writes config files** (if absent):
+   - `crouton.json` — with detected `resourcesDir` and `dataSourcesDir`
+   - `crouton.enums.json` — empty enum registry
+   - `data-sources/default/` — default datasource with Prisma schema and config
+   - `.env.example` — with `DATABASE_URL` placeholder
+6. **Installs dependencies** — runs `<pm> install` if missing deps were detected.
+
+After running `@ghentcdh/add-crouton`, wire `CroutonApiModule` into your NestJS app module — see [Backend setup](backend.md).

package/agent-docs/1.getting-started/manual-setup.md

@@ -0,0 +1,478 @@
+---
+description: Step-by-step guide to add Crouton to an existing NestJS project without using the CLI scaffolding tools.
+---
+
+# Manual setup
+
+Add crouton to an existing NestJS project without using the CLI scaffolding tools (`create-crouton` or `add-crouton`).
+
+## 1. Install dependencies
+
+### Backend
+
+```sh
+# Runtime
+pnpm add @ghentcdh/crouton-api @prisma/adapter-pg @prisma/client dotenv tslib zod
+
+# Dev
+pnpm add -D @ghentcdh/crouton-cli @ghentcdh/crouton-prisma prisma
+```
+
+### Frontend (optional, Vue 3)
+
+```sh
+pnpm add @ghentcdh/crouton-vue vue
+pnpm add -D vite @vitejs/plugin-vue
+```
+
+## 2. Create the project config
+
+### crouton.json
+
+Create `crouton.json` at the project root (or workspace root for Nx):
+
+```json
+{
+  "title": "My App",
+  "resourcesDir": "src/app/resources",
+  "dataSourcesDir": "src/app/data-sources",
+  "enumsFile": "crouton.enums.json"
+}
+```
+
+For Nx monorepos with apps in subdirectories, adjust paths accordingly:
+
+```json
+{
+  "title": "My App",
+  "resourcesDir": "apps/backend/src/app/resources",
+  "dataSourcesDir": "apps/backend/src/app/data-sources",
+  "enumsFile": "crouton.enums.json"
+}
+```
+
+### crouton.enums.json
+
+Create an empty enum registry:
+
+```json
+{}
+```
+
+## 3. Set up a data source
+
+### Prisma schema
+
+Create `prisma/default/schema.prisma`:
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+  output   = "../../generated/default/client/src"
+}
+
+generator crouton {
+  provider  = "crouton-prisma"
+  zodOutput = "../../generated/default/types/src"
+}
+
+datasource db {
+  provider = "postgresql"
+  // url is provided by prisma.config.ts (Prisma 7 forbids url here)
+}
+```
+
+### Prisma config
+
+Create `prisma/default/prisma.config.ts`:
+
+```ts
+import 'dotenv/config';
+import { defineConfig, env } from 'prisma/config';
+
+export default defineConfig({
+  schema: 'prisma/default/schema.prisma',
+  migrations: {
+    path: 'prisma/default/migrations',
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+});
+```
+
+### Data source folder
+
+Create `src/app/data-sources/default/data-source.json`:
+
+```json
+{
+  "type": "postgres",
+  "name": "default",
+  "default": true,
+  "prismaSchema": "prisma/default/schema.prisma",
+  "urlEnv": "DATABASE_URL",
+  "generatedTypesImport": "@my-app/generated/default/types",
+  "zodOutput": "generated/default/types/src",
+  "prismaConfig": "prisma/default/prisma.config.ts"
+}
+```
+
+Create `src/app/data-sources/default/index.ts`:
+
+```ts
+import { PrismaClient } from '../../generated/default/client/src';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const client = new PrismaClient({ adapter });
+
+export default client;
+```
+
+## 4. Configure TypeScript paths
+
+### Standalone project
+
+In `tsconfig.json`, add path aliases for the generated types and client:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@my-app/generated/default/types": [
+        "./generated/default/types/src"
+      ],
+      "@my-app/generated/default/client": [
+        "./generated/default/client/src"
+      ]
+    }
+  }
+}
+```
+
+### Nx monorepo
+
+In `tsconfig.base.json` at the workspace root:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@my-app/generated/default/types": [
+        "./generated/default/types/src"
+      ],
+      "@my-app/generated/default/client": [
+        "./generated/default/client/src"
+      ]
+    }
+  }
+}
+```
+
+If using a prefix subfolder (e.g. `split`), adjust the paths:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@my-app/generated/default/types": [
+        "./split/generated/default/types/src"
+      ],
+      "@my-app/generated/default/client": [
+        "./split/generated/default/client/src"
+      ]
+    }
+  }
+}
+```
+
+## 5. Register the NestJS module
+
+In your app module:
+
+```ts
+import { resolve } from 'node:path';
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { CroutonApiModule } from '@ghentcdh/crouton-api';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, envFilePath: ['.env.local', '.env'] }),
+    CroutonApiModule.forResourceDir(
+      resolve(__dirname, 'resources'),
+      resolve(__dirname, 'data-sources'),
+      {
+        baseUrl: '/api',
+        title: 'My App',
+        enumsFile: resolve(__dirname, '..', '..', 'crouton.enums.json'),
+      },
+    ),
+  ],
+})
+export class AppModule {
+}
+```
+
+## 6. Environment file
+
+Create `.env`:
+
+```env
+DATABASE_URL=postgresql://crouton:crouton@localhost:5432/my_app?schema=public
+```
+
+## 7. Generate Prisma client and types
+
+```sh
+npx prisma migrate dev --config prisma/default/prisma.config.ts
+```
+
+This creates the initial migration, generates the Prisma client, and runs `crouton-prisma` (which normalizes the schema and generates Zod types).
+
+## 8. Generate resources
+
+```sh
+npx crouton update resources
+```
+
+For Nx workspaces with a prefix subfolder:
+
+```sh
+npx crouton update resources --prefix split
+```
+
+This introspects your database, lets you pick which models to expose, and generates `resource.json` + `schema.ts` files
+per resource.
+
+### CLI flags
+
+| Flag                      | Description                                          |
+|---------------------------|------------------------------------------------------|
+| `-d, --datasource <name>` | Datasource to use (from crouton.config).             |
+| `-m, --models <list>`     | Comma-separated models to limit to.                  |
+| `--cwd <dir>`             | Project directory (defaults to cwd).                 |
+| `--prefix <name>`         | Subfolder prefix (resolves cwd to `<cwd>/<prefix>`). |
+| `--dry-run`               | Show planned changes without writing files.          |
+| `-y, --yes`               | Accept all defaults (non-interactive).               |
+| `--skip-pull`             | Do not run `prisma db pull`.                         |
+| `--skip-generate`         | Do not run `prisma generate` after pulling.          |
+
+## 9. Frontend app (Vue 3)
+
+### Install dependencies
+
+```sh
+pnpm add @ghentcdh/crouton-vue axios vue vue-router
+pnpm add -D vite @vitejs/plugin-vue @types/node typescript
+```
+
+### index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>My App</title>
+</head>
+<body>
+<div id="app"></div>
+<script type="module" src="/src/main.ts"></script>
+</body>
+</html>
+```
+
+### API client
+
+Create `src/api.ts`:
+
+```ts
+import axios from 'axios';
+
+export const api = axios.create({
+  baseURL: '/api',
+});
+```
+
+### Entry point
+
+Create `src/main.ts`:
+
+```ts
+import { createApp } from 'vue';
+import { createRouter, createWebHistory } from 'vue-router';
+import { CroutonPlugin, CroutonRouter } from '@ghentcdh/crouton-vue';
+import '@ghentcdh/crouton-vue/styles.css';
+import { api } from './api';
+import App from './App.vue';
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      name: 'admin',
+      children: [...CroutonRouter],
+    },
+  ],
+});
+
+const app = createApp(App);
+app.use(CroutonPlugin(api, { title: 'My App', router }));
+app.use(router);
+app.mount('#app');
+```
+
+### App component
+
+Create `src/App.vue`:
+
+```vue
+
+<template>
+  <router-view />
+</template>
+
+<script setup lang="ts">
+</script>
+```
+
+### Vite config
+
+Create `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [vue()],
+  server: {
+    port: 4200,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3000',
+        changeOrigin: true,
+      },
+    },
+  },
+});
+```
+
+The proxy forwards `/api` requests to the NestJS backend during development.
+
+### Frontend tsconfig.json (Nx only)
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "jsx": "preserve",
+    "jsxImportSource": "vue"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.vue"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}
+```
+
+## 10. Start the dev server
+
+```sh
+pnpm dev
+```
+
+For more frontend configuration, see [Frontend setup](frontend.md).
+
+## Nx workspace extras
+
+For Nx monorepos, you also need:
+
+### pnpm-workspace.yaml
+
+```yaml
+packages:
+  - apps/*
+  - generated/default/*
+  - libs/*
+```
+
+### nx.json
+
+```json
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "defaultBase": "main"
+}
+```
+
+### Backend tsconfig.json
+
+Backend app tsconfigs should extend the base:
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "outDir": "./dist",
+    "sourceMap": true,
+    "incremental": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}
+```
+
+### Generated package.json files
+
+Each generated output needs a `../../../package.json` for workspace resolution:
+
+`generated/default/types/package.json`:
+
+```json
+{
+  "name": "@my-app/generated-default-types",
+  "version": "0.0.1",
+  "private": true,
+  "main": "./src/index.ts",
+  "dependencies": {
+    "zod": "^4.0.0"
+  }
+}
+```
+
+`generated/default/client/package.json`:
+
+```json
+{
+  "name": "@my-app/generated-default-client",
+  "version": "0.0.1",
+  "private": true,
+  "main": "./src/index.ts"
+}
+```