Skip to main content

Developer Experience (DX) Tools

The DX Plugin provides modern development tooling for WordPress projects, enabling TypeScript, SCSS compilation, and enhanced block development.

Overview​

The DX Plugin enhances WordPress development with:

  • Laravel Mix - Asset compilation for TypeScript and SCSS
  • SCSS Variables - Auto-generated from theme.json design tokens
  • ACF Blocks - Automated block registration
  • Pattern System - Enhanced block pattern development
  • BEM Methodology - Enforced component-based styling

Installation​

Requirements​

  • WordPress 6.0+
  • PHP 8.0+
  • Node.js 18+
  • ACF Pro

Setup Steps​

  1. Install the DX Plugin

    # Via WP CLI
    wp plugin install developer-experience --activate

  2. Create dx/ folder in theme

    wp-content/themes/your-theme/
    └── dx/
        ├── acf-blocks/
        ├── patterns/
        ├── scss/
        │   ├── _variables.scss      # Auto-generated
        │   ├── blocks/
        │   └── patterns/
        └── ts/
            ├── blocks/
            └── global/

  3. Initialize package.json

    cd wp-content/themes/your-theme/dx
    npm init -y
    npm install laravel-mix sass typescript --save-dev

  4. Configure webpack.mix.js

    const mix = require('laravel-mix');

    mix.ts('ts/global/main.ts', 'dist/js')
       .sass('scss/main.scss', 'dist/css')
       .setPublicPath('dist');

SCSS Integration​

Auto-Generated Variables​

The DX Plugin automatically generates SCSS variables from theme.json:

// dx/scss/_variables.scss (auto-generated)
$color-primary: #1D2433;
$color-secondary: #F5F4F0;
$font-family-body: Inter, sans-serif;
$font-family-heading: Bebas Neue, sans-serif;
$space-20: 20px;
$space-40: 40px;

Using Variables​

// dx/scss/patterns/_hero.scss
.hero {
  background-color: $color-primary;
  padding: $space-80 0;

  &__title {
    font-family: $font-family-heading;
    color: $color-secondary;
  }

  &__content {
    font-family: $font-family-body;
  }
}

ACF Blocks​

Block Structure​

dx/acf-blocks/
└── hero/
    ├── block.json
    ├── hero.php
    ├── hero.scss
    └── hero.ts (optional)

block.json​

{
  "name": "acf/hero",
  "title": "Hero",
  "description": "Hero section with heading and CTA",
  "category": "theme",
  "icon": "cover-image",
  "keywords": ["hero", "header"],
  "acf": {
    "mode": "edit",
    "renderTemplate": "hero.php"
  },
  "supports": {
    "align": ["full", "wide"],
    "mode": false
  }
}

Block Template (hero.php)​

<?php
$heading = get_field('heading');
$cta_text = get_field('cta_text');
$cta_link = get_field('cta_link');
?>

<section class="hero alignfull">
  <div class="hero__container">
    <?php if ($heading): ?>
      <h1 class="hero__title"><?php echo esc_html($heading); ?></h1>
    <?php endif; ?>

    <?php if ($cta_text && $cta_link): ?>
      <a href="<?php echo esc_url($cta_link); ?>" class="hero__cta btn btn--primary">
        <?php echo esc_html($cta_text); ?>
      </a>
    <?php endif; ?>
  </div>
</section>

Block Patterns​

Pattern Structure​

dx/patterns/
└── hero-pattern/
    ├── pattern.php
    └── hero-pattern.scss

Pattern Registration​

<?php
/**
 * Title: Hero Pattern
 * Slug: theme/hero-pattern
 * Categories: hero
 * Block Types: core/cover
 */
?>

<!-- wp:cover {"dimRatio":50,"className":"hero-pattern"} -->
<div class="wp-block-cover hero-pattern">
  <!-- Block content -->
</div>
<!-- /wp:cover -->

Commands​

Development​

# Watch for changes
npm run watch

# Development build
npm run dev

# Production build
npm run prod

Helpful Scripts​

Add to package.json:

{
  "scripts": {
    "dev": "mix",
    "watch": "mix watch",
    "prod": "mix --production",
    "lint": "eslint ts/**/*.ts",
    "build": "npm run prod"
  }
}

BEM Methodology​

DX enforces BEM (Block Element Modifier) for consistent styling:

// Block
.hero { }

// Element
.hero__title { }
.hero__content { }
.hero__cta { }

// Modifier
.hero--dark { }
.hero__title--large { }

Best Practices​

  1. One block per file - Each component in its own SCSS file
  2. Flat specificity - Avoid deep nesting
  3. No ID selectors - Use classes only
  4. Consistent naming - Follow BEM strictly

Troubleshooting​

Common Issues​

Variables not updating​

  • Run npm run dev to regenerate variables
  • Check theme.json syntax is valid

TypeScript errors​

  • Ensure tsconfig.json is properly configured
  • Check import paths are correct

Blocks not appearing​

  • Verify block.json is valid JSON
  • Check PHP template path is correct
  • Clear block editor cache
Performance

Use npm run prod before deployment to ensure assets are minified and optimized.