Building Themes for Aikeedo v3.x

Creating a custom theme for Aikeedo allows you to personalize the look and feel of your platform. This guide covers the modern approach using the Aikeedo Theme Starter Kit - a comprehensive development environment that streamlines theme creation.

This guide is for Aikeedo v3.x. We strongly recommend using the themes-starter kit for new theme development as it provides a modern build system and best practices.

Modern Theme Development with Starter Kit

The Aikeedo Theme Starter Kit provides a modern development environment with:

Vite.js for fast asset building and hot module replacement
Alpine.js for lightweight JavaScript interactivity
Tailwind CSS for utility-first styling
Twig for PHP templating
Gettext for internationalization
PHP Composer package structure

Theme Development Options

You have several options for theme development:

Build a new theme from scratch using the themes-starter kit
Customize the default theme for simple modifications
Customize marketplace themes for advanced modifications
Rebuild themes from source for complex customizations

Choosing the Right Approach

Simple Changes
Complex Changes
New Theme

Use: Quick customization (Option 2 or 3)Best for:

Changing colors, fonts, or basic styling
Modifying text content
Simple layout adjustments
Adding basic HTML elements

Limitations:

Manual asset copying required
No hot reloading
Limited to existing template structure

Option 1: Building a New Theme

Clone the Starter Repository

Start by cloning the themes-starter repository:

git clone https://github.com/heyaikeedo/themes-starter.git my-theme
cd my-theme

Configure Your Theme Package

Edit /static/composer.json with your theme details:

{
  "name": "your-vendor/your-theme-name",
  "description": "Your theme description",
  "version": "1.0.0",
  "type": "aikeedo-theme",
  "homepage": "https://your-site.com",
  "license": "AIKEEDO",
  "authors": [
    {
      "name": "Your Name",
      "email": "your.email@example.com",
      "homepage": "https://your-site.com",
      "role": "Developer"
    }
  ],
  "support": {
    "email": "support@your-site.com",
    "docs": "https://docs.your-site.com/"
  },
  "require": {
    "heyaikeedo/composer": "^1.0.0"
  },
  "extra": {
    "entry-class": "YourVendor\\ThemeName\\Theme",
    "title": "Your Theme Title",
    "description": "Your theme description",
    "logo": "https://your-site.com/logo.png",
    "icon": "https://your-site.com/icon.png",
    "status": "active",
    "public": [
      "assets",
      ".vite"
    ]
  },
  "autoload": {
    "psr-4": {
      "YourVendor\\ThemeName\\": "src/"
    }
  }
}

Important: Replace YourVendor\\ThemeName with your actual namespace. The namespace in autoload.psr-4 must match your entry-class namespace.

Set Up Environment

Create your local environment file:

cp .env .env.local

Configure .env.local with your paths:

# Windows path example:
BUILD_DIR=C:/xampp/htdocs/aikeedo/extra/extensions/your-vendor/your-theme-name

# Linux/Mac path example:
BUILD_DIR=/var/www/aikeedo/extra/extensions/your-vendor/your-theme-name

# Aikeedo server URL (required for development)
AIKEEDO_SERVER=http://localhost:8000

Critical: The final path segments (your-vendor/your-theme-name) MUST match your composer.json package name!

Install Dependencies

Install npm packages:

npm install

Verify installation:

# Should list alpinejs and other dependencies
npm list

Start Development Server

npm run dev

This will:

Start Vite dev server on port 5174
Watch for file changes
Copy static files to BUILD_DIR
Extract translations automatically

Register Theme with Aikeedo

In your Aikeedo installation directory:

# Add your theme as a requirement
composer require your-vendor/your-theme-name

Configure Aikeedo

Add or update these settings in your Aikeedo’s .env file:

# Required for development
THEME_ASSETS_SERVER=http://localhost:5174/

# Set environment to development
ENVIRONMENT=dev

# Enable debug mode for development
DEBUG=1

# Disable caching for development
CACHE=0

Verify Installation

# Your theme should be here
ls /path/to/aikeedo/public/content/plugins/your-vendor/your-theme-name

