{"id":48342303,"url":"https://github.com/agility/nextjs-demo-site-2026","last_synced_at":"2026-04-05T05:04:42.967Z","repository":{"id":316267079,"uuid":"1015598661","full_name":"agility/nextjs-demo-site-2026","owner":"agility","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-27T02:30:21.000Z","size":34658,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T07:44:29.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://nextjs-demo-site-2025.publishwithagility.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agility.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-07T18:41:54.000Z","updated_at":"2026-01-26T20:46:01.000Z","dependencies_parsed_at":"2025-11-10T20:10:02.329Z","dependency_job_id":null,"html_url":"https://github.com/agility/nextjs-demo-site-2026","commit_stats":null,"previous_names":["agility/nextjs-demo-site-2025","agility/nextjs-demo-site-2026"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agility/nextjs-demo-site-2026","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agility%2Fnextjs-demo-site-2026","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agility%2Fnextjs-demo-site-2026/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agility%2Fnextjs-demo-site-2026/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agility%2Fnextjs-demo-site-2026/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agility","download_url":"https://codeload.github.com/agility/nextjs-demo-site-2026/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agility%2Fnextjs-demo-site-2026/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31424932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T05:04:16.873Z","updated_at":"2026-04-05T05:04:42.944Z","avatar_url":"https://github.com/agility.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agility CMS Next.js Demo Site\n\n\u003e Modern headless CMS website with AI-powered search, internationalization, and advanced caching\n\nA production-ready Next.js demo site showcasing Agility CMS integration with React 19, TypeScript, Tailwind CSS v4, and AI-powered search capabilities.\n\n## 🎯 Get This Reference Implementation\n\nThis is a fully-featured reference implementation showcasing Agility CMS capabilities. To get your own copy of this solution:\n\n**[Contact our sales team](https://agilitycms.com/contact-us/get-a-demo)** and we'll clone this solution for you and help you get set up with a POC (Proof of Concept).\n\nOur team will:\n- Clone the complete solution to your environment\n- Set up your Agility CMS instance with the content models\n- Help you configure the necessary integrations\n- Guide you through the setup process\n\n---\n\n## ✨ Features\n\n- **Headless CMS Integration** - Full Agility CMS integration with dynamic page routing\n- **AI-Powered Search** - Azure OpenAI + Algolia integration for intelligent content search\n- **Internationalization** - Multi-locale support with clean URL routing\n- **Advanced Caching** - Next.js cache tags with automatic revalidation\n- **Preview Mode** - Draft content preview with Agility CMS integration\n- **Audience \u0026 Region Personalization** - URL-based personalization system\n- **View Transitions** - Smooth page transitions using React ViewTransition API\n- **Type Safety** - Strongly-typed environment variables and CMS content\n- **Modern Stack** - Next.js 15.5.3, React 19, Tailwind CSS v4, TypeScript\n\n## 🤖 For AI Coding Assistants\n\nThis project includes comprehensive instructions for AI coding assistants. **See [`AGENTS.md`](AGENTS.md)** for complete development guidelines, architecture patterns, CMS integration details, and coding conventions.\n\nThe `AGENTS.md` file provides:\n- Complete project architecture and patterns\n- Agility CMS integration guidelines\n- Component conventions and standards\n- TypeScript patterns and type definitions\n- Development workflows and best practices\n- Common gotchas and debugging tips\n\nSupported AI assistants: Cursor, GitHub Copilot, Windsurf, Claude Code, OpenAI Codex, and Google Jules.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 20+\n- npm or yarn\n- Agility CMS instance (get one at [agilitycms.com](https://agilitycms.com))\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd demosite2025\n\n# Install dependencies\nnpm install\n\n# Copy environment variables\ncp .env.example .env.local\n\n# Edit .env.local with your Agility CMS credentials\n```\n\n### Environment Variables\n\nCreate a `.env.local` file with the following required variables:\n\n```env\n# Agility CMS Configuration\nAGILITY_GUID=your-instance-guid\nAGILITY_API_FETCH_KEY=your-fetch-api-key\nAGILITY_API_PREVIEW_KEY=your-preview-api-key\nAGILITY_SECURITY_KEY=your-security-key\nAGILITY_LOCALES=en-us,fr-ca,es-mx\nAGILITY_SITEMAP=website\nAGILITY_FETCH_CACHE_DURATION=60\nAGILITY_PATH_REVALIDATE_DURATION=60\n\n# PostHog Analytics (Optional)\nNEXT_PUBLIC_POSTHOG_KEY=your-posthog-key\nNEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com\n\n# Node Environment\nNODE_ENV=development\n\n# Build Hook (Optional - for redirect rebuilds)\nBUILD_HOOK_URL=https://your-build-hook-url\n```\n\n### Development\n\n```bash\n# Start development server with Turbopack\nnpm run dev\n\n# Run prebuild (rebuilds redirect cache - required before production build)\nnpm run prebuild\n\n# Build for production\nnpm run build\n\n# Start production server\nnpm run start\n\n# Run linter\nnpm run lint\n```\n\n**⚠️ Important**: Always run `npm run prebuild` before `npm run build` to rebuild the redirect cache.\n\n## 📁 Project Structure\n\n```\nsrc/\n├── app/                    # Next.js App Router\n│   ├── [locale]/          # Internationalized routes\n│   │   └── [...slug]/     # Dynamic page routes\n│   └── api/               # API routes\n│       ├── ai/            # AI search endpoints\n│       ├── preview/       # Preview mode handling\n│       ├── revalidate/    # Cache revalidation webhook\n│       └── dynamic-redirect/ # Content ID redirects\n├── components/\n│   ├── agility-components/ # CMS-connected components\n│   ├── agility-pages/      # Page templates\n│   ├── ai-agent/          # AI chat interface\n│   ├── ai-elements/       # AI-powered UI elements\n│   ├── ai-search/         # AI search components\n│   ├── header/            # Navigation components\n│   └── footer/            # Footer components\n├── lib/\n│   ├── cms/               # Agility CMS SDK wrappers\n│   ├── cms-content/       # Content processing utilities\n│   ├── ai/                # AI integration utilities\n│   ├── posthog/           # Analytics integration\n│   ├── hooks/             # React hooks\n│   ├── i18n/              # Internationalization config\n│   ├── types/             # TypeScript definitions\n│   └── utils/             # Utility functions\n└── public/                # Static assets\n```\n\n## 🏗️ Architecture\n\n### Headless CMS Pattern\n\nContent managed in Agility CMS → API fetching → Next.js rendering\n\n- **Page Routing**: Dynamic via Agility's sitemap\n- **Content Zones**: `\u003cContentZone name=\"main-content-zone\"\u003e` renders CMS modules\n- **Module System**: Components auto-registered via `getModule()` function\n\n### Key File Relationships\n\n- `src/middleware.ts` → Handles preview, redirects, i18n routing\n- `src/lib/cms/` → All CMS API abstractions with caching\n- `src/components/agility-components/` → CMS-bound components\n\n## 🎨 Technology Stack\n\n- **Framework**: Next.js 15.5.3 (App Router)\n- **React**: 19.1.0\n- **TypeScript**: 5.x\n- **Styling**: Tailwind CSS v4 (CSS-file based)\n- **CMS**: Agility CMS (@agility/nextjs 15.0.7)\n- **Animations**: Motion 12.23.0\n- **AI**: Azure OpenAI + Algolia\n- **Analytics**: PostHog\n- **Icons**: Heroicons v2, React Icons\n\n## 📝 Key Concepts\n\n### CMS Component Registration\n\nAll Agility CMS components must be registered in `src/components/agility-components/index.ts`:\n\n```typescript\nimport { ComponentName } from \"./ComponentName\"\n\nconst allModules = [\n  { name: \"ComponentName\", module: ComponentName },\n  // ... other modules\n]\n```\n\n### Standard Component Pattern\n\n```typescript\nexport const ComponentName = async ({ module, languageCode }: UnloadedModuleProps) =\u003e {\n  const { fields, contentID } = await getContentItem\u003cIComponentType\u003e({\n    contentID: module.contentid,\n    languageCode,\n  })\n\n  return (\n    \u003cdiv data-agility-component={contentID}\u003e\n      \u003cdiv data-agility-field=\"fieldName\"\u003e{fields.fieldName}\u003c/div\u003e\n    \u003c/div\u003e\n  )\n}\n```\n\n### Nested Content Fetching\n\n```typescript\n// Get parent content with nested reference\nconst { fields: { nestedRef: { referencename } } } = await getContentItem\u003cMainType\u003e({\n  contentID: module.contentid,\n  languageCode,\n})\n\n// Fetch nested collection separately\nconst nestedItems = await getContentList\u003cNestedType\u003e({\n  referenceName: referencename,\n  languageCode,\n  take: 20\n})\n```\n\n### Image Handling\n\nAlways use `\u003cAgilityPic\u003e` for Agility CMS images:\n\n```typescript\nimport { AgilityPic } from \"@agility/nextjs\"\n\n\u003cAgilityPic\n  image={imageField}\n  fallbackWidth={600}\n  className=\"w-full h-auto\"\n  data-agility-field=\"image\"\n/\u003e\n```\n\n### Rich Text Rendering\n\nUse `renderHTML()` from Agility SDK:\n\n```typescript\nimport { renderHTML } from \"@agility/nextjs\"\n\n\u003cdiv\n  data-agility-field=\"textblob\"\n  data-agility-html\n  className=\"prose dark:prose-invert\"\n  dangerouslySetInnerHTML={renderHTML(htmlField)}\n/\u003e\n```\n\n## 🌍 Internationalization\n\nThe site supports multiple locales with clean URL routing:\n\n- **Default Locale**: No path prefix (e.g., `/blog`)\n- **Other Locales**: Explicit prefix (e.g., `/fr/blog`, `/es/blog`)\n\nLocales are configured via `AGILITY_LOCALES` environment variable (comma-separated).\n\n## 🎯 Audience \u0026 Region Personalization\n\nURL-based personalization system using query parameters:\n\n```typescript\n// Client component\nconst { selectedAudience, setAudience } = useAudienceRegionParams(audiences, regions)\n\n// Server component\nconst audienceContentID = await getAudienceContentID(searchParams, locale)\n```\n\n## 🔄 Caching \u0026 Revalidation\n\n- **Automatic Cache Tags**: All CMS fetches include Next.js cache tags\n- **Tag Format**: `agility-content-{contentID|referenceName}-{locale}`\n- **Revalidation**: 60-second cache + tag-based invalidation\n- **Webhook**: `/api/revalidate` receives Agility CMS publish events\n\n## 🔍 AI Search\n\nAI-powered search using Azure OpenAI and Algolia:\n\n- **Endpoint**: `/api/ai/search`\n- **Features**: Streaming responses, tool calling, rate limiting\n- **Components**: Chat interface, message history, markdown rendering\n\n## 🚢 Deployment\n\n### Pre-build Steps\n\n1. Set all required environment variables\n2. Run `npm run prebuild` to rebuild redirect cache\n3. Run `npm run build` for production build\n\n### Environment-Specific Notes\n\n- **Preview Mode**: Automatically enabled in development\n- **Redirects**: Bloom filter cache must be rebuilt before production\n- **Cache Revalidation**: Configure webhook in Agility CMS to point to `/api/revalidate`\n\n## 📚 Documentation\n\n### In-Site Documentation (`/docs`)\n\n**⚠️ Important**: This demo site includes an in-site documentation system accessible at `/docs`. This is **specific to this demo site** and is **not part of a normal Agility CMS site**. It's included here to document:\n\n- Demo site architecture and implementation patterns\n- Instance-specific Agility CMS configuration\n- Codebase structure and developer guides\n- Content editor workflows for this specific demo\n\nThe documentation is built using MDX routing with markdown files in the `docs/` folder. It includes:\n- **Admin Guides** - Instance configuration, content models, components, workflows\n- **Architect Guides** - Site architecture, component design, content architecture, integrations\n- **Content Editor Guides** - Common tasks, components, content models, pages\n- **Developer Guides** - Codebase structure, environment variables, multi-locale setup, personalization, view transitions\n\n**Note**: For generic Agility CMS training and documentation, see the [Official Agility CMS Training Guide](https://agilitycms.com/docs/training-guide).\n\n### Quick Reference\n- [AI Agent Instructions](AGENTS.md) - Comprehensive development guidelines (single source of truth)\n- [Cursor Rules](.cursorrules) - Cursor-specific file (references AGENTS.md)\n- [Copilot Instructions](.github/copilot-instructions.md) - GitHub Copilot-specific file (references AGENTS.md)\n- [Windsurf Rules](.windsurf/rules/project.md) - Windsurf-specific file (references AGENTS.md)\n- [Claude Context](CLAUDE.md) - Stub file pointing to AGENTS.md\n\n### Full Documentation\n- **[📖 In-Site Documentation](https://demo.agilitycms.com/docs)** - Complete documentation guide (demo site specific)\n- **[📖 Documentation Index](docs/README.md)** - Documentation source files\n\n**Developer Docs:**\n- [Codebase Guide](docs/developer/codebase/README.md) - Project structure and implementation\n- [Environment Variables](docs/developer/ENVIRONMENT_VARIABLES.md) - Strongly typed env configuration\n- [Multi-Locale Implementation](docs/developer/MULTI_LOCALE_IMPLEMENTATION.md) - i18n setup and routing\n- [Audience \u0026 Region System](docs/developer/AUDIENCE_REGION_SYSTEM.md) - Personalization system\n- [View Transitions](docs/developer/VIEW_TRANSITIONS.md) - Page transition implementation\n\n**Agility CMS Training:**\n- [Content Editor Guide](docs/content-editor/README.md) - Creating and managing content\n- [Administrator Guide](docs/admin/README.md) - Instance configuration\n- [Architect Guide](docs/architect/README.md) - Architecture decisions\n- [URL Patterns](docs/AGILITY_CMS_URL_PATTERNS.md) - Agility CMS interface URLs\n\n**External Resources:**\n- [Official Agility CMS Docs](https://agilitycms.com/docs) - Agility CMS documentation\n- [Official Training Guide](https://agilitycms.com/docs/training-guide) - Generic Agility CMS training\n\n## 🐛 Common Issues\n\n### Preview Mode Not Working\n- Ensure `agilitypreviewkey` param is present (not just `AgilityPreview`)\n- Check that `AGILITY_API_PREVIEW_KEY` is set correctly\n\n### Redirects Not Working\n- Run `npm run prebuild` before building\n- Check that `data/redirections-bloom-filter.json` exists\n\n### Components Not Rendering\n- Verify component is registered in `src/components/agility-components/index.ts`\n- Check that component name matches Agility CMS module name (case-insensitive)\n\n### Cache Not Updating\n- Verify webhook is configured in Agility CMS\n- Check `/api/revalidate` endpoint is accessible\n- Ensure `AGILITY_SECURITY_KEY` matches webhook configuration\n\n## 🤝 Contributing\n\n1. Follow existing code patterns and conventions\n2. Register new components in `index.ts`\n3. Use TypeScript for all new code\n4. Follow Tailwind CSS v4 patterns\n5. Add proper TypeScript interfaces for CMS content\n6. Test with multiple locales if applicable\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Resources\n\n- [Agility CMS Documentation](https://agilitycms.com/docs)\n- [Next.js Documentation](https://nextjs.org/docs)\n- [Tailwind CSS v4](https://tailwindcss.com/docs)\n- [React 19](https://react.dev)\n\n## 🌐 Live Demo\n\n- **Production Site**: [demo.agilitycms.com](https://demo.agilitycms.com)\n- **GitHub Repository**: [github.com/agility/nextjs-demo-site-2025](https://github.com/agility/nextjs-demo-site-2025)\n\n---\n\nBuilt with ❤️ using [Agility CMS](https://agilitycms.com) and [Next.js](https://nextjs.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagility%2Fnextjs-demo-site-2026","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagility%2Fnextjs-demo-site-2026","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagility%2Fnextjs-demo-site-2026/lists"}