@agility/create-next-app 1.0.0-beta.2

package/templates/PROMPTS.md

@@ -0,0 +1,410 @@
+# Prompt Engineering Guide for AI-Assisted Website Building
+
+This guide helps you write effective prompts to build a complete website with AI assistance and Agility CMS.
+
+## 🎯 Quick Start: Building from Scratch
+
+If you're starting with a **blank Agility CMS instance**, follow this workflow:
+
+### Phase 1: Initial Setup
+```
+"I'm starting with a blank Agility CMS instance. Help me set up the content structure for a [type of website]. What content models and page templates should I create in Agility CMS?"
+```
+
+### Phase 2: Create the Components
+```
+"Create the [component name] component with [specific features]. It should include [fields list] and use [design requirements]."
+```
+
+### Phase 3: Build the Pages
+```
+"Now that I have my components, help me build the [page name] page that uses [list of components]."
+```
+
+## 📋 The Perfect Prompt Formula
+
+For best results, structure your prompts with these elements:
+
+### 1. **What** (Component Type)
+Be specific about what you want to build:
+- ❌ BAD: "Add a blog"
+- ✅ GOOD: "Add a blog listing component"
+
+### 2. **Where** (Location)
+Specify if it's a component, page, or feature:
+- ❌ BAD: "Add navigation"
+- ✅ GOOD: "Add a navigation component to the MainTemplate"
+
+### 3. **How** (Behavior/Design)
+Include specific requirements:
+- ❌ BAD: "Add a hero"
+- ✅ GOOD: "Add a hero component with a background image, heading, subtitle, and CTA button"
+
+### 4. **Fields** (CMS Fields)
+List the Agility CMS fields you want:
+- ❌ BAD: "Add a testimonial carousel"
+- ✅ GOOD: "Add a testimonials carousel that fetches from a 'testimonials' content list with fields: quote, author, title, photo"
+
+### 5. **Style** (Visual Design)
+Include design specifics when relevant:
+- ✅ BETTER: "Add a testimonials carousel with cards, 3-column grid on desktop, centered text, and rounded images"
+
+## 🌟 Example Prompts (From Worst to Best)
+
+### Prompt Quality: ⭐ Poor
+```
+"Add a blog"
+```
+**Problem**: Too vague. AI doesn't know:
+- Is this a listing page or single post?
+- What fields should posts have?
+- Should it have pagination?
+- What's the design?
+
+### Prompt Quality: ⭐⭐ Basic
+```
+"Add a blog listing component with pagination"
+```
+**Better**: Specifies component type and a feature.
+**Still Missing**: Field structure, design requirements.
+
+### Prompt Quality: ⭐⭐⭐ Good
+```
+"Add a blog listing component with pagination that shows 9 posts per page. Each post should display title, excerpt, featured image, date, and author name."
+```
+**Much Better**: Includes specific requirements and data structure.
+**Could Add**: Design details, filtering, categories.
+
+### Prompt Quality: ⭐⭐⭐⭐ Excellent
+```
+"Add a blog listing component with the following requirements:
+
+**Data Source**: Fetch from 'blogPosts' content list in Agility CMS
+**Fields per post**: title, slug, excerpt, featuredImage, date, author (linked content), categories (linked content list)
+**Layout**: 3-column grid on desktop, 2 on tablet, 1 on mobile
+**Pagination**: Show 9 posts per page with next/prev buttons
+**Filtering**: Add category filter buttons at the top
+**Design**: Cards with rounded corners, hover effect, featured image at top
+**Sort**: Most recent first (date descending)"
+```
+**Excellent**: Complete specification, AI can build this perfectly!
+
+## 🏗️ Building a Complete Website: Step-by-Step Prompts
+
+### Starting Fresh with a Blank Agility Instance
+
+#### Step 1: Plan Your Content Structure
+```
+"I'm building a [business/portfolio/blog] website with a blank Agility CMS instance. Help me plan:
+1. What content models should I create? (Pages, Blog Posts, Team Members, etc.)
+2. What fields should each model have?
+3. What page components (modules) will I need?
+
+The site should have:
+- [List your main pages: Home, About, Blog, Contact, etc.]
+- [List your content types: Blog posts, team members, testimonials, etc.]
+- [List your requirements: multi-language, e-commerce, etc.]"
+```
+
+#### Step 2: Set Up Content Models in Agility CMS
+The AI will give you a plan. **You manually create these in Agility CMS**:
+1. Go to Settings > Content Definitions
+2. Create each content model with the suggested fields
+3. Come back and confirm it's done
+
+#### Step 3: Build Components One by One
+```
+"Create the Hero component for the homepage with these requirements:
+- Background image field (use AgilityPic)
+- Heading (h1)
+- Subheading
+- CTA button with text and link
+- Full-width layout
+- Dark overlay on background image for text readability
+- Centered text alignment"
+```
+
+#### Step 4: Create Content Lists
+```
+"Create a Blog Listing component:
+- Fetches from 'blogPosts' content list
+- Shows 9 posts per page in 3-column grid
+- Each card shows: featured image, title, excerpt (100 chars), date, author name, category
+- Pagination with next/prev buttons
+- Category filter dropdown
+- Responsive: 3 cols desktop, 2 tablet, 1 mobile"
+```
+
+#### Step 5: Build Individual Content Pages
+```
+"Create a blog post detail page component that:
+- Receives slug from URL params
+- Fetches single post from 'blogPosts' by slug
+- Shows: featured image, title, date, author with photo, content (rich text)
+- Displays categories as badges
+- Shows related posts at bottom (same category, limit 3)
+- Responsive layout with max-width container"
+```
+
+#### Step 6: Navigation & Layout
+```
+"Create a header component with:
+- Logo on the left (image field)
+- Navigation menu items from Agility sitemap
+- Mobile hamburger menu
+- Sticky header on scroll
+- Desktop: horizontal menu, Mobile: slide-out drawer"
+```
+
+## 🎨 Prompt Templates by Component Type
+
+### Hero Sections
+```
+"Create a [full-width/contained] hero component with:
+- [Background image/solid color/gradient]
+- [Heading/subheading/body text]
+- [CTA buttons count and style]
+- [Image position: left/right/background/none]
+- [Text alignment: left/center/right]
+- [Additional elements: badges/icons/stats]"
+```
+
+### Content Lists (Blog, Team, Products, etc.)
+```
+"Create a [content type] listing component:
+- Content list: '[referenceName]'
+- Fields to display: [field1, field2, field3]
+- Layout: [grid/list/masonry] - [X columns]
+- Items per page: [number]
+- Sorting: [field name] [asc/desc]
+- Filtering: [by category/tag/custom field]
+- Search: [yes/no]
+- Pagination: [numbered/next-prev/infinite-scroll]
+- Card design: [specific styling requirements]"
+```
+
+### Forms
+```
+"Create a [contact/newsletter/registration] form with:
+- Fields: [list fields with types]
+- Validation: [required fields, email format, etc.]
+- Submit action: [email/API/database]
+- Success message: [custom message]
+- Error handling: [inline/toast/modal]
+- Design: [styling requirements]"
+```
+
+### Carousels/Sliders
+```
+"Create a [testimonials/images/featured content] carousel:
+- Data source: [content list/static/mixed]
+- Items to show: [number] at a time
+- Auto-play: [yes/no] - [interval]
+- Navigation: [arrows/dots/both/none]
+- Transition: [slide/fade]
+- Responsive breakpoints: [mobile/tablet/desktop counts]"
+```
+
+### Navigation
+```
+"Create a [header/footer/sidebar] navigation:
+- Menu items from: [Agility sitemap/custom list]
+- Layout: [horizontal/vertical/mega-menu]
+- Mobile behavior: [hamburger/bottom-nav/slide-out]
+- Styling: [specific design requirements]
+- Active page indicator: [yes/no]
+- Dropdown submenus: [yes/no]"
+```
+
+## 🚀 Advanced Prompt Techniques
+
+### Multi-Step Features
+Break complex features into smaller prompts:
+
+```
+Step 1: "Create the data structure for a blog with categories and tags"
+Step 2: "Create the blog listing component with category filtering"
+Step 3: "Create the single blog post page"
+Step 4: "Add related posts section to single post page"
+Step 5: "Add a blog archive/category page"
+```
+
+### Referencing Existing Components
+```
+"Create a Team Members grid similar to the Blog Listing component but:
+- Fetches from 'teamMembers' instead
+- Shows 4 columns instead of 3
+- No pagination (show all)
+- Different card style: circular images, name, title, bio"
+```
+
+### Iterative Improvements
+```
+"Update the Hero component to add:
+- A background video option (alternative to image)
+- Animated text reveal on page load
+- Parallax scrolling effect
+- Keep all existing functionality"
+```
+
+## ✅ Pre-Build Checklist
+
+Before asking AI to build components, make sure you have:
+
+### In Agility CMS:
+- [ ] Content models created (Pages, Posts, Team, etc.)
+- [ ] Fields defined for each model
+- [ ] Sample content added (at least 2-3 items per list)
+- [ ] Page templates created (if needed)
+- [ ] Sitemap structure planned
+
+### In Your Prompt:
+- [ ] Specific component name
+- [ ] Data source (content list reference name)
+- [ ] All field names spelled exactly as in Agility CMS
+- [ ] Layout requirements (grid columns, responsive behavior)
+- [ ] Specific design requirements
+- [ ] Any interactive behaviors needed
+
+## 🎓 Learning from Examples
+
+### Example: Building a Portfolio Site
+
+**Prompt 1 - Planning:**
+```
+"I'm building a portfolio website for a freelance designer with a blank Agility CMS instance. Help me plan the content structure. The site needs:
+- Homepage with hero, about section, featured projects showcase
+- Projects page showing all projects in a grid
+- Individual project detail pages
+- About page with bio and skills
+- Contact page with form
+
+What content models, modules, and fields should I create in Agility CMS?"
+```
+
+**Prompt 2 - Hero Component:**
+```
+"Create a Hero component for the homepage with:
+- Full-width background image (AgilityPic)
+- Centered text with h1 heading 'headline' field
+- Subheading 'tagline' field
+- Two CTA buttons: 'primaryCTA' and 'secondaryCTA' (with text and link)
+- Dark overlay on image for text contrast (40% opacity)
+- Height: 80vh on desktop, 60vh on mobile"
+```
+
+**Prompt 3 - Projects Grid:**
+```
+"Create a Projects Grid component:
+- Fetches from 'projects' content list (referenceName: 'projects')
+- Shows 6 projects in 3-column grid (desktop), 2 columns (tablet), 1 column (mobile)
+- Each project card displays:
+  - Thumbnail image (use AgilityPic)
+  - Project title
+  - Client name
+  - Category badge
+  - Hover effect: scale up slightly and show "View Project" overlay
+- Links to individual project pages using slug
+- No pagination, show all projects"
+```
+
+**Prompt 4 - Project Detail Page:**
+```
+"Create a Project Detail component for individual project pages:
+- Fetches single project by slug from URL
+- Layout:
+  - Full-width hero image (project.featuredImage)
+  - Container with max-width for content:
+    - Project title (h1)
+    - Client name and date
+    - Category badges
+    - Project description (rich text)
+    - Image gallery grid (3 columns)
+    - Technologies used (list with icons)
+    - Link to live site (if available)
+- Related projects at bottom (same category, limit 3)
+- Responsive: single column on mobile"
+```
+
+## 🔍 Troubleshooting Prompts
+
+If the AI's output isn't quite right, use these follow-up prompts:
+
+### Component Not Rendering
+```
+"The [component name] isn't showing up. Can you check:
+1. Is it registered in the index.ts file?
+2. Does the reference name match Agility CMS exactly?
+3. Are there any TypeScript errors?
+4. Show me the current registration code"
+```
+
+### Wrong Data Structure
+```
+"The [component name] is showing [undefined/error]. The actual field structure in Agility CMS is:
+- field1: [type]
+- field2: [type]
+Please update the component to match this exact structure."
+```
+
+### Styling Issues
+```
+"Update the [component name] styling to:
+- [Specific change 1]
+- [Specific change 2]
+Keep all existing functionality unchanged."
+```
+
+## 💡 Pro Tips
+
+1. **Start Small**: Build one component at a time, test it, then move to the next
+2. **Be Specific**: The more details you provide, the better the result
+3. **Reference Existing**: Point to similar components when asking for new ones
+4. **Test Often**: Build, test in Agility CMS, then iterate
+5. **Use Exact Names**: Always use the exact reference names from Agility CMS
+6. **Think Responsive**: Always mention mobile/tablet/desktop requirements
+7. **Content First**: Create content in Agility CMS before building components
+8. **Type Safety**: Ask for TypeScript interfaces when needed
+
+## 📚 Common Patterns Quick Reference
+
+| What You Want | Prompt Template |
+|---------------|-----------------|
+| Page Module | "Create a [name] component with fields: [list]. Layout: [description]" |
+| Content List | "Create a [type] listing from '[referenceName]' with [X] items per page" |
+| Single Item | "Create a [type] detail page that fetches by slug from '[referenceName]'" |
+| Form | "Create a [purpose] form with fields: [list]. Submit to [destination]" |
+| Navigation | "Create [header/footer] nav from Agility sitemap with [behavior]" |
+| Interactive | "Create a [component] with [interaction] using client component pattern" |
+
+## 🎯 Your First Website Prompt
+
+Ready to start? Try this comprehensive first prompt:
+
+```
+"I have a blank Agility CMS instance and want to build a [business type] website. Help me set up the initial structure:
+
+**Pages Needed:**
+1. Homepage (hero, services overview, testimonials, CTA)
+2. About page (team members, company story)
+3. Services page (list of services)
+4. Blog (listing and detail pages)
+5. Contact page (form)
+
+**Content to Manage:**
+- Service items (title, description, icon, features list)
+- Team members (name, title, bio, photo, social links)
+- Blog posts (title, content, featured image, author, date, categories)
+- Testimonials (quote, author, company, photo)
+
+Please provide:
+1. A list of content models to create in Agility CMS with their fields
+2. A list of page modules (components) I'll need
+3. The order I should build them in
+
+After I confirm I've created the content models in Agility CMS, we'll build each component step by step."
+```
+
+---
+
+**Remember**: The AI can't create content models in Agility CMS for you, but it can tell you exactly what to create and then build all the code to display that content beautifully! 🎨✨

