@next-friday/create-app 2.1.6 → 2.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,7 +1,36 @@
|
|
|
1
1
|
# Agent guide
|
|
2
2
|
|
|
3
|
-
NestJS
|
|
3
|
+
NestJS HTTP API in TypeScript on pnpm and Node.js `>=24.15.0 <25`.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
| Task | Command |
|
|
8
|
+
| :-------------------------- | :-------------------------------------------------- |
|
|
9
|
+
| Start with reload | `pnpm start:dev` |
|
|
10
|
+
| One test | `pnpm vitest run src/port.test.ts -t "<test name>"` |
|
|
11
|
+
| Unit tests | `pnpm test`, or `pnpm test:coverage` |
|
|
12
|
+
| End-to-end tests | `pnpm test:e2e` |
|
|
13
|
+
| What `pre-push` runs | `pnpm check` |
|
|
14
|
+
| Every check | `pnpm verify` |
|
|
15
|
+
| Render rules after a change | `pnpm rules:sync` |
|
|
16
|
+
|
|
17
|
+
## How it fits together
|
|
18
|
+
|
|
19
|
+
- `src/main.ts` creates the app from `AppModule` on `parsePort(process.env.PORT)` with Nest's `ConsoleLogger`, which writes JSON lines when `NODE_ENV` is `production`.
|
|
20
|
+
- `AppModule` imports `HealthModule`, whose Terminus controller serves `/health`. Add a feature as its own module and import it in `AppModule`.
|
|
21
|
+
|
|
22
|
+
## Mandatory rules
|
|
23
|
+
|
|
24
|
+
1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
|
|
25
|
+
2. **Put unit tests next to the code as `src/**/*.test.ts` and end-to-end tests in `test/` as `*.e2e.test.ts`.** `vitest.config.ts` and `vitest.e2e.config.ts` collect only those patterns.
|
|
26
|
+
3. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`.
|
|
27
|
+
4. **Log through Nest's `Logger`.** It goes to the `ConsoleLogger` set in `src/main.ts`.
|
|
28
|
+
|
|
29
|
+
## Known pitfalls
|
|
30
|
+
|
|
31
|
+
- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
|
|
32
|
+
|
|
33
|
+
## Related documentation
|
|
34
|
+
|
|
35
|
+
- [README.md](README.md): scripts, container, deploy
|
|
36
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
|
|
@@ -1,10 +1,40 @@
|
|
|
1
1
|
# Agent guide
|
|
2
2
|
|
|
3
|
-
Next.js App Router
|
|
3
|
+
Next.js App Router web app with React and Tailwind CSS, in TypeScript on pnpm and Node.js `>=24.15.0 <25`.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
| Task | Command |
|
|
8
|
+
| :-------------------------- | :---------------------------------------------------------- |
|
|
9
|
+
| Start with reload | `pnpm dev` |
|
|
10
|
+
| One test | `pnpm vitest run app/health/route.test.ts -t "<test name>"` |
|
|
11
|
+
| Unit tests | `pnpm test`, or `pnpm test:coverage` |
|
|
12
|
+
| End-to-end tests | `pnpm test:e2e` |
|
|
13
|
+
| What `pre-push` runs | `pnpm check` |
|
|
14
|
+
| Every check | `pnpm verify` |
|
|
15
|
+
| Render rules after a change | `pnpm rules:sync` |
|
|
16
|
+
|
|
17
|
+
## How it fits together
|
|
18
|
+
|
|
19
|
+
- Routes live in `app/`. `app/health/route.ts` serves `/health`.
|
|
20
|
+
- `next.config.ts` builds `output: "standalone"`, enables Cache Components, and sets the security headers. `pnpm start` copies the static assets into `.next/standalone` and serves it.
|
|
21
|
+
|
|
22
|
+
## Mandatory rules
|
|
23
|
+
|
|
24
|
+
1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
|
|
25
|
+
2. **Put unit tests next to the code as `app/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
|
|
26
|
+
3. **Ask the user before adding component tests.** They need a DOM test environment, and Vitest runs in Node.js.
|
|
27
|
+
4. **Read configuration from environment variables and fail when one is missing.** Document each variable in `.env.example`.
|
|
28
|
+
|
|
29
|
+
## Known pitfalls
|
|
30
|
+
|
|
31
|
+
- **First end-to-end run**: run `pnpm exec playwright install chromium` once. `pnpm test:e2e` starts the development server unless one is already running.
|
|
32
|
+
- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
|
|
33
|
+
|
|
34
|
+
## Related documentation
|
|
35
|
+
|
|
36
|
+
- [README.md](README.md): scripts, container, deploy
|
|
37
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
|
|
8
38
|
|
|
9
39
|
<!-- BEGIN:nextjs-agent-rules -->
|
|
10
40
|
|
|
@@ -1,7 +1,34 @@
|
|
|
1
1
|
# Agent guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
TypeScript HTTP service on `node:http`, without a framework, on pnpm and Node.js `>=24.15.0 <25`.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
| Task | Command |
|
|
8
|
+
| :-------------------------- | :-------------------------------------------------- |
|
|
9
|
+
| Start with reload | `pnpm start:dev` |
|
|
10
|
+
| One test | `pnpm vitest run src/port.test.ts -t "<test name>"` |
|
|
11
|
+
| Unit tests | `pnpm test`, or `pnpm test:coverage` |
|
|
12
|
+
| What `pre-push` runs | `pnpm check` |
|
|
13
|
+
| Every check | `pnpm verify` |
|
|
14
|
+
| Render rules after a change | `pnpm rules:sync` |
|
|
15
|
+
|
|
16
|
+
## How it fits together
|
|
17
|
+
|
|
18
|
+
- `src/main.ts` starts `createAppServer()` from `src/server.ts` on `parsePort(process.env.PORT)`, and on `SIGTERM` or `SIGINT` stops accepting connections and closes any left after 10 seconds.
|
|
19
|
+
- `src/server.ts` answers `GET` and `HEAD` `/health` and returns 404 for every other request. Routes go there.
|
|
20
|
+
|
|
21
|
+
## Mandatory rules
|
|
22
|
+
|
|
23
|
+
1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
|
|
24
|
+
2. **Put tests next to the code as `src/**/*.test.ts`.** Vitest collects only that pattern.
|
|
25
|
+
3. **Read configuration from environment variables and fail when one is missing**, as `parsePort` does. Document each variable in `.env.example`; `pnpm start` and `pnpm start:dev` load `.env`.
|
|
26
|
+
|
|
27
|
+
## Known pitfalls
|
|
28
|
+
|
|
29
|
+
- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
|
|
30
|
+
|
|
31
|
+
## Related documentation
|
|
32
|
+
|
|
33
|
+
- [README.md](README.md): scripts, container, deploy
|
|
34
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
|
|
@@ -1,11 +1,43 @@
|
|
|
1
1
|
# Agent guide
|
|
2
2
|
|
|
3
|
-
Payload CMS on Next.js App Router and PostgreSQL,
|
|
3
|
+
Payload CMS on Next.js App Router and PostgreSQL, in TypeScript on pnpm and Node.js `>=24.22.1 <25`. The API is REST at `/api`.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
| Task | Command |
|
|
8
|
+
| :---------------------------- | :--------------------------------------------------------- |
|
|
9
|
+
| Start with reload | `pnpm dev` |
|
|
10
|
+
| One test | `pnpm vitest run src/environment.test.ts -t "<test name>"` |
|
|
11
|
+
| Unit tests | `pnpm test`, or `pnpm test:coverage` |
|
|
12
|
+
| End-to-end tests | `pnpm test:e2e` |
|
|
13
|
+
| Regenerate after a collection | `pnpm generate:types`, `pnpm generate:importmap` |
|
|
14
|
+
| Create a migration | `pnpm migrate:create <name>` |
|
|
15
|
+
| What `pre-push` runs | `pnpm check` |
|
|
16
|
+
| Every check | `pnpm verify` |
|
|
17
|
+
| Render rules after a change | `pnpm rules:sync` |
|
|
18
|
+
|
|
19
|
+
## How it fits together
|
|
20
|
+
|
|
21
|
+
- `src/payload.config.ts` wires the collections in `src/collections/` to PostgreSQL. The site lives in `src/app/(frontend)/`, and `src/app/health/route.ts` serves `/health`.
|
|
22
|
+
- In development, Payload applies collection changes to the database directly. In production, the server applies the migrations in `src/migrations/` when it starts.
|
|
23
|
+
|
|
24
|
+
## Mandatory rules
|
|
25
|
+
|
|
26
|
+
1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
|
|
27
|
+
2. **Change the schema only through collections, then regenerate and commit.** Payload generates `src/app/(payload)/`, `src/payload-types.ts`, and `src/migrations/`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
|
|
28
|
+
3. **Put unit tests next to the code as `src/**/*.test.{ts,tsx}` and Playwright end-to-end tests in `test/` as `*.e2e.test.ts`.** Vitest collects only the first pattern.
|
|
29
|
+
4. **Ask the user before adding component tests.** They need a DOM test environment, and Vitest runs in Node.js.
|
|
30
|
+
5. **Read configuration through `requireEnvironment` in `src/environment.ts`.** Document each variable in `.env.example`.
|
|
31
|
+
|
|
32
|
+
## Known pitfalls
|
|
33
|
+
|
|
34
|
+
- **Database for `pnpm dev` and end-to-end tests**: both need a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm exec playwright install chromium` once before the first `pnpm test:e2e`.
|
|
35
|
+
- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
|
|
36
|
+
|
|
37
|
+
## Related documentation
|
|
38
|
+
|
|
39
|
+
- [README.md](README.md): environment variables, scripts, container, deploy
|
|
40
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
|
|
9
41
|
|
|
10
42
|
<!-- BEGIN:nextjs-agent-rules -->
|
|
11
43
|
|
|
@@ -1,19 +1,43 @@
|
|
|
1
1
|
# Agent guide
|
|
2
2
|
|
|
3
|
-
Turborepo workspace on pnpm. `apps/app` is
|
|
3
|
+
Turborepo workspace in TypeScript on pnpm and Node.js `>=24.22.1 <25`. `apps/app` is a Next.js site on port 3000. `apps/backoffice` is a Payload CMS on PostgreSQL on port 3001, with a REST API at `/api`.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- 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.
|
|
7
|
-
- 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`.
|
|
8
|
-
- 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.
|
|
9
|
-
- Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`. Document each variable in `.env.example`.
|
|
5
|
+
## Commands
|
|
10
6
|
|
|
11
|
-
|
|
7
|
+
| Task | Command |
|
|
8
|
+
| :---------------------------- | :----------------------------------------------------------------------------------------- |
|
|
9
|
+
| Start both apps with reload | `pnpm dev` |
|
|
10
|
+
| One test | `pnpm --filter ./apps/backoffice exec vitest run src/environment.test.ts -t "<test name>"` |
|
|
11
|
+
| Tests in one app | `TURBO_FILTER=--filter=./apps/app pnpm test` |
|
|
12
|
+
| Unit tests | `pnpm test`, or `pnpm test:coverage` |
|
|
13
|
+
| End-to-end tests | `pnpm test:e2e` |
|
|
14
|
+
| Regenerate after a collection | `pnpm generate:types`, `pnpm generate:importmap` |
|
|
15
|
+
| Create a migration | `pnpm migrate:create <name>` |
|
|
16
|
+
| What `pre-push` runs | `pnpm check` |
|
|
17
|
+
| Every check | `pnpm verify` |
|
|
18
|
+
| Render rules after a change | `pnpm rules:sync` |
|
|
12
19
|
|
|
13
|
-
##
|
|
20
|
+
## How it fits together
|
|
14
21
|
|
|
15
|
-
|
|
22
|
+
- Root scripts run lint, format, Knip, and the agent checks once for the workspace, and hand `build`, `test`, `typecheck`, and `depcruise` to Turborepo for each app. `TURBO_FILTER` narrows them; the default is every app.
|
|
23
|
+
- The site lives in `apps/app/app/`. The backoffice site lives in `apps/backoffice/src/app/(frontend)/`, its collections in `apps/backoffice/src/collections/`, and its config in `apps/backoffice/src/payload.config.ts`. The root `generate:*` and `migrate*` scripts run in the backoffice.
|
|
24
|
+
- In development, Payload applies collection changes to the database directly. In production, the backoffice applies the migrations in `apps/backoffice/src/migrations/` when it starts.
|
|
16
25
|
|
|
17
|
-
|
|
26
|
+
## Mandatory rules
|
|
18
27
|
|
|
19
|
-
|
|
28
|
+
1. **Follow `.agents/rules/`.** `.agents/rules.json` gives each rule's scope; Claude Code and Cursor load them. After changing either, run `pnpm rules:sync`; `pnpm check` fails on stale copies.
|
|
29
|
+
2. **Change the backoffice schema only through collections, then regenerate and commit.** Payload generates `apps/backoffice/src/app/(payload)/`, `apps/backoffice/src/payload-types.ts`, and `apps/backoffice/src/migrations/`; run `pnpm generate:types`, `pnpm generate:importmap`, and `pnpm migrate:create <name>`. Do not edit those files by hand.
|
|
30
|
+
3. **Put unit tests next to the code and Playwright end-to-end tests in `apps/app/test/` and `apps/backoffice/test/` as `*.e2e.test.ts`.** Vitest collects `apps/app/app/**/*.test.{ts,tsx}` and `apps/backoffice/src/**/*.test.{ts,tsx}`.
|
|
31
|
+
4. **Ask the user before adding component tests.** They need a DOM test environment, and Vitest runs in Node.js.
|
|
32
|
+
5. **Read backoffice configuration through `requireEnvironment` in `apps/backoffice/src/environment.ts`.** Document each variable in `.env.example`.
|
|
33
|
+
|
|
34
|
+
## Known pitfalls
|
|
35
|
+
|
|
36
|
+
- **Next.js docs live per app**: this Next.js version differs from your training data. Read the guide in `apps/app/node_modules/next/dist/docs/` or `apps/backoffice/node_modules/next/dist/docs/` before writing Next.js code; the workspace root has no `next` package.
|
|
37
|
+
- **Database for `pnpm dev` and end-to-end tests**: the backoffice needs a PostgreSQL database in `DATABASE_URL` and `PAYLOAD_SECRET` in `.env`; the README lists every variable. Run `pnpm exec playwright install chromium` once before the first `pnpm test:e2e`.
|
|
38
|
+
- **Agent shell gate**: `.agents/hooks/agent-shell-gate.sh` blocks a shell command that names a protected path such as `.agents`, `.cursor`, `.claude/rules`, or `.husky`, even when it only reads.
|
|
39
|
+
|
|
40
|
+
## Related documentation
|
|
41
|
+
|
|
42
|
+
- [README.md](README.md): environment variables, scripts, CI caching, container, deploy
|
|
43
|
+
- [CONTRIBUTING.md](CONTRIBUTING.md): prerequisites, Git hooks, pull requests
|