Joomla Component Template

A minimal, modern development template for creating Joomla components with live preview and automatic code quality checks.

Tech Stack

• Pug - Clean, indentation-based HTML templating
• Sass (SCSS) - Modern CSS with variables and nesting (using @use modules)
• stylelint - SCSS linting and auto-formatting
• Prettier - Code formatting
• Autoprefixer - Automatic vendor prefixes
• Browser-sync - Live reload development server
• Husky - Git hooks for automatic linting
• lint-staged - Run linters on staged files only

Features

• ✅ Live Preview System - See components with automatic hot reload
• ✅ Component-based Structure - Reusable Pug mixins with sample data
• ✅ Modern Sass - Uses @use instead of deprecated @import
• ✅ Automatic Linting - Git hooks ensure code quality before commits
• ✅ Human-readable Output - Generated HTML/CSS is formatted, not minified
• ✅ Minimal & Unopinionated - Clean starter with no forced design decisions
• ✅ Image Optimization - WebP conversion with multiple sizes

Getting Started

Prerequisites

• Node.js 18+ and pnpm 9+
• Git (for the automatic linting hooks)

1. Use This Template

Click "Use this template" on GitHub or clone:

git clone <your-repo-url>
cd joomla-template

2. Install Dependencies

pnpm install

This automatically:

• Installs all packages
• Sets up Husky git hooks
• Configures lint-staged

3. Start Development Mode

pnpm run dev

This will:

• Build all components
• Start watch mode for auto-rebuild
• Launch live server at http://localhost:3000
• Open your browser automatically

4. Create Your First Component

Create a new folder in src/pug/components/:

src/pug/components/my-component/
├── my-component.pug          # Pug template with mixin
├── my-component.config.js    # Preview configuration

Example: my-component.pug

mixin my-component(data)
  .my-component
    h3.my-component__title= data.title
    p.my-component__description= data.description

Example: my-component.config.js

module.exports = {
  name: 'My Component',
  description: 'A simple component',
  preview: {
    sampleData: {
      title: 'Hello World',
      description: 'This is my component'
    }
  }
};

5. Add Component Styles

Create src/scss/components/_my-component.scss:

@use "../base/variables" as *;

.my-component {
  padding: 2rem;

  &__title {
    font-size: 1.5rem;
    margin-bottom: 1rem;
  }

  &__description {
    color: #666;
  }

  @media (max-width: $breakpoint-md) {
    padding: 1rem;
  }
}

Import it in src/scss/main.scss:

@use 'components/my-component';

6. View Your Component

Your component will automatically appear in the preview at http://localhost:3000

Available Commands

Command	Description
pnpm run dev	Start development mode (build + watch + live server)
pnpm run build	Build production files
pnpm run build:previews	Generate preview files only
pnpm run watch	Watch for changes (no live server)
pnpm run serve	Serve preview at localhost:3000
pnpm run lint	Check SCSS code quality
pnpm run lint:fix	Auto-fix SCSS issues
pnpm run optimize:images	Optimize images (WebP + responsive sizes)
pnpm run deploy	Deploy via FTP (requires .env setup)

Project Structure

src/
├── pug/
│   ├── components/          # Your components
│   │   └── [component-name]/
│   │       ├── [name].pug
│   │       └── [name].config.js
│   └── preview/             # Preview templates
├── scss/
│   ├── base/                # Variables, reset, utilities
│   ├── components/          # Component styles
│   └── main.scss            # Main entry point
└── assets/images/           # Images to optimize

dist/
├── preview/                 # Preview builds (localhost:3000)
└── production/              # Production builds
    ├── components/          # Component HTML
    ├── css/                 # Compiled CSS
    └── assets/              # Optimized images

How It Works

Development Workflow

1. Edit Pug/SCSS files in src/
2. Auto-rebuild happens automatically (watch mode)
3. Browser refreshes with updated preview
4. Linting runs automatically on git commit

Component Preview System

Each component has:

• A Pug mixin for reusable HTML
• A config file with sample data for preview
• SCSS styles using BEM methodology

The preview system renders each component in a clean container with:

• Component name header
• Sample data from config
• Live-reloaded styles

Automatic Code Quality

Git Hooks (Husky + lint-staged):

• Runs stylelint on staged .scss files before commit
• Auto-fixes formatting issues
• Blocks commit if linting fails

Configuration Files

• .stylelintrc.json - SCSS linting rules
• .husky/pre-commit - Git pre-commit hook
• package.json (lint-staged) - Which files to lint

Build Output

Production builds generate:

• dist/production/components/ - Individual component HTML files
• dist/production/css/main.css - Compiled, formatted CSS (not minified)
• Output is human-readable for easy debugging

Image Optimization

Place images in src/assets/images/, then run:

pnpm run optimize:images

Generates:

• WebP versions
• Multiple sizes (sm, md, lg)
• Retina versions (@2x)

FTP Deployment

1. Copy .env.example to .env
2. Add your FTP credentials
3. Run pnpm run deploy

Why This Template?

✅ Modern - Uses latest Sass features, no deprecated code ✅ Clean - Minimal setup, no opinionated frameworks ✅ Quality - Automatic linting ensures consistent code ✅ Fast - Live reload, watch mode, only lints changed files ✅ Joomla-Ready - Generates clean HTML for Joomla components

Documentation

For detailed instructions on creating components, SCSS organization, and best practices, see CLAUDE.md.

License

MIT