package/templates/README.md

@@ -0,0 +1,281 @@
+# Agility CMS + Next.js Project
+
+This project was created with [`create-next-agility-app`](https://github.com/agility/create-next-agility-app).
+
+**✨ Built for AI-assisted development** - Includes comprehensive documentation for Claude Code, Cursor, GitHub Copilot, and all AI coding tools.
+
+## 🚀 Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see your site.
+
+## 📋 Prerequisites
+
+You need an **Agility CMS instance** to use this project. Most users will already have an existing instance with content.
+
+### Need a Blank Instance?
+If you want to start completely from scratch with a blank Agility CMS instance, contact **support@agilitycms.com** to request one. Then follow the [BLANK-INSTANCE-SETUP.md](./BLANK-INSTANCE-SETUP.md) guide.
+
+### Have an Existing Instance?
+If you already have an Agility CMS instance with content, you're ready to go! Just configure your `.env.local` with your API keys and start building components for your existing content models.
+
+## 📚 Documentation
+
+This project includes extensive documentation optimized for both developers and AI assistants:
+
+### 🚀 Start Here
+- **[PROMPTS.md](./PROMPTS.md)** - How to write effective prompts for AI assistants
+- **[EXAMPLE-PROMPTS.md](./EXAMPLE-PROMPTS.md)** - Copy-paste prompt library
+- **[.claude/QUICK-START.md](./.claude/QUICK-START.md)** - Get started in 5 minutes
+- **[BLANK-INSTANCE-SETUP.md](./BLANK-INSTANCE-SETUP.md)** - For blank instances (contact support@agilitycms.com first)
+
+### 📖 Guides
+- **[DEVELOPMENT.md](./DEVELOPMENT.md)** - Complete development guide
+- **[agents.md](./agents.md)** - AI assistant guide (for Claude Code, Cursor, etc.)
+- **[.claude/README.md](./.claude/README.md)** - Full documentation index
+- **[docs/README.md](./docs/README.md)** - Detailed documentation
+
+### For Building with AI
+- [Prompt Engineering Guide](./PROMPTS.md) - Write better prompts
+- [Example Prompts Library](./EXAMPLE-PROMPTS.md) - Ready-to-use prompts
+
+### For Developers
+- [Agility CMS Overview](./docs/01-agility-cms-overview.md) - How Agility CMS works
+- [Creating Components](./docs/03-creating-components.md) - Build features
+- [Common Components](./docs/08-common-components.md) - Ready-to-use examples
+
+## 🤖 AI-Assisted Development
+
+This project is designed for AI-assisted development.
+
+**Getting started with AI?**
+1. **[PROMPTS.md](./PROMPTS.md)** - Learn how to write effective prompts
+2. **[EXAMPLE-PROMPTS.md](./EXAMPLE-PROMPTS.md)** - Copy and customize ready-made prompts
+
+**Quick Examples:**
+```
+"Add a blog listing component with pagination"
+"Create a hero section with background image"
+"Implement a testimonials carousel"
+"Add a contact form with validation"
+```
+
+💡 **Tip**: The more specific your prompts, the better the results! See [PROMPTS.md](./PROMPTS.md) for the formula.
+
+### Platform-Specific Tips
+
+**Claude Code:**
+```
+Just ask naturally - documentation is auto-discovered!
+"Add a blog with categories"
+```
+
+**Cursor:**
+```
+Reference docs explicitly:
+@.claude/docs/03-creating-components.md create a testimonials carousel
+```
+
+**GitHub Copilot:**
+```
+Use workspace context:
+@workspace /new Create a team members grid following Agility CMS patterns
+```
+
+## 📂 Project Structure
+
+```
+src/
+├── app/
+│   ├── api/                      # API routes for Agility CMS
+│   │   ├── preview/             # Preview mode endpoints
+│   │   ├── revalidate/          # Webhook for cache revalidation
+│   │   └── dynamic-redirect/    # Dynamic page redirects
+│   └── [locale]/
+│       └── [...slug]/
+│           └── page.tsx          # All pages route through here
+├── components/
+│   ├── agility-components/       # CMS components (add yours here)
+│   │   ├── index.ts             # Component registry
+│   │   └── RichTextArea.tsx     # Example component
+│   └── agility-pages/            # Page templates
+│       ├── index.ts             # Template registry
+│       └── MainTemplate.tsx     # Main template
+└── lib/
+    ├── cms/                      # CMS helper functions
+    │   ├── getAgilityPage.ts
+    │   ├── getContentItem.ts
+    │   ├── getContentList.ts
+    │   └── ...
+    └── i18n/
+        └── config.ts             # Locale configuration
+```
+
+## 🔗 API Routes
+
+This project includes built-in API routes for Agility CMS:
+
+### Preview Mode
+- **`/api/preview`** - Enables preview/draft mode for viewing unpublished content
+- **`/api/preview/exit`** - Exits preview mode and returns to published content
+
+### Cache Revalidation
+- **`/api/revalidate`** - Webhook endpoint for on-demand cache revalidation when content changes in Agility CMS
+
+### Dynamic Redirects
+- **`/api/dynamic-redirect`** - Redirects to the correct URL for a dynamic page based on ContentID
+
+**Configure webhooks in Agility CMS:** Settings > Webhooks > Add Webhook → Point to `https://yourdomain.com/api/revalidate`
+
+## 🔧 Environment Variables
+
+Configure your Agility CMS connection in `.env.local`:
+
+```env
+AGILITY_GUID=your-instance-guid
+AGILITY_API_FETCH_KEY=your-fetch-api-key
+AGILITY_API_PREVIEW_KEY=your-preview-api-key
+AGILITY_LOCALES=en-us
+AGILITY_SITEMAP=website
+```
+
+## 🎯 Common Tasks
+
+### Add a New Component
+
+1. Create file: `src/components/agility-components/YourComponent.tsx`
+2. Register in: `src/components/agility-components/index.ts`
+3. Create component model in Agility CMS (Settings > Content Definitions > New Module)
+4. Add to page in CMS
+
+**See:** [.claude/docs/03-creating-components.md](./.claude/docs/03-creating-components.md)
+
+### Fetch Content Lists
+
+```typescript
+import { getContentList } from "@/lib/cms/getContentList";
+
+const posts = await getContentList({
+  referenceName: "posts",
+  locale: "en-us",
+  take: 10,
+});
+```
+
+**See:** [.claude/docs/04-data-fetching.md](./.claude/docs/04-data-fetching.md)
+
+### Add Multi-Language Support
+
+1. Update `AGILITY_LOCALES` in `.env.local`
+2. Update `src/lib/i18n/config.ts`
+3. Add locale content in Agility CMS
+
+**See:** [.claude/docs/06-localization.md](./.claude/docs/06-localization.md)
+
+## 🏗️ Development Commands
+
+```bash
+npm run dev       # Start development server
+npm run build     # Build for production
+npm run start     # Start production server
+npm run lint      # Run ESLint
+```
+
+## 📦 What's Included
+
+- ✅ **Agility CMS Integration** - Full SDK with type-safe helpers
+- ✅ **Next.js 15** - App Router with Server Components
+- ✅ **Multi-Locale Support** - Built-in internationalization
+- ✅ **TypeScript** - Full type safety
+- ✅ **Caching** - ISR with on-demand revalidation
+- ✅ **Preview Mode** - See draft content before publishing
+- ✅ **AI-Friendly Docs** - Optimized for all AI coding tools
+
+## 🔗 Key Concepts
+
+### Components (Called "Modules" in CMS)
+Reusable building blocks that editors add to pages. Created in Agility CMS, implemented as React components.
+
+### Page Templates
+Define page layout with zones. Components are placed in these zones.
+
+### Content Lists
+Collections like blog posts, testimonials, team members. Fetched with `getContentList()`.
+
+### Locales
+Multi-language support. Default locale (en-us) has clean URLs, others are prefixed (/fr/, /es/).
+
+## 📖 Learn More
+
+### Documentation
+- **[Development Guide](./DEVELOPMENT.md)** - Comprehensive dev guide
+- **[Quick Start](./.claude/QUICK-START.md)** - 5-minute setup
+- **[Full Docs](./.claude/README.md)** - Complete documentation
+
+### Agility CMS Resources
+- [Agility CMS Documentation](https://agilitycms.com/docs)
+- [Agility CMS Help Center](https://help.agilitycms.com)
+- [Agility CMS Community](https://community.agilitycms.com)
+
+### Next.js Resources
+- [Next.js Documentation](https://nextjs.org/docs)
+- [Learn Next.js](https://nextjs.org/learn)
+- [Next.js GitHub](https://github.com/vercel/next.js)
+
+## 🚢 Deployment
+
+### Deploy on Vercel
+
+The easiest way to deploy:
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new)
+
+1. Push your code to GitHub
+2. Import repository in Vercel
+3. Add environment variables
+4. Deploy!
+
+### Environment Variables for Production
+
+Set these in your hosting platform:
+- `AGILITY_GUID`
+- `AGILITY_API_FETCH_KEY`
+- `AGILITY_API_PREVIEW_KEY`
+- `AGILITY_SECURITY_KEY` (for webhooks)
+- `AGILITY_LOCALES`
+- `AGILITY_SITEMAP`
+
+## 🐛 Troubleshooting
+
+### Build Fails
+- Check all environment variables are set
+- Ensure components are registered in `index.ts`
+- Verify Agility CMS content exists
+
+### Preview Mode Not Working
+- Check `AGILITY_API_PREVIEW_KEY` is set
+- Verify preview key matches in CMS
+- Clear cookies and try again
+
+### Components Not Rendering
+- Verify component is registered in `agility-components/index.ts`
+- Check component reference name matches CMS exactly (case-sensitive)
+- Ensure component model exists in Agility CMS
+
+**More help:** See [.claude/docs/11-troubleshooting.md](./.claude/docs/11-troubleshooting.md) (if available)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read the [contribution guidelines](https://github.com/agility/create-next-agility-app/blob/main/CONTRIBUTING.md) first.
+
+## 📄 License
+
+MIT
+
+---
+
+**Built with [Agility CMS](https://agilitycms.com) ❤️**