@core / kit-cms

1.0.1 ▾

1.0.1

인증됨MIT

GitHub

Next.js 자체 관리 사이트 키트: /admin에서 블록 페이지, 미디어, 메뉴, 설정, 폼, 사용자 편집

코드파일 38개컨텍스트약 1.8천토큰검사 통과

약 1.8천토큰→ src/app/(cms)/AGENTS.md→ .cursor/rules/genpm-core-kit-cms.mdc

이것이 AI가 src/app/(cms)에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

@core/kit-cms — rules for AI agents

Purpose

Turns a Next.js (App Router) site into a self-managed one: /admin where non-technical people edit pages built with blocks, images, menus, site settings, forms, redirects and users, with drafts, signed previews, scheduled publishing and roles. Glue only: all logic lives in @core/admin, content, media, rich-text, blocks, site, seo, forms, search, auth and rbac (the last two arrive through @core/admin). Public routes: pages created in the admin (/[...slug]), /search, /sitemap.xml, /robots.txt, /llms.txt. Base for kit-blog, kit-landing and kit-store.

Map

admin/[[...path]]/page.tsx — panel (server checks session + admin:access). admin/login/page.tsx — OAuth sign-in.
api/admin/[...path] — admin API. api/media/uploads… — uploads. api/preview, api/exit-preview — draft mode. api/forms/[key] — form posts. api/cron — @core/jobs. api/search — JSON search.
[...slug]/page.tsx — pages of the pages collection (redirects before the 404). search/page.tsx — results.
_lib/page.tsx — CmsPage, pageMetadata. _lib/home.tsx — home page from the home entry. _lib/session.ts.
_components/ — admin client app and the media / richText field editors.
_templates/genpm/*.ts — the project's registration files. _templates/middleware.ts — redirects middleware. _templates/layout.tsx — root layout for a new site. _templates/env.example — every variable the kit and its packages read.
_lib/maintenance.ts — daily cms.maintenance job (prunes rate limits and old jobs), loaded by api/cron.
_scripts/create-owner.ts — gives the first signed-in user the owner role (and creates the default roles).
_scripts/setup-schedules.ts — schedules the daily jobs of the installed kits (cms.maintenance, search.reindex, store.maintenance, experiments.prune) and queues the first reindex.

Integration

Check Next ≥ 15.5 with App Router, src/app and the @/* → src/* alias. Without src/: install with --dest app/(cms) and adapt @/ imports. GenPM packages import each other with .ts extensions: tsconfig.json needs "allowImportingTsExtensions": true (Next projects already have "noEmit": true). Works with webpack and Turbopack. In next.config set htmlLimitedBots: /.*/: metadata comes from the database, and without it Next 15 streams <title>, description and canonical into <body> for every client except a few bots (Lighthouse, link previews and some crawlers miss them).
Env: copy _templates/env.example to the project's .env.example (merge if it exists; Next's default .gitignore has .env*, so add a line !.env.example) and the real values to .env.local. Required: DATABASE_URL, AUTH_SECRET, one OAuth provider (GITHUB_CLIENT_ID/SECRET or GOOGLE_…), STORAGE_*, EMAIL_FROM + RESEND_API_KEY, SITE_URL, CONTENT_PREVIEW_SECRET (≥ 32 chars), ANTISPAM_SECRET, CRON_SECRET. With STORAGE_DRIVER=local also mount the storage route (src/lib/storage/AGENTS.md, Integration 1).
Mount the @core/auth routes (app/auth/login/[provider], app/auth/callback/[provider], app/auth/logout) as its AGENTS.md says.
Copy _templates/genpm/*.ts to src/genpm/ (skip files that exist and merge by hand). These files belong to the project: later kits add lines to them. Copy _templates/middleware.ts to src/middleware.ts (or merge into the existing one).
Migrations: GenPM does not install dev tools — run src/lib/db/AGENTS.md steps 3–5 (drizzle-kit + tsx, the db:generate / db:migrate scripts), generate one migration for all packages and apply it where a database exists.
Schedule GET /api/cron every minute with Authorization: Bearer $CRON_SECRET (e.g. vercel.json crons). Once the database is migrated, the person runs npx tsx "src/app/(cms)/_scripts/setup-schedules.ts" (idempotent; it schedules the daily jobs of every installed kit, so run it again after adding another kit).
The person signs in once at /admin/login, then runs npx tsx "src/app/(cms)/_scripts/create-owner.ts" <their email>. Never run it for them with an email they did not give you.
New site: create src/app/page.tsx with export { default, generateMetadata } from './(cms)/_lib/home'; and create the home page in the admin (blocks: hero, features, cta…). Existing site: follow "Retrofit" below.
Root layout: new site → copy _templates/layout.tsx to src/app/layout.tsx. Existing layout → import @/lib/ui/ui.css and @/lib/blocks/blocks.css, render menus with getMenu('header') / getMenu('footer') and the site name with getSiteSettings() (@core/site), and add export const dynamic = 'force-dynamic' (it reads the database; without it next build tries to prerender and fails without DATABASE_URL).
Verify: npx tsc --noEmit and npx next build pass without a database. Then, with one: sign in at /admin, edit a page, open "Preview", publish, and see the change on the public URL.
Delete every src/lib/*/adapters/hono.ts (rm src/lib/*/adapters/hono.ts): they import hono, which a Next project does not install, and tsc checks every file. Keep adapters/next.ts.

Retrofit (make an existing site editable)

Follow the @core/content procedure page by page, one commit per page: inventory visible literals → a singleton per page (or a collection when repeated) defined in src/genpm/content.ts → seed with the current values (seedEntry) → replace literals with typed reads → compare the rendered HTML before/after (must be identical). Keep markup and design; only the data source changes: skip className="ui-root" on <body> and don't add buildMetadata tags the site did not have (keep its titles and descriptions, now read from the CMS). Local images go to @core/media with their alt text; SVG (which @core/media rejects) stays in public/ with its path in a text field. Keep the root layout's existing header/footer markup and feed it from getSiteSettings() / getMenu(). Existing routes keep priority over [...slug]. Non-Next sites (static HTML, Astro, Vite): out of scope for 1.0 — say so.

Conventions

Page sections are blocks registered in src/genpm/blocks.ts; add new blocks there, never per-page components.
Admin resources are registered in src/genpm/admin.ts; never write a custom admin page for a resource.
The pages entry with slug home is /; other slugs map to /<slug>.
Default roles: editor publishes pages but cannot see users or settings beyond content; author edits only own entries.

Don't

Don't invent legal texts (privacy, terms, imprint): create the pages empty with a "pending review" note for the owner.
Don't expose /admin or /api in the sitemap, and don't remove robots: noindex from admin pages.
Don't bypass CRON_SECRET or call runDue() from a public route.
Don't grant roles or create owners from code paths reachable by visitors.

# @core/kit-cms — rules for AI agents

## Purpose
Turns a Next.js (App Router) site into a self-managed one: `/admin` where non-technical people edit pages built with
blocks, images, menus, site settings, forms, redirects and users, with drafts, signed previews, scheduled publishing
and roles. Glue only: all logic lives in @core/admin, content, media, rich-text, blocks, site, seo, forms, search,
auth and rbac (the last two arrive through @core/admin). Public routes: pages created in the admin (`/[...slug]`), `/search`, `/sitemap.xml`, `/robots.txt`,
`/llms.txt`. Base for kit-blog, kit-landing and kit-store.

## Map
- `admin/[[...path]]/page.tsx` — panel (server checks session + `admin:access`). `admin/login/page.tsx` — OAuth sign-in.
- `api/admin/[...path]` — admin API. `api/media/uploads…` — uploads. `api/preview`, `api/exit-preview` — draft mode.
  `api/forms/[key]` — form posts. `api/cron` — @core/jobs. `api/search` — JSON search.
- `[...slug]/page.tsx` — pages of the `pages` collection (redirects before the 404). `search/page.tsx` — results.
- `_lib/page.tsx` — `CmsPage`, `pageMetadata`. `_lib/home.tsx` — home page from the `home` entry. `_lib/session.ts`.
- `_components/` — admin client app and the `media` / `richText` field editors.
- `_templates/genpm/*.ts` — the project's registration files. `_templates/middleware.ts` — redirects middleware.
  `_templates/layout.tsx` — root layout for a new site. `_templates/env.example` — every variable the kit and its packages read.
- `_lib/maintenance.ts` — daily `cms.maintenance` job (prunes rate limits and old jobs), loaded by `api/cron`.
- `_scripts/create-owner.ts` — gives the first signed-in user the `owner` role (and creates the default roles).
- `_scripts/setup-schedules.ts` — schedules the daily jobs of the installed kits (`cms.maintenance`, `search.reindex`,
  `store.maintenance`, `experiments.prune`) and queues the first reindex.

## Integration
1. Check Next ≥ 15.5 with App Router, `src/app` and the `@/*` → `src/*` alias. Without `src/`: install with `--dest app/(cms)` and adapt `@/` imports.
   GenPM packages import each other with `.ts` extensions: `tsconfig.json` needs `"allowImportingTsExtensions": true`
   (Next projects already have `"noEmit": true`). Works with webpack and Turbopack. In `next.config` set
   `htmlLimitedBots: /.*/`: metadata comes from the database, and without it Next 15 streams `<title>`, description and
   canonical into `<body>` for every client except a few bots (Lighthouse, link previews and some crawlers miss them).
2. Env: copy `_templates/env.example` to the project's `.env.example` (merge if it exists; Next's default `.gitignore`
   has `.env*`, so add a line `!.env.example`) and the real values to `.env.local`. Required: `DATABASE_URL`, `AUTH_SECRET`, one OAuth provider
   (`GITHUB_CLIENT_ID/SECRET` or `GOOGLE_…`), `STORAGE_*`, `EMAIL_FROM` + `RESEND_API_KEY`, `SITE_URL`,
   `CONTENT_PREVIEW_SECRET` (≥ 32 chars), `ANTISPAM_SECRET`, `CRON_SECRET`. With `STORAGE_DRIVER=local` also mount the
   storage route (`src/lib/storage/AGENTS.md`, Integration 1).
3. Mount the @core/auth routes (`app/auth/login/[provider]`, `app/auth/callback/[provider]`, `app/auth/logout`) as its AGENTS.md says.
4. Copy `_templates/genpm/*.ts` to `src/genpm/` (skip files that exist and merge by hand). These files belong to the project:
   later kits add lines to them. Copy `_templates/middleware.ts` to `src/middleware.ts` (or merge into the existing one).
5. Migrations: GenPM does not install dev tools — run `src/lib/db/AGENTS.md` steps 3–5 (`drizzle-kit` + `tsx`, the
   `db:generate` / `db:migrate` scripts), generate one migration for all packages and apply it where a database exists.
6. Schedule `GET /api/cron` every minute with `Authorization: Bearer $CRON_SECRET` (e.g. `vercel.json` crons). Once the
   database is migrated, the person runs `npx tsx "src/app/(cms)/_scripts/setup-schedules.ts"` (idempotent; it schedules
   the daily jobs of every installed kit, so run it again after adding another kit).
7. The person signs in once at `/admin/login`, then runs `npx tsx "src/app/(cms)/_scripts/create-owner.ts" <their email>`.
   Never run it for them with an email they did not give you.
8. New site: create `src/app/page.tsx` with `export { default, generateMetadata } from './(cms)/_lib/home';` and create
   the `home` page in the admin (blocks: hero, features, cta…). Existing site: follow "Retrofit" below.
9. Root layout: new site → copy `_templates/layout.tsx` to `src/app/layout.tsx`. Existing layout → import `@/lib/ui/ui.css`
   and `@/lib/blocks/blocks.css`, render menus with `getMenu('header')` / `getMenu('footer')` and the site name with
   `getSiteSettings()` (@core/site), and add `export const dynamic = 'force-dynamic'` (it reads the database; without it
   `next build` tries to prerender and fails without `DATABASE_URL`).
10. Verify: `npx tsc --noEmit` and `npx next build` pass without a database. Then, with one: sign in at `/admin`, edit a
    page, open "Preview", publish, and see the change on the public URL.
11. Delete every `src/lib/*/adapters/hono.ts` (`rm src/lib/*/adapters/hono.ts`): they import `hono`, which a Next
    project does not install, and `tsc` checks every file. Keep `adapters/next.ts`.

## Retrofit (make an existing site editable)
Follow the @core/content procedure page by page, one commit per page: inventory visible literals → a singleton per
page (or a collection when repeated) defined in `src/genpm/content.ts` → seed with the current values (`seedEntry`) →
replace literals with typed reads → compare the rendered HTML before/after (must be identical). Keep markup and design;
only the data source changes: skip `className="ui-root"` on `<body>` and don't add `buildMetadata` tags the site did not
have (keep its titles and descriptions, now read from the CMS). Local images go to @core/media with their alt text;
SVG (which @core/media rejects) stays in `public/` with its path in a text field. Keep the root layout's existing
header/footer markup and feed it from `getSiteSettings()` / `getMenu()`. Existing routes keep priority over
`[...slug]`. Non-Next sites (static HTML, Astro, Vite): out of scope for 1.0 — say so.

## Conventions
- Page sections are blocks registered in `src/genpm/blocks.ts`; add new blocks there, never per-page components.
- Admin resources are registered in `src/genpm/admin.ts`; never write a custom admin page for a resource.
- The `pages` entry with slug `home` is `/`; other slugs map to `/<slug>`.
- Default roles: `editor` publishes pages but cannot see users or settings beyond content; `author` edits only own entries.

## Don't
- Don't invent legal texts (privacy, terms, imprint): create the pages empty with a "pending review" note for the owner.
- Don't expose `/admin` or `/api` in the sitemap, and don't remove `robots: noindex` from admin pages.
- Don't bypass `CRON_SECRET` or call `runDue()` from a public route.
- Don't grant roles or create owners from code paths reachable by visitors.

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/app/(cms)/_templates/env.example읽기 전용 · bb5d8e0

# Environment for a site with @core/kit-cms. Copy to the project's `.env.example` (and add `!.env.example` to
# .gitignore); put real values in `.env.local`, never in the repository. Secrets: at least 32 random characters
# (e.g. `openssl rand -base64 32`).

# Database (any Postgres)
DATABASE_URL=postgres://user:password@localhost:5432/site

# Sign-in (@core/auth): at least one OAuth provider
AUTH_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
# GOOGLE_CLIENT_ID=
# GOOGLE_CLIENT_SECRET=

# Public URL (https in production). SEO_NOINDEX=1 on staging (noindex everywhere).
SITE_URL=http://localhost:3000
# SEO_NOINDEX=1
# Extra hosts allowed as absolute redirect targets, comma-separated (@core/site)
# SITE_REDIRECT_HOSTS=

# Content (@core/content): signed draft previews; default locale of entries
CONTENT_PREVIEW_SECRET=
# CONTENT_DEFAULT_LOCALE=en

# Forms and spam protection (@core/forms, @core/antispam)
ANTISPAM_SECRET=
FORMS_NOTIFY_TO=
# FORMS_WEBHOOK_SECRET=
# Optional captcha: Turnstile or hCaptcha
# TURNSTILE_SITE_KEY=
# TURNSTILE_SECRET_KEY=
# HCAPTCHA_SECRET_KEY=
# Client IP for rate limits: header set by your proxy/CDN, or X-Forwarded-For minus N trusted proxies
# ANTISPAM_IP_HEADER=cf-connecting-ip
# ANTISPAM_TRUSTED_PROXIES=1

# Background jobs (@core/jobs): GET /api/cron with Authorization: Bearer $CRON_SECRET every minute
CRON_SECRET=

# Files (@core/storage, @core/media): S3, R2 or MinIO…
STORAGE_DRIVER=s3
STORAGE_BUCKET=
STORAGE_ENDPOINT=
STORAGE_REGION=auto
STORAGE_ACCESS_KEY_ID=
STORAGE_SECRET_ACCESS_KEY=
STORAGE_PUBLIC_URL=
# …or local disk for development (mount app/api/storage/[[...key]]/route.ts, see src/lib/storage/AGENTS.md):
# STORAGE_DRIVER=local
# STORAGE_SECRET=
# STORAGE_PUBLIC_URL=http://localhost:3000
# STORAGE_LOCAL_DIR=.storage   (add it to .gitignore)
# Image resizing by your CDN (see src/lib/media/AGENTS.md)
# MEDIA_TRANSFORM=

# Email (@core/email). Without RESEND_API_KEY, under `next dev`, emails are printed to the console.
EMAIL_FROM="Site <hello@example.com>"
RESEND_API_KEY=
# APP_NAME=Site
# SMTP instead of Resend: EMAIL_PROVIDER=smtp, SMTP_URL=smtps://user:pass@host:465 (install nodemailer)

버전	커밋	게시일	검사
1.0.1	bb5d8e0	3시간 전	검사 통과

$genpm add @core/kit-cms

주입 위치: src/app/(cms)
커밋
태그: v1.0.1
필요: @core/admin ^1.0.0 @core/blocks ^1.0.0 @core/content ^1.1.0 @core/forms ^1.0.0 @core/media ^1.0.0 @core/rich-text ^1.0.0 @core/search ^1.0.0 @core/seo ^1.0.0 @core/site ^1.0.0
npm: next >=15.5.0react ^19.0.0zod ^4.0.0
품질: 100/100
사용처: 3
설치 수: 0 / 30일
게시일: 3시간 전 · genpm-system

README 배지

[![genpm](https://api.genpm.net/v1/badge/@core/kit-cms.svg)](https://genpm.net/p/@core/kit-cms)