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:

drupalninja / drupalx-decoupled

Maintainers

Details