The theme doesn’t appear in the admin panel
The package failed validation, or it isn’t where Aikeedo looks.The directory is
extra/extensions/{vendor}/{name} and matches the name field.type is aikeedo-theme.require includes heyaikeedo/composer.composer.json is valid JSON.DEBUG=true to see the validation error instead of a silently skipped package.
Styles or scripts don’t load
In development
In development
npm run dev must be running, and THEME_ASSETS_SERVER in the Aikeedo .env must match its port. The starter serves on 5174.In production
In production
extra.public must include assets and .vite, and the theme must have been installed or reinstalled after the build so those files were copied to public/e/{vendor}/{name}/.Assets point at localhost
Assets point at localhost
THEME_ASSETS_SERVER is still set. Remove it outside development.Template changes do nothing
- With
CACHE=trueandDEBUG=false, templates are cached. Clear the cache from Status → Clear cache. - In development, the dev server copies
static/intoBUILD_DIR. IfBUILD_DIRis wrong, the installed theme never changes. - Check you’re editing the repository, not the installed copy, which is overwritten by the next build.
Twig errors about undefined variables
Debug mode enables strict variables:user and workspace exist only for signed-in visitors, plans only on the landing page, and locale only when your theme has a catalog for the resolved language.
The build deleted my files
The production build emptiesBUILD_DIR before writing. Point it at the theme’s own directory, extra/extensions/{vendor}/{name}, and nothing else.
A custom page returns 404
The theme is published, since a theme’s entry class only boots while it’s active.
The package was installed with
composer require, so the class autoloads.AttributeMapper::addPath() covers the handler’s directory.The route cache was cleared, or
CACHE=false.Strings aren’t translated
The string uses
d__('theme', …) or dp__('theme', …), not a plain __().A
theme.po exists for that language, with X-Domain: theme.The language is enabled in Settings → Languages.
Extraction was re-run after the last copy change.
The favicon 404s
{{ 'favicon.ico'|asset_url }} resolves to your theme’s assets, so either ship that file or fall back to the brand setting:
Dark mode flashes the wrong colors
The mode must be applied in the<head>, before the body paints. See Dark mode and colors.
The site shows the old theme after publishing
Clear the cache, and check that the theme’s package name matches its directory. Preview separately at/preview?theme=vendor/name, which sets a short-lived cookie rather than switching the live site.