Use the Localhost Setup Quickstart as the setup reference. This chapter connects that environment to the plugin used in the rest of the guide.
Prepare your environment
The current quickstart lists Homebrew, PHP 8.3 or later, Docker, Node 20.x, Composer 2 and Yarn.
You need access to vanillaforums/vanilla-local and your organization's Code Deploy repository. Keep both repositories inside the directory shared with Docker.
The documented Vanilla location is ~/vnla/vanilla. In this example, the partner repository is a sibling named my-custom-code.
~/vnla/
vanilla/
my-custom-code/
plugins/
themes/
Clone the supplied repositories into those locations. Use the repository URLs supplied during onboarding. The partner source is vanilla-local
Start Vanilla
Run these commands from ~/vnla/vanilla, following the quickstart's installation prerequisites:
composer install
~/vnla/vanilla/cli/bin/vnla install
vnla docker up
vnla spawn-site
Follow the site-creation prompts. Open the local site URL supplied by that process and sign in as its administrator.
If frontend assets are missing, the quickstart documents:
composer install
yarn install
vnla build
Use vnla docker down when you want to stop the containers.
Checkpoint: the local community and Dashboard both load before you add custom code.
Create the addon
Inside the partner repository, create plugins/my-custom-catalog.
Start with these files:
plugins/my-custom-catalog/
addon.json
Addon/
CatalogContainerRules.php
src/scripts/entries/
layouts.tsx
Create addon.json:
{
"key": "my-custom-catalog",
"name": "My Custom Catalog",
"description": "A catalog integration used in this guide.",
"version": "1.0.0",
"type": "addon"
}
Keep the addon key and directory name consistent. Add your organization's author and license metadata before distribution. Declare any actual addon dependencies in the manifest; do not copy an unrelated minimum version from another example.
Add the container rules
Create Addon/CatalogContainerRules.php:
<?php
namespace MyCustom\Catalog\Addon;
use Garden\Container\ContainerConfigurationInterface;
use Vanilla\AddonContainerRules;
class CatalogContainerRules extends AddonContainerRules
{
public function configureContainer(ContainerConfigurationInterface $container): void
{
// Widget and fragment registrations are added in later chapters.
}
}
The namespace ends in Addon. In the inspected implementation, Vanilla discovers special addon classes in that namespace and calls their container rules.
PHP class discovery and frontend entry discovery are separate. A JavaScript entry does not register a PHP service or widget.
Connect the addon to local Vanilla
The partner repository holds your code. Local Vanilla must also be able to discover it.
With the directory layout shown above, create a relative symlink from Vanilla's plugin directory:
cd ~/vnla/vanilla/plugins
ln -s ../../my-custom-code/plugins/my-custom-catalog my-custom-catalog
Use a new destination name. If that path already exists, inspect the existing setup before changing it.
Both the link and its target must resolve inside the directories shared with Docker. This relative-link pattern follows the theming quickstart; verify the path inside your supplied Docker environment.
Return to the Vanilla root and rebuild discovery and assets:
cd ~/vnla/vanilla
vnla clear-caches
vnla build
clear-caches rebuilds the addon cache in the inspected CLI. Run composer install and yarn install when your changes introduce dependency changes.
Enable the plugin
Open the local Dashboard's addon management page and enable My Custom Catalog.
The inspected checkout serves addon management at /settings/addons. Use the addon page provided by your LTS release if its Dashboard navigation differs.
If the addon is absent, check the symlink target, manifest, addon cache and PHP errors first. A frontend rebuild alone does not repair PHP discovery.
Confirm the frontend entry loads
Add this temporary development message to src/scripts/entries/layouts.tsx:
console.info("My Custom Catalog: layouts entry loaded");
Rebuild the frontend. Open a community page that uses the Layouts section and check the browser console.
The build discovers section entries under src/scripts/entries. The enabled-addon list controls whether the plugin's entry executes. A layouts.tsx entry runs in the Layouts section; it is not a global entry for every page.
Enabling the addon does not build its entry. Vanilla can only run entries that the frontend build has already produced. vnla clear-caches refreshes PHP discovery; it does not rebuild frontend entries.
For ongoing frontend work, the inspected CLI supports:
vnla build --dev
Restart the development build after adding a new entry or changing addon discovery. If the message does not appear, rebuild or restart the development build, then reload the page.
Remove the temporary console message once you have confirmed loading. You can restore it later to check that the entry still runs.
Checkpoint: the plugin is enabled and its Layouts entry executes. Do not continue until the message appears. The widget in Create a configurable widget depends on this entry. Continue with Create an API endpoint.