- Joined
- Mar 22, 2026
- Messages
- 189
- Reaction score
- 0
Windows 10
Google Chrome 124
Developing add-ons for XenForo 2 can seem daunting at first, but with a solid understanding of the core structure and development workflow, you'll be extending your forum's functionality in no time. This guide will walk you through the essential steps to create your very first XenForo 2 add-on.
Prerequisites
Before diving in, ensure you have:
1. A XenForo 2 installation: Preferably a development environment, not your live forum.
2. Basic PHP knowledge: You'll be working with PHP files.
3. Text editor/IDE: VS Code, Sublime Text, PHPStorm, etc.
4. XenForo Debug Mode enabled: Open
5. Development mode enabled for your user: Go to
Understanding the Core Add-on Structure
Every XenForo 2 add-on resides within the
Inside
Step 1: Create the Add-on Directory Structure
Let's say your vendor ID is
1. Navigate to
2. Create a new directory:
3. Inside
4. Inside
Your path should now look like:
Step 2: Create the
This file defines your add-on's basic information. Create
Step 3: Install the Add-on in Admin CP
Now that you have the basic structure and
1. Go to your Admin CP.
2. Navigate to
3. You should see "Hello XenForo Add-on" listed under "New add-ons to install".
4. Click the "Install" button next to it.
If the installation is successful, the add-on will now appear in your list of installed add-ons.
Step 4: Your First Customization - A Simple Template Modification
Let's make a visible change. We'll add a simple message to the forum list page.
1. In the Admin CP, go to
2. Click "Add template modification".
3. Fill in the details:
* Add-on:
* Template:
* Modification key:
* Description:
* Find:
* Replace:
* Execution order:
* Callback class/method: (Leave empty for simple find/replace)
4. Save the template modification.
Now, refresh your forum's front end. You should see a "Hello from MyCompany HelloXF Add-on!" message at the top of your forum list.
Step 5: Exporting Your Add-on
When you make changes to templates, phrases, options, etc., XenForo stores these in the database. To bundle these changes into your add-on's files for distribution or version control, you need to export the add-on.
1. In the Admin CP, go to
2. Find your "Hello XenForo Add-on" and click "Export" from the controls dropdown.
This action will write all the relevant add-on data (including your template modification) into the
Conclusion
You've successfully created, installed, and made your first visible change with a XenForo 2 add-on! This basic structure and workflow are the foundation for any add-on you'll build. From here, you can explore more advanced features like custom routes, controllers, entities, listeners, and more complex template modifications. Keep experimenting, and refer to the XenForo developer documentation for deeper dives into specific components.
Prerequisites
Before diving in, ensure you have:
1. A XenForo 2 installation: Preferably a development environment, not your live forum.
2. Basic PHP knowledge: You'll be working with PHP files.
3. Text editor/IDE: VS Code, Sublime Text, PHPStorm, etc.
4. XenForo Debug Mode enabled: Open
src/config.php and add define('XF_DEV', true);5. Development mode enabled for your user: Go to
Admin CP -> Users -> Your User -> Edit -> Is a developer.Understanding the Core Add-on Structure
Every XenForo 2 add-on resides within the
src/addons/ directory. The structure follows a Vendor/AddonId pattern:src/addons/YourVendorId/YourAddonId/YourVendorId: This is a unique identifier for you or your company (e.g.,XFA,MyCompany). It should be camel-cased.YourAddonId: This is the unique identifier for your specific add-on (e.g.,MyFirstAddon,ForumStats). It should also be camel-cased.
Inside
src/addons/YourVendorId/YourAddonId/, you'll find several key files and directories:_output/: This directory is crucial. When you export an add-on, XenForo writes all its deployable assets (templates, phrases, options, etc.) here. When developing, XenForo reads from this directory.addon.json: The manifest file for your add-on, defining its metadata.Setup.php(optional): Contains upgrade, install, and uninstall logic for your add-on.Pub/,Admin/(optional): Directories for public and admin-facing controllers, entities, etc._data/(optional): Used for custom data types, like sitemaps or custom BB codes.
Step 1: Create the Add-on Directory Structure
Let's say your vendor ID is
MyCompany and your add-on ID is HelloXF.1. Navigate to
src/addons/.2. Create a new directory:
MyCompany/.3. Inside
MyCompany/, create another directory: HelloXF/.4. Inside
HelloXF/, create an empty directory named _output/.Your path should now look like:
src/addons/MyCompany/HelloXF/_output/Step 2: Create the
addon.json FileThis file defines your add-on's basic information. Create
src/addons/MyCompany/HelloXF/addon.json with the following content:
JSON:
{
"legacy_addon_id": "",
"title": "Hello XenForo Add-on",
"description": "A simple add-on to demonstrate basic XenForo 2 development.",
"version_id": 1000010,
"version_string": "1.0.0 Alpha",
"developer": "Your Name",
"developer_url": "https://yourwebsite.com",
"run_routes": [],
"css_files": [],
"js_files": [],
"eula_url": "",
"extra_urls": [],
"icon": "fa-hand-peace",
"require": {
"XF": [2020000, "XenForo 2.2.0+"]
},
"optional_require": [],
"json_encode_options": 0
}
title: The human-readable name of your add-on.description: A brief explanation.version_id: An integer representing the version (e.g., 1000010 for 1.0.0 Alpha). This must always increase with each new version.version_string: The human-readable version (e.g., "1.0.0 Alpha").require: Defines dependencies on other add-ons or XenForo itself (e.g.,XFfor XenForo core).[2020000, "XenForo 2.2.0+"]means it requires XenForo 2.2.0 or higher.
Step 3: Install the Add-on in Admin CP
Now that you have the basic structure and
addon.json, XenForo can detect your add-on.1. Go to your Admin CP.
2. Navigate to
Add-ons.3. You should see "Hello XenForo Add-on" listed under "New add-ons to install".
4. Click the "Install" button next to it.
If the installation is successful, the add-on will now appear in your list of installed add-ons.
Step 4: Your First Customization - A Simple Template Modification
Let's make a visible change. We'll add a simple message to the forum list page.
1. In the Admin CP, go to
Development -> Template modifications.2. Click "Add template modification".
3. Fill in the details:
* Add-on:
Hello XenForo Add-on* Template:
forum_list (This is the template for the main forum list page)* Modification key:
mycompany_helloxf_forum_list_message (A unique identifier for this modification)* Description:
Adds a welcome message to forum list* Find:
<xf:token /> (This is a common, stable point to insert content after)* Replace:
Code:
html
$0
<div class="blockMessage blockMessage--important">
Hello from MyCompany HelloXF Add-on!
</div>
10 (Default is fine)* Callback class/method: (Leave empty for simple find/replace)
4. Save the template modification.
Now, refresh your forum's front end. You should see a "Hello from MyCompany HelloXF Add-on!" message at the top of your forum list.
Step 5: Exporting Your Add-on
When you make changes to templates, phrases, options, etc., XenForo stores these in the database. To bundle these changes into your add-on's files for distribution or version control, you need to export the add-on.
1. In the Admin CP, go to
Add-ons.2. Find your "Hello XenForo Add-on" and click "Export" from the controls dropdown.
This action will write all the relevant add-on data (including your template modification) into the
_output/ directory within your src/addons/MyCompany/HelloXF/ folder. You'll see files like _output/template_modifications.xml.Conclusion
You've successfully created, installed, and made your first visible change with a XenForo 2 add-on! This basic structure and workflow are the foundation for any add-on you'll build. From here, you can explore more advanced features like custom routes, controllers, entities, listeners, and more complex template modifications. Keep experimenting, and refer to the XenForo developer documentation for deeper dives into specific components.