Activate Your Theme

Log into Admin Panel

Access your Aikeedo admin panel

Navigate to Themes

Go to the Themes section in the admin panel

Find Your Theme

Locate your theme in the list of available themes

Activate Theme

Click “Publish” to activate your theme

Your theme is now active and visible to users!

Option 2: Customizing the Default Theme

For simple modifications to the default theme, you can make direct changes without rebuilding from source.

This approach is suitable for basic customizations. For complex changes, consider rebuilding from source (Option 4).

Quick Customization Guide

For detailed step-by-step instructions on customizing the default theme, including:

Duplicating the default theme
Updating composer configuration
Copying public assets
Activating your custom theme
Making changes and managing cache

Landing Page Customization

Complete step-by-step guide for customizing the default theme with detailed instructions for duplicating, configuring, and modifying themes.

Option 3: Customizing Marketplace Themes

For themes purchased from the Aikeedo marketplace, follow the same process as customizing the default theme, but start with your purchased theme instead.

Always work on a copy of the theme to prevent losing changes during updates.

Quick Customization Guide

Follow the same steps as customizing the default theme, but replace the default theme with your purchased theme.

Landing Page Customization

Complete step-by-step guide for customizing themes with detailed instructions for duplicating, configuring, and modifying themes.

Option 4: Rebuilding Themes from Source

For complex customizations, rebuild the theme from source using the same process as building a new theme.

Rebuilding the Default Theme

Clone the Default Theme Repository

git clone https://github.com/heyaikeedo/themes-default.git my-custom-theme
cd my-custom-theme

Configure Your Theme

Follow the same configuration steps as building a new theme, but update the package name to avoid conflicts:

{
  "name": "yourorganization/custom-default",
  "description": "Customized default theme",
  "version": "1.0.0",
  "type": "aikeedo-theme",
  "require": {
    "heyaikeedo/composer": "^1.0.0"
  },
  "extra": {
    "title": "Custom Default Theme",
    "status": "active"
  }
}

Set Up Development Environment

Follow the same environment setup as building a new theme, but point to your custom theme directory.

Make Your Customizations

Edit the source files in the src/ and static/ directories as needed.

Build and Deploy

npm run build
npm run pack

Project Structure

The themes-starter kit provides a well-organized structure:

theme-starter/
├── src/                    # Frontend source
│   ├── js/               # JavaScript files
│   │   ├── components/  # Custom elements
│   │   └── index.js    # Main JS entry
│   └── css/             # CSS files
│       ├── base.css    # Base styles
│       └── index.css   # Main CSS entry
│
├── static/                # PHP package structure
│   ├── composer.json     # Package definition
│   ├── templates/       # Twig template files
│   ├── sections/       # Reusable template sections
│   ├── snippets/      # Template partials
│   ├── layouts/       # Base layouts
│   ├── locale/        # Translation files (.po)
│   └── src/          # PHP source files
│
└── scripts/              # Build and utility scripts
    ├── pack.mjs        # Theme packaging
    ├── release.mjs    # Release creation
    └── locale-extract.mjs # Translation extraction

Development Features

Hot Module Replacement

The starter kit provides instant development feedback:

Instant CSS updates via Tailwind CSS
Alpine.js component reloading for JavaScript changes
Full page reload for Twig template changes
Automatic static file copying to your Aikeedo installation

Custom Elements

The starter kit includes pre-built custom elements:

<!-- Dark/Light Mode Switcher -->
<mode-switcher>
  <button class="text-2xl">
    <i class="ti ti-moon-stars dark:hidden"></i>
    <i class="hidden ti ti-sun-filled dark:block"></i>
  </button>
</mode-switcher>

<!-- Avatar Component -->
<x-avatar title="User Name" src="/path/to/avatar.jpg" length="2"></x-avatar>

Twig Templates

Use the modern Twig templating system:

{% extends "@theme/layouts/theme.twig" %}

{% block template %}
  <div class="container">
    {% include "@theme/sections/header.twig" %}
    {{ content }}
  </div>
{% endblock %}

