@itgkey/integrate-itgkey

Add itgkey to an existing Next.js app with minimal setup.

Usage

npx @itgkey/integrate-itgkey@latest

Or target a specific directory:

npx @itgkey/integrate-itgkey@latest ./my-next-app

The CLI will:

• Add keystatic.config.ts
• Add page-builder.ts
• Add editor/device-visibility-* helper files for responsive block visibility controls
• Add app/renderBlocks.tsx and app/LivePreviewPage.tsx (or src/app/...)
• Add app/page-records.ts for page collection reads and nested navigation
• Add app/CmsWidget.tsx and app/CmsSessionBeacon.tsx when scaffolding CMS-aware routes
• Add API route files under app/api/keystatic/[...params]/route.ts (or src/app/...)
• Add app/api/link-options/route.ts for page/post link lookups
• Add admin UI route files under app/keystatic (or src/app/keystatic)
• Add dynamic frontend routes (/ and /[...slug]) with block rendering
• Add posts route rendering with block content (/posts/[slug])
• Add starter content files (pages/hi.yaml, settings/index.yaml, posts/first-post.yaml)
• Add itgkey-blocks.ts for user-defined component/block schemas
• Add .github/prompts/itgkey-migration-agent.prompt.md for Codex-driven project-specific migration
• Add postcss.config.js and tailwind.config.js so block styling works like the template
• Optionally install required runtime + styling dependencies

When existing frontend routes are detected, the CLI defaults to preserve mode:

• Keeps your existing frontend route files and layout files
• Adds preview routes under /itgkey-preview
• Adds app/itgkey-responsive.tsx helper to convert existing page sections into responsive blocks

When existing itgkey files are detected, the CLI can rebuild managed files to the latest scaffold and remove legacy preview/live [slug] routes that can shadow the new [...slug] routes.

Migration rule: user-facing copy should be CMS-driven.

• During migration, map current page titles/text/buttons into block fields in Keystatic.
• Avoid hardcoding site copy in components so content stays editable from /keystatic.
• Treat each existing frontend component/section as its own block (no mega catch-all block).
• After migration, verify multiple routes work (at minimum: /, /keystatic, /itgkey-preview, /itgkey-preview/[slug], and one real /posts/[slug] route if posts exist).