@next-friday/create-app 2.0.0 → 2.1.0

package/templates/turborepo/.github/workflows/ci.yml

@@ -0,0 +1,212 @@
+name: Verify
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, converted_to_draft]
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "0 3 * * 1"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read # Needed by paths-filter to inspect pull request changes.
+    outputs:
+      heavy: ${{ steps.filter.outputs.heavy }}
+      ci_policy: ${{ steps.filter.outputs.ci_policy }}
+      full_verification: ${{ steps.mode.outputs.full_verification }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Detect relevant changes
+        id: filter
+        if: github.event_name == 'pull_request'
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        with:
+          predicate-quantifier: some-with-excludes
+          filters: .github/file-filters.yml
+      - name: Select verification mode
+        id: mode
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          DRAFT: ${{ github.event.pull_request.draft }}
+          HEAVY: ${{ steps.filter.outputs.heavy }}
+          CI_POLICY: ${{ steps.filter.outputs.ci_policy }}
+        run: |
+          full_verification=false
+          if [[ "$EVENT_NAME" == "push" || ( "$EVENT_NAME" == "pull_request" && "$DRAFT" != "true" && ( "$HEAVY" == "true" || "$CI_POLICY" == "true" ) ) ]]; then
+            full_verification=true
+          fi
+
+          echo "full_verification=$full_verification" >> "$GITHUB_OUTPUT"
+
+  checks:
+    name: Static Checks, Tests & Build
+    needs: changes
+    if: needs.changes.outputs.full_verification == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:17.11-alpine@sha256:266d3c257594e195b309ae9d1805e54c788f1d7b375f56bf6c367aac6c917e7b
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: payload
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready --username postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/payload
+      PAYLOAD_SECRET: ci-only-secret
+      APP_URL: http://localhost:3001
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Node.js and pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          cache: true
+          require-lockfile: true
+      - name: Reject suppression directives
+        run: pnpm suppressions:check
+      - name: Check Cursor rules match .agents/rules
+        run: pnpm rules:check
+      - name: Check agent gates
+        run: pnpm gates:check
+      - name: Check lint
+        run: pnpm lint:check
+      - name: Check formatting
+        run: pnpm format:check
+        env:
+          GITHUB_TOKEN: ${{ github.token }} # editorconfig-checker downloads its binary from GitHub releases; the token avoids the anonymous rate limit.
+      - name: Check package.json ordering
+        run: pnpm sort-package-json:check
+      - name: Validate peer dependency contracts
+        run: pnpm peers:check
+      - name: Check types
+        run: pnpm typecheck
+      - name: Run Knip
+        run: pnpm knip
+      - name: Check dependency graph
+        run: pnpm depcruise
+      - name: Run tests with coverage
+        run: pnpm test:coverage
+      - name: Build
+        run: pnpm build
+        env:
+          NEXT_TELEMETRY_DISABLED: "1"
+      - name: Install Playwright browser
+        run: pnpm --filter ./apps/app exec playwright install --with-deps chromium
+      - name: Run end-to-end tests
+        run: pnpm test:e2e
+        env:
+          NEXT_TELEMETRY_DISABLED: "1"
+      - name: Check patch coverage
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          python3 -m venv "$RUNNER_TEMP/diff-cover"
+          "$RUNNER_TEMP/diff-cover/bin/pip" install --quiet --require-hashes --only-binary=:all: -r .github/requirements/diff-cover.txt
+          "$RUNNER_TEMP/diff-cover/bin/diff-cover" apps/app/coverage/cobertura-coverage.xml --compare-branch "origin/$BASE_REF" --fail-under 95 --branch-coverage
+          "$RUNNER_TEMP/diff-cover/bin/diff-cover" apps/backoffice/coverage/cobertura-coverage.xml --compare-branch "origin/$BASE_REF" --fail-under 95 --branch-coverage
+
+  image:
+    name: Container Image
+    needs: changes
+    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      HADOLINT_VERSION: 2.15.1
+      HADOLINT_SHA256: c7187db94eeeeca956519a6af171adc31453941a1e777961f6e680f697c8c507
+      TRIVY_VERSION: 0.76.1
+      TRIVY_SHA256: c7cbe3137fb8a48a17574bede3dd6beb16742d1e9772929940fc90082c39d9c0
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Lint Dockerfile
+        run: |
+          curl --silent --show-error --fail --location --output hadolint \
+            "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-linux-x86_64"
+          echo "${HADOLINT_SHA256}  hadolint" | sha256sum --check --strict
+          chmod +x hadolint
+          ./hadolint apps/app/Dockerfile apps/backoffice/Dockerfile
+      - name: Build images
+        run: |
+          docker build --file apps/app/Dockerfile --tag app:ci .
+          docker build --file apps/backoffice/Dockerfile --tag backoffice:ci .
+      - name: Smoke test images
+        id: smoke
+        run: |
+          docker run --detach --name app --env PORT=3000 --publish 3000:3000 app:ci
+          docker run --detach --name backoffice --env PORT=3001 --env DATABASE_URL=postgres://build-only@localhost/build-only --env PAYLOAD_SECRET=ci-only-secret --env APP_URL=http://localhost:3001 --publish 3001:3001 backoffice:ci
+          curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3000/health
+          curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3001/health
+      - name: Show container logs
+        if: failure() && steps.smoke.outcome == 'failure'
+        run: |
+          docker logs app
+          docker logs backoffice
+      - name: Scan images for vulnerabilities
+        run: |
+          archive="trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz"
+          curl --silent --show-error --fail --location --output "$archive" \
+            "https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/${archive}"
+          echo "${TRIVY_SHA256}  ${archive}" | sha256sum --check --strict
+          tar --extract --gzip --file "$archive" trivy
+          ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
+          ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress backoffice:ci
+
+  deploy-dev:
+    name: Deploy to dev
+    needs:
+      - checks
+      - image
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_ENABLED == 'true'
+    permissions:
+      contents: read
+      actions: read # Needed by deploy.yml to find the CI run of the deployed commit.
+    uses: ./.github/workflows/deploy.yml
+    with:
+      environment: dev
+      commit_sha: ${{ github.sha }}
+
+  ci:
+    name: All Checks
+    if: always()
+    timeout-minutes: 5
+    needs:
+      - changes
+      - checks
+      - image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require all verification jobs
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

package/templates/turborepo/.github/workflows/deploy.yml

@@ -0,0 +1,135 @@
+name: Deploy
+run-name: Deploy ${{ inputs.commit_sha }} to ${{ inputs.environment }}
+
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      commit_sha:
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Railway environment to promote to
+        required: true
+        type: choice
+        options:
+          - uat
+          - prod
+      commit_sha:
+        description: Full commit SHA on main that passed CI
+        required: true
+        type: string
+
+permissions: {}
+
+concurrency:
+  group: deploy-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify the requested commit
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      actions: read # Needed to find the CI and deploy runs of the requested commit.
+    env:
+      COMMIT_SHA: ${{ inputs.commit_sha }}
+      TARGET: ${{ inputs.environment }}
+    steps:
+      - name: Checkout the requested revision
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ inputs.commit_sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Require the commit on main with passing CI and a deployment to the previous environment
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          [[ "$COMMIT_SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::Expected a full lowercase commit SHA"; exit 1; }
+          git merge-base --is-ancestor "$COMMIT_SHA" origin/main || { echo "::error::$COMMIT_SHA is not on main"; exit 1; }
+          ci_run="$(gh api "repos/$REPOSITORY/actions/workflows/ci.yml/runs?head_sha=$COMMIT_SHA&event=push&branch=main&status=success" --jq '.workflow_runs[0].id // empty')"
+          [[ -n "$ci_run" ]] || { echo "::error::No successful CI run on main for $COMMIT_SHA"; exit 1; }
+          case "$TARGET" in
+            uat)
+              previous=dev
+              deployed="$(gh api "repos/$REPOSITORY/actions/runs/$ci_run/jobs" --jq '[.jobs[] | select(.name == "Deploy to dev / Deploy to dev" and .conclusion == "success")] | length')"
+              ;;
+            prod)
+              previous=uat
+              export EXPECTED_TITLE="Deploy $COMMIT_SHA to uat"
+              deployed="$(gh api --paginate "repos/$REPOSITORY/actions/workflows/deploy.yml/runs?event=workflow_dispatch&status=success&per_page=100" --jq '.workflow_runs[] | select(.display_title == env.EXPECTED_TITLE) | .id' | wc -l)"
+              ;;
+          esac
+          [[ "$deployed" -gt 0 ]] || { echo "::error::$COMMIT_SHA has no successful $previous deployment; promote through $previous first"; exit 1; }
+
+  deploy:
+    name: Deploy to ${{ inputs.environment }}
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    environment:
+      name: ${{ inputs.environment }}
+      url: ${{ vars.APP_URL }}
+    permissions:
+      contents: read
+    env:
+      APP_URL: ${{ vars.APP_URL }}
+      BACKOFFICE_URL: ${{ vars.BACKOFFICE_URL }}
+      RAILWAY_CLI_SHA256: 2e682fd2ddf8d6fdf9e46d9d99d99646ff0022a6abb0c2bca93011348a269fb9
+      RAILWAY_CLI_VERSION: 5.71.0
+      RAILWAY_ENVIRONMENT: ${{ inputs.environment }}
+      RAILWAY_SERVICE_APP: ${{ vars.RAILWAY_SERVICE_APP }}
+      RAILWAY_SERVICE_BACKOFFICE: ${{ vars.RAILWAY_SERVICE_BACKOFFICE }}
+    steps:
+      - name: Require environment settings
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+        run: |
+          [[ -n "$RAILWAY_TOKEN" ]] || { echo "::error::Set the RAILWAY_TOKEN secret in the $RAILWAY_ENVIRONMENT environment"; exit 1; }
+          [[ -n "$RAILWAY_SERVICE_APP" ]] || { echo "::error::Set the RAILWAY_SERVICE_APP variable in the $RAILWAY_ENVIRONMENT environment"; exit 1; }
+          [[ -n "$RAILWAY_SERVICE_BACKOFFICE" ]] || { echo "::error::Set the RAILWAY_SERVICE_BACKOFFICE variable in the $RAILWAY_ENVIRONMENT environment"; exit 1; }
+          [[ "$APP_URL" == https://* ]] || { echo "::error::Set the APP_URL variable to an https URL in the $RAILWAY_ENVIRONMENT environment"; exit 1; }
+          [[ "$BACKOFFICE_URL" == https://* ]] || { echo "::error::Set the BACKOFFICE_URL variable to an https URL in the $RAILWAY_ENVIRONMENT environment"; exit 1; }
+      - name: Checkout the requested revision
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ inputs.commit_sha }}
+          persist-credentials: false
+      - name: Install verified Railway CLI
+        run: |
+          archive="railway-v${RAILWAY_CLI_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          curl --silent --show-error --fail --location --retry 3 --output "$RUNNER_TEMP/$archive" \
+            "https://github.com/railwayapp/cli/releases/download/v${RAILWAY_CLI_VERSION}/${archive}"
+          echo "${RAILWAY_CLI_SHA256}  $RUNNER_TEMP/$archive" | sha256sum --check --strict
+          tar --extract --gzip --file "$RUNNER_TEMP/$archive" --directory "$RUNNER_TEMP"
+          echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+      - name: Deploy
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+        run: |
+          railway up --ci --service "$RAILWAY_SERVICE_APP" --environment "$RAILWAY_ENVIRONMENT"
+          railway up --ci --service "$RAILWAY_SERVICE_BACKOFFICE" --environment "$RAILWAY_ENVIRONMENT"
+      - name: Require a healthy deployment
+        run: |
+          wait_health() {
+            url="$1"
+            for _ in $(seq 30); do
+              if curl --silent --fail --output /dev/null "$url/health"; then
+                return 0
+              fi
+              sleep 10
+            done
+            echo "::error::$url/health did not respond"
+            return 1
+          }
+          wait_health "$APP_URL"
+          wait_health "$BACKOFFICE_URL"

package/templates/turborepo/.github/workflows/sast.yml

@@ -0,0 +1,46 @@
+name: SAST
+
+on:
+  pull_request: {}
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "**/*.md"
+      - ".agents/**"
+      - ".claude/**"
+      - ".cursor/**"
+  schedule:
+    - cron: "17 2 * * 1"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  semgrep:
+    name: Semgrep (OWASP)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    container:
+      image: semgrep/semgrep:1.179.0@sha256:93963d9295a366f59e4850127b1550400ee7b388f04fe144e4a1f6325d96e01b
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Scan source
+        run: >-
+          semgrep scan
+          --config p/owasp-top-ten
+          --config p/typescript
+          --config p/nodejsscan
+          --config p/react
+          --severity ERROR --severity WARNING
+          --error --metrics=off
+          --timeout 60 --timeout-threshold 0
+          .

package/templates/turborepo/.lintstagedrc.json

@@ -0,0 +1,10 @@
+{
+  "*.{ts,tsx,js,jsx,mjs,cjs}": [
+    "pnpm exec eslint --fix --cache --max-warnings=0 --no-warn-ignored --no-inline-config",
+    "prettier --write --cache"
+  ],
+  "!(package).json": ["prettier --write --cache"],
+  "*.{css,scss,md,yml,yaml}": ["prettier --write --cache"],
+  "package.json": ["sort-package-json", "prettier --write --cache"],
+  ".husky/{commit-msg,pre-commit,pre-merge-commit,pre-push}": ["prettier --write --cache"]
+}

package/templates/turborepo/.prettierignore

@@ -0,0 +1,5 @@
+.husky/_
+pnpm-lock.yaml
+apps/backoffice/src/app/(payload)/
+apps/backoffice/src/migrations/
+apps/backoffice/src/payload-types.ts

package/templates/turborepo/AGENTS.md

@@ -0,0 +1,20 @@
+# Agent guide
+
+Turborepo workspace on pnpm. `apps/app` is the Next.js site. `apps/backoffice` is the Payload CMS. Root scripts run the same checks as the other Next Friday templates and delegate framework commands with Turborepo.
+
+- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
+- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
+- Put unit tests next to the code as `*.test.ts`. Put Playwright end-to-end tests in `apps/app/test/` and `apps/backoffice/test/` as `*.e2e.test.ts`. Component tests need a DOM test environment, which is not set up yet; ask the user before adding one.
+- The Next.js site lives in `apps/app/app/`. The backoffice site lives in `apps/backoffice/src/app/(frontend)/`, collections in `apps/backoffice/src/collections/`, and the Payload config in `apps/backoffice/src/payload.config.ts`.
+- Payload generates `apps/backoffice/src/app/(payload)/`, `apps/backoffice/src/payload-types.ts`, and `apps/backoffice/src/migrations/`. After changing a collection, regenerate them with `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`, and commit the results.
+- Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`. Document each variable in `.env.example`.
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

package/templates/turborepo/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Use this guide to prepare changes to this repository.
+
+## Prerequisites
+
+- Use the Node.js version declared by `.nvmrc` and `package.json#engines`.
+- Change the Node.js version in `.nvmrc` and both Dockerfiles together. Dependabot updates only the Dockerfiles.
+- Install pnpm once with `npm install --global pnpm`. It switches to the version declared by `package.json#packageManager` automatically.
+- Use Claude Code v2.1.295 or later. It reads `AGENTS.md` directly and supports the `onFailure` field the agent hooks use.
+- Install gitleaks 8.19 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
+
+From the repository root:
+
+```sh
+npm install --global pnpm
+pnpm install
+```
+
+## Quality standards
+
+- Fix lint, type, and test failures at their root cause.
+- Put unit tests next to the code as `*.test.ts` and Playwright end-to-end tests in each app's `test/` as `*.e2e.test.ts`.
+- Change the database schema only through collections, then run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>` and commit the generated files. Production applies pending migrations when the server starts.
+- Treat `coverage/` as generated output.
+- Do not commit `.env` files or credentials.
+
+## Verification
+
+Run the narrowest check that covers the change while you work. Git hooks run these checks:
+
+| Hook               | Checks                                                                                                                                                |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pre-commit`       | blocks commits on `main` except the first commit of a new repository, gitleaks on staged changes, `pnpm rules:check`, and lint-staged on staged files |
+| `commit-msg`       | commitlint                                                                                                                                            |
+| `pre-merge-commit` | blocks merge commits on `main`                                                                                                                        |
+| `pre-push`         | blocks pushes to `main` except the push that creates it, then `pnpm check`: the static checks and the unit tests related to your changes              |
+
+- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, and OSV scans. Dependabot and OSV-Scanner report vulnerable dependencies.
+- **End-to-end tests:** run `pnpm test:e2e` when you change pages or the admin panel. It starts both development servers unless they are already running, and the backoffice needs `DATABASE_URL` and `PAYLOAD_SECRET` from `.env`. Run `pnpm --filter ./apps/app exec playwright install chromium` once before the first run. CI runs it against the production build and a PostgreSQL service on every pull request that is ready for review and changes code.
+- **Coverage:** CI requires 95% branch coverage on changed lines in `apps/app/app/` and `apps/backoffice/src/`, except layouts, the Payload config, and generated files.
+
+Run `pnpm verify` for repository changes.
+
+Agent rules live in `.agents/rules/` with their scope in `.agents/rules.json`. After you change either, run `pnpm rules:sync` to regenerate `.claude/rules/` and `.cursor/rules/`.
+
+## Pull requests
+
+We use trunk-based development. `main` is the only long-lived branch, and every deploy promotes a commit from `main` (see the Deploy section in the README).
+
+- Branch from `main` and merge back within a day or two. Do not create `develop` or release branches.
+- Merge unfinished work behind a feature flag or keep it unreachable instead of holding a long-lived branch.
+- Pull requests are squash-merged, so the pull request title becomes the commit on `main`.
+- Write commit messages in the format that `@next-friday/commitlint-config-friday` defines. Pull request titles use `<type>(<scope>): <subject>`, which `.github/workflows/validate-pr-title.yml` checks.
+- Keep each pull request focused on one cohesive change.
+- Describe observable page, collection, API, or configuration effects.
+- Report only checks that actually ran and include their results.
+- Add or update tests only when they protect a distinct observable contract.

package/templates/turborepo/README.md

@@ -0,0 +1,102 @@
+# next-friday-template-turborepo
+
+Next Friday starter for a Turborepo workspace. `apps/app` is a Next.js site on port 3000. `apps/backoffice` is a Payload CMS on port 3001. The backoffice API is REST at `/api`.
+
+## Getting started
+
+```sh
+npm install --global pnpm
+pnpm install
+pnpm dev
+```
+
+The CLI created `.env` from `.env.example` and set `PAYLOAD_SECRET` to a random secret. Before `pnpm dev`, set in `.env`:
+
+- `DATABASE_URL`: a PostgreSQL database.
+- `APP_URL`: the URL you open the backoffice at, such as `http://localhost:3001`.
+- `PAYLOAD_SECRET`, only if you recreate `.env` from `.env.example`: generate one with `openssl rand -hex 32`.
+
+Then open `http://localhost:3000` for the site and `http://localhost:3001/admin` to create the first user.
+
+**Warning:** until the first user exists, anyone who can reach the backoffice `/admin` can create it. Create the first user in each deployed environment right after its first deploy, before you share the URL.
+
+In development, Payload applies collection changes to the database directly. In production, the server applies the migrations in `apps/backoffice/src/migrations/` when it starts.
+
+## After creating a project from this template
+
+1. Install gitleaks and jq (see [CONTRIBUTING.md](CONTRIBUTING.md)). Make the first commit on `main` and push it. The Git hooks allow only this first commit and push on `main`; work on branches after that.
+
+   ```sh
+   git add --all
+   git commit -m "chore(repo): start from template"
+   git push --set-upstream origin main
+   ```
+
+2. Add your team as the owner of every file in `.github/CODEOWNERS`, and replace the owner placeholder in `.github/zizmor.yml`.
+3. Replace the template's description and owner: `package.json#description`, `repository.url`, and `author`, and the `Next Friday Next.js template` text in `apps/app/app/layout.tsx`, `apps/app/app/page.tsx`, and their tests, and the `Next Friday Payload template` text in `apps/backoffice/src/app/(frontend)/layout.tsx`, `apps/backoffice/src/app/(frontend)/page.tsx`, and their tests. Change `license` from `UNLICENSED` if the project is open source.
+4. In the repository settings:
+   - **Actions → General → Workflow permissions:** select **Read repository contents and packages permissions**. Every workflow requests the extra permissions it needs.
+   - **Advanced Security:** enable private vulnerability reporting, Dependabot alerts, Dependabot security updates, secret scanning, and push protection. `SECURITY.md` sends reporters to private vulnerability reporting.
+   - **Cursor Bugbot:** enable the repository at [Bugbot](https://cursor.com/automations/from-cursor/bugbot). Bugbot reviews pull requests against the rules linked from `.cursor/BUGBOT.md`.
+   - **Rules → Rulesets:** protect `main` with squash merges only, a linear history, no force pushes or deletion, and the required checks `All Checks` and `Validate pull request title`. Rulesets in a private repository need GitHub Pro, Team, or Enterprise; on GitHub Free, make the repository public or upgrade.
+   - Create the `needs triage` label, which the issue forms apply: `gh label create "needs triage"`.
+
+## Scripts
+
+| Script                    | Purpose                                                                                          |
+| :------------------------ | :----------------------------------------------------------------------------------------------- |
+| `pnpm dev`                | Start the Next.js app on port 3000 and the Payload backoffice on port 3001                       |
+| `pnpm build`              | Build both apps for production                                                                   |
+| `pnpm start`              | Serve both standalone production builds after `pnpm build`                                       |
+| `pnpm test`               | Run unit tests in both apps                                                                      |
+| `pnpm test:e2e`           | Run Playwright end-to-end tests in both apps. The backoffice uses the database in `DATABASE_URL` |
+| `pnpm generate:types`     | Regenerate `apps/backoffice/src/payload-types.ts` after a collection change                      |
+| `pnpm generate:importmap` | Regenerate the admin import map after adding a custom component                                  |
+| `pnpm migrate:create`     | Create a migration from collection changes, for example `pnpm migrate:create add-posts`          |
+| `pnpm migrate`            | Apply pending migrations to the database in `DATABASE_URL`                                       |
+| `pnpm check`              | Run the static checks and the unit tests for changed code (the `pre-push` hook)                  |
+| `pnpm verify`             | Run the static checks and all unit tests with coverage                                           |
+
+CI also runs the build, the end-to-end tests, the container image scans, and the security scans.
+
+## Container
+
+Each app has a Dockerfile. Build both from the workspace root. The images run as the `node` user. The app listens on `PORT`, or 3000 when it is unset. The backoffice listens on `PORT`, or 3000 when it is unset, and needs `DATABASE_URL`, `PAYLOAD_SECRET`, and `APP_URL`.
+
+```sh
+docker build --file apps/app/Dockerfile --tag app .
+docker build --file apps/backoffice/Dockerfile --tag backoffice .
+docker run --publish 3000:3000 app
+docker run --publish 3001:3001 --env PORT=3001 --env DATABASE_URL --env PAYLOAD_SECRET --env APP_URL backoffice
+```
+
+Uploaded images, up to 10 MB each, are written to the backoffice container filesystem, which a redeploy discards. Add a Payload storage adapter, for example `@payloadcms/storage-s3`, before storing media in production.
+
+On Vercel, deploy an app without its image. The Next.js preset takes precedence over the Dockerfile.
+
+## Deploy
+
+`.github/workflows/deploy.yml` deploys both apps and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. Create one Railway service per app, with that service's Dockerfile path set to `apps/app/Dockerfile` or `apps/backoffice/Dockerfile`. The workflow stays off until you configure it:
+
+1. In Railway, create a project with one service for each app, one PostgreSQL database for the backoffice, and the environments `dev`, `uat`, and `prod`. The workflow passes these names to `railway up --environment`. In each backoffice environment, set the service variables:
+   - `DATABASE_URL` to `${{Postgres.DATABASE_URL}}`;
+   - `PAYLOAD_SECRET` to a separate long random string;
+   - `APP_URL` to that environment's public backoffice `https://` URL.
+
+   Create one project token per environment under **Project Settings → Tokens**. CI tests against PostgreSQL 17; change the image in `ci.yml` if the database runs another major version.
+
+2. In GitHub, create the `dev`, `uat`, and `prod` environments under **Settings → Environments**, and add to each:
+   - the `RAILWAY_TOKEN` secret: that environment's project token;
+   - the `RAILWAY_SERVICE_APP` variable: the Next.js service name;
+   - the `RAILWAY_SERVICE_BACKOFFICE` variable: the Payload service name;
+   - the `APP_URL` variable: the public Next.js `https://` URL;
+   - the `BACKOFFICE_URL` variable: the public backoffice `https://` URL.
+
+   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+
+3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
+4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.
+
+Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/turborepo/_gitignore

@@ -0,0 +1,53 @@
+node_modules
+.pnpm-store
+
+coverage
+playwright-report
+test-results
+*.tsbuildinfo
+
+.cache
+
+*.pem
+
+npm-debug.log*
+pnpm-debug.log*
+*.log
+
+**/.env*
+!.env.example
+
+.eslintcache
+
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+/.idea
+
+logs
+.temp
+.tmp
+
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+**/.DS_Store
+
+*.key
+*.p12
+*.pfx
+id_rsa*
+id_ed25519*
+
+/.claude/settings.local.json
+/.claude/worktrees/
+
+.next
+.turbo
+apps/backoffice/media
+/out
+next-env.d.ts