Internationalization

The starter kit includes automatic translation extraction:

Automatic string extraction to PO files
Multiple language support with Gettext
Translation file watching during development
Uses PHP’s Gettext for translations

Available Commands

Command	Purpose
`npm run dev`	Start Vite development server
`npm run build`	Build production assets
`npm run serve`	Preview production build
`npm run locale`	Extract translatable strings
`npm run pack`	Create installable theme package
`npm run release`	Create distribution package

Theme Objects

Aikeedo provides several objects for use in Twig templates:

theme: Theme metadata and configuration
option: Site settings and options
user: Current user information
environment: Environment variables and settings

Refer to the Theme Objects documentation for complete details.

Best Practices

Use the Starter Kit: Always start with the themes-starter for new themes
Responsive Design: Ensure your theme looks good on all device sizes using Tailwind CSS
Accessibility: Follow WCAG guidelines to make your theme usable for everyone
Performance:
- Leverage Vite’s built-in optimization
- Use Tailwind’s utility classes for efficient CSS
- Implement lazy loading for images
- Take advantage of Alpine.js’s lightweight nature
Version Control: Use Git to track changes and maintain version history
Documentation: Document your theme’s features and customization options
Testing: Test across different browsers and devices

Common Setup Issues

Assets Not Loading

If theme assets aren’t loading:

Verify THEME_ASSETS_SERVER in Aikeedo’s .env
Ensure Vite server is running on port 5174
Check proxy settings in vite.config.mjs

Template Changes Not Reflecting

Clear Aikeedo’s cache
Check BUILD_DIR path is correct
Verify file permissions

Build Problems

Verify all paths in .env.local
Check write permissions on BUILD_DIR
Review Vite build output for errors

Landing Page Customization - Basic customization guide for the default theme
Theme Objects - Available objects for templates
Localization - Add multilingual support
Themes Starter Repository - Modern development starter kit
Default Theme Repository - Source code for the default theme

Need Help?

If you need assistance with Aikeedo:

Professional Support

Get expert help from our team with a paid support subscription

Troubleshooting Guide

Check common issues and solutions

Happy theme development! 🎨

Development

Plugins & Themes

​Building Themes for Aikeedo v3.x

​Modern Theme Development with Starter Kit

​Theme Development Options

​Choosing the Right Approach

​Option 1: Building a New Theme

​Clone the Starter Repository

​Configure Your Theme Package

​Set Up Environment

​Install Dependencies

​Start Development Server

​Register Theme with Aikeedo

​Configure Aikeedo

​Verify Installation

​Activate Your Theme

​Option 2: Customizing the Default Theme

​Quick Customization Guide

Landing Page Customization

​Option 3: Customizing Marketplace Themes

​Quick Customization Guide

Landing Page Customization

​Option 4: Rebuilding Themes from Source

​Rebuilding the Default Theme

​Project Structure

​Development Features

​Hot Module Replacement

​Custom Elements

​Twig Templates

​Internationalization

​Available Commands

​Theme Objects

​Best Practices

​Common Setup Issues

​Assets Not Loading

​Template Changes Not Reflecting

​Build Problems

​Related Guides

​Need Help?

Professional Support

Troubleshooting Guide

Building Themes for Aikeedo v3.x

Modern Theme Development with Starter Kit

Theme Development Options

Choosing the Right Approach

Option 1: Building a New Theme

Clone the Starter Repository

Configure Your Theme Package

Set Up Environment

Install Dependencies

Start Development Server

Register Theme with Aikeedo

Configure Aikeedo

Verify Installation

Activate Your Theme

Option 2: Customizing the Default Theme

Quick Customization Guide

Option 3: Customizing Marketplace Themes

Quick Customization Guide

Option 4: Rebuilding Themes from Source

Rebuilding the Default Theme

Project Structure

Development Features

Hot Module Replacement

Custom Elements

Twig Templates

Internationalization

Available Commands

Theme Objects

Best Practices

Common Setup Issues

Assets Not Loading

Template Changes Not Reflecting

Build Problems

Related Guides

Need Help?