Skip to content

CLAUDE.md

Latest commit

 

History

History
181 lines (148 loc) · 7.82 KB

CLAUDE.md

File metadata and controls

181 lines (148 loc) · 7.82 KB

WordPress Vite Boilerplate

Proyecto WordPress Bedrock con Docker y tema Block Theme (FSE). El tema vive en app/web/app/themes/__THEME_SLUG__/.

Estructura del Repositorio

project/
├── docker-compose.yml           # Docker: PHP-FPM, Nginx, MariaDB, MailHog, phpMyAdmin
├── docker/                      # Dockerfiles y configs
├── setup.js                     # Interactive setup (run once, then deleted)
├── app/                         # Bedrock application root
│   ├── composer.json            # Bedrock deps (WP core, plugins via wpackagist)
│   ├── config/application.php   # Main WP config (reads .env)
│   └── web/app/themes/<theme>/  # Block Theme (FSE)

Estructura del Tema

app/web/app/themes/<theme>/
├── blocks/                  # ACF Blocks v3 (block.json + render.php)
├── includes/                # PHP classes (PSR-4, namespace __NAMESPACE__\)
│   ├── ACF/                 # ACF field groups
│   ├── Helpers/             # ViteHelper.php
│   └── Theme/               # ThemeSetup.php
├── parts/                   # Template parts (header, footer)
├── templates/               # Block templates FSE (index.html, single.html, etc.)
├── resources/
│   ├── fonts/               # Custom fonts (copied to public/ by Vite)
│   ├── styles/              # SCSS: base/, components/, sections/, templates/, frontend/
│   └── scripts/             # TS: components/, frontend/
├── public/                  # Generated by Vite (DO NOT edit)
├── functions.php
├── theme.json
├── vite.config.js
└── tsconfig.json

Comandos Principales

# Docker
docker compose up -d              # Start services
docker compose down               # Stop services
docker compose exec php sh        # Shell into PHP container

# Bedrock (from app/)
cd app && composer install        # Install WP core + plugins
composer require wpackagist-plugin/name  # Add plugin

# Theme (from app/web/app/themes/<theme>/)
npm run dev                       # Vite dev server with HMR (localhost:5173)
npm run build                     # Build once
npm run production                # Optimized build
composer install                  # Theme PHP deps

# Remote sync — powered by wp-dev-sync (from project root)
npm run sync                      # Watch + auto-sync to remote (wp-dev-sync watch)
npm run sync:push                 # Manual push (wp-dev-sync push)
npm run sync:pull                 # Manual pull (wp-dev-sync pull)

# WordPress CLI
docker compose exec php wp cache flush
docker compose exec php wp db export

Convenciones de Codigo

PHP (PSR-12, PHP 8.2+)

  • declare(strict_types=1); y defined('ABSPATH') || exit; al inicio de archivos
  • Clases: PascalCase, archivos PascalCase.php, namespace __NAMESPACE__\
  • Funciones: snake_case, Variables: snake_case o camelCase (consistente)
  • Constantes: UPPER_SNAKE_CASE
  • 4 espacios de indentacion, maximo 120 caracteres por linea
  • Usar features de PHP 8.2: readonly classes, enums, constructor property promotion, named arguments, match expressions, nullsafe operator, union types
  • Escapar salida: esc_html(), esc_attr(), esc_url(), wp_kses_post()
  • Sanitizar entrada: sanitize_email(), sanitize_text_field()
  • Verificar nonces y capabilities en formularios/AJAX
  • Prefijo __THEME_SLUG___ para hooks y filters
  • Constantes del tema: THEME_DIR, THEME_URI, THEME_VERSION, THEME_SITENAME

JavaScript/TypeScript

  • Archivos: kebab-case.js/ts en resources/scripts/
  • Variables/Funciones: camelCase, Clases: PascalCase, Constantes: UPPER_SNAKE_CASE
  • Usar const por defecto, let solo cuando necesario, nunca var
  • Modulos ES6 con import/export, path alias @/ para resources/
  • Preferir metodos inmutables: toSorted(), toReversed(), toSpliced(), with()
  • Optional chaining (?.) y nullish coalescing (??)
  • Sistema de inicializacion: clases con static initializeAll() llamadas desde main.ts en DOMContentLoaded
  • Entry: resources/scripts/frontend/main.ts

TypeScript Especifico

  • strict: true en tsconfig.json
  • Minimizar any, usar unknown cuando tipo desconocido
  • readonly para propiedades inmutables
  • Tipos explicitos en APIs publicas, inferencia para lo obvio
  • Composicion sobre herencia

SCSS/CSS

  • Archivos: kebab-case.scss en resources/styles/
  • BEM obligatorio: .block, .block__element, .block--modifier
  • Maximo 3 niveles de nesting
  • Entry: resources/styles/frontend/main.scss (importa todo)
  • Media queries obligatorio con mixins (NO usar @media directo): 
    @use '../../media-queries' as mq;
@include mq.respond-above(sm);    // > breakpoint
@include mq.respond-below(md);    // < breakpoint
@include mq.respond-between(sm, md);
  • Breakpoints: xs:576px, sm:768px, md:1200px, lg:1440px, xl:1600px
  • Media queries anidadas dentro del selector, no en bloques separados
  • Usar CSS moderno: container queries, cascade layers, :has(), native nesting, oklch(), color-mix(), clamp()
  • Variables CSS para theming dinamico, variables SCSS para logica
  • Mobile-first approach

ACF Blocks v3

Estructura: blocks/nombre/block.json + blocks/nombre/render.php

block.json obligatorio:

{
  "acf": {
    "mode": "preview",
    "blockVersion": 3,
    "autoInlineEditing": true,
    "renderTemplate": "render.php"
  }
}

Workflow nuevo block:

  1. Crear blocks/mi-block/block.json + render.php
  2. Campos ACF en includes/ACF/MiBlock.php
  3. Agregar 'MiBlock' al array $acf_files en functions.php
  4. Agregar 'mi-block' al array $blocks en ThemeSetup.php
  5. Estilos en resources/styles/sections/_mi-block.scss
  6. Importar en resources/styles/frontend/main.scss
  7. Ver blocks/example-cta/ como referencia completa

Blocks estructurales: "multiple": false, "reusable": false

Blocks de contenido: "anchor": true, "align": ["wide", "full"], "multiple": true

Accesibilidad (WCAG 2.1 Level AA)

  • HTML semantico: <header>, <nav>, <main>, <article>, <section>, <aside>, <footer>
  • Jerarquia de encabezados h1-h6 sin saltar niveles
  • ARIA labels en elementos interactivos, aria-expanded, aria-controls, aria-live
  • Navegacion completa por teclado, indicadores de focus visibles
  • Contraste minimo 4.5:1 (texto normal), 3:1 (texto grande y componentes UI)
  • alt en todas las imagenes, aria-hidden="true" en decorativas
  • prefers-reduced-motion: reduce respetado en animaciones
  • Skip links en header
  • Labels asociados en formularios, mensajes de error con aria-describedby

Vite y Assets

  • HMR: npm run dev crea public/hot, ViteHelper detecta y carga desde dev server
  • host.docker.internal permite al contenedor PHP alcanzar Vite en el host
  • Fuentes: Vite copia resources/fonts/ a public/fonts/, theme.json usa file:./public/fonts/
  • Produccion: npm run production, WordPress carga desde public/ via manifest.json
  • SCSS se importa desde el entry TS: main.ts importa ../../styles/frontend/main.scss
  • Site Editor / wp-admin: no encolar enqueue_asset() (JS + cliente Vite) en enqueue_block_assets cuando is_admin(). Usar solo ViteHelper::enqueue_compiled_styles_only() para el iframe del editor.

Archivos que NO se Committean

.env, app/.env, app/vendor/, app/web/wp/, app/web/app/plugins/*, node_modules/, vendor/, public/hot, public/css/, public/js/, public/.vite/, public/manifest.json

Integraciones

  • Bedrock: Content dir /app, WordPress core via Composer, plugins via wpackagist
  • ACF Pro: Field groups en includes/ACF/, blocks en blocks/
  • Vite 5: Build tool con HMR, vite-plugin-static-copy para fuentes
  • Composer PSR-4: __NAMESPACE__\ a includes/
  • Remote Sync: wp-dev-sync CLI para sync con servidor remoto (SSH/FTP)