README

A modern, enterprise-ready Drupal 11 decoupled project template featuring GraphQL API, Next.js frontend, and a comprehensive component library. Built with recipes, Storybook, and TypeScript for rapid development and deployment.

Features

Backend (Drupal 11)

• GraphQL API - Fully configured GraphQL server with compose fragments
• Recipe System - Modular configuration using Drupal recipes
• Content Types - Pre-configured Article, Page, and Landing page types
• Paragraph Components - 15+ reusable paragraph components (Hero, Cards, Carousel, etc.)
• Media Management - Image, SVG, and video media types with responsive image styles
• Preview System - Live preview with decoupled iframe integration
• OAuth Authentication - Simple OAuth for secure API access

Frontend (Next.js 15)

• TypeScript - Full TypeScript support with type safety
• Tailwind CSS - Utility-first CSS framework with custom components
• Radix UI - Accessible component primitives
• Storybook - Component library documentation and testing
• Cypress - End-to-end testing framework
• GraphQL Client - Fully typed GraphQL queries and mutations
• Component Library - 25+ pre-built React components
• Responsive Design - Mobile-first responsive layouts

Development Environment

• DDEV - Containerized development environment
• Multiple Recipes - Demo, Government, University, and Nonprofit content
• Hot Reload - Development server with live reload
• Code Quality - ESLint, Prettier, and TypeScript checking

Requirements

• PHP 8.3 or higher
• Node.js 20+ (managed via nvm)
• Composer 2.x
• DDEV (recommended) or Docker
• Git

Installation

1. Create your project

composer create-project drupalninja/drupalx-decoupled:11.x-dev drupalx-decoupled-starter --no-interaction
cd drupalx-decoupled-starter

2. Set up permissions

chmod -R 755 web/sites/default/files/

3. Configure DDEV

ddev config

4. Install Drupal with recipes

ddev install

This command will:

• Start DDEV containers
• Install Composer dependencies
• Install Drupal with minimal profile
• Apply DrupalX GraphQL and Core recipes
• Configure OAuth consumer keys
• Generate admin login link

5. Set up Next.js frontend

In a new terminal tab:

cd nextjs
nvm install  # Installs Node.js 20+
npm install
npm run dev  # Starts development server on port 8080

6. Access your sites

• Drupal Admin: Use the login link generated by ddev install
• Next.js Frontend: https://your-project.ddev.site:8080
• GraphQL Explorer: https://your-project.ddev.site/graphql/explorer

Development Workflow

Available Recipes

The project includes several content recipes you can apply:

# Demo content (default)
ddev drush recipe ../recipes/drupalx-demo

# Government site content
ddev drush recipe ../recipes/drupalx-gov

# University site content  
ddev drush recipe ../recipes/drupalx-university

# Nonprofit site content
ddev drush recipe ../recipes/drupalx-nonprofit

Common Commands

Backend (Drupal):

# Start/stop DDEV
ddev start
ddev stop

# Database operations
ddev drush sql:dump > backup.sql
ddev drush sql:drop -y && ddev drush sql:cli < backup.sql

# Clear cache
ddev drush cr

# Generate login link
ddev drush uli

# Export/import config
ddev drush config:export
ddev drush config:import

Frontend (Next.js):

cd nextjs

# Development server
npm run dev

# Build production
npm run build
npm run start

# Linting
npm run lint

# Component development
npm run storybook

# Testing
npm run cypress

Component Development

Storybook - Component library and documentation:

cd nextjs
npm run storybook
# Access at http://localhost:6006

Cypress Testing - End-to-end testing:

cd nextjs
npm run cypress

Frontend Architecture

Technology Stack

• Next.js 15 - React framework with App Router
• TypeScript - Type safety and better developer experience
• Tailwind CSS - Utility-first CSS framework
• Radix UI - Headless UI components
• Shadcn/ui - Modern component library
• URQL - GraphQL client with caching
• Embla Carousel - Accessible carousel component
• Lucide React - Beautiful icon library

Component Library

The project includes 25+ pre-built components:

• Layout: Header, Footer, Container
• Content: Hero, Text, RichText, Media
• Navigation: MainMenu, Pager
• Interactive: Accordion, Carousel, Modal, Tabs
• Forms: Newsletter, Button, Input
• Data Display: Card, Gallery, Stats, Pricing
• Feedback: Alert, Badge, Tooltip

GraphQL Integration

• Fully typed GraphQL queries
• Fragment composition for reusable query parts
• Automatic TypeScript generation
• Optimized caching strategies

Troubleshooting

Common Issues

DDEV won't start:

ddev poweroff
ddev start

Port conflicts:

# Check what's using port 8080
lsof -i :8080
# Kill the process or change Next.js port
npm run dev -- --port 3000

GraphQL schema issues:

# Rebuild GraphQL schema
ddev drush cr
ddev drush graphql:rebuild

Next.js build errors:

cd nextjs
# Clear Next.js cache
rm -rf .next
npm run build

Permission issues:

# Fix file permissions
sudo chown -R $USER:$USER .
chmod -R 755 web/sites/default/files/

Node.js version issues:

# Ensure you're using Node 20+
nvm use 20
node --version

Support

For issues specific to this template:

• Check the GitHub Issues
• Review the CI workflow for testing examples

For general support:

• DDEV Documentation
• Next.js Documentation
• Drupal Documentation