Weave Code
Theme Installer Laravel Package
orchestra/theme-installer
Composer installer for Orchestra Platform themes that automatically places theme packages in the correct themes directory, streamlining installation and discovery within Orchestra applications.
Theme Installer for Orchestra Platform
Frequently asked questions about Theme Installer
- What does the orchestra/theme-installer Composer plugin actually do?
- It registers a custom Composer package type called orchestra-theme and installs packages of that type into the application's themes/ directory instead of vendor/. That keeps Orchestra Platform themes alongside your application code so they are easier to deploy and discover. It is Composer plumbing only: it handles file placement during install and update, not theme activation or management.
- How do I install orchestra/theme-installer?
- Require it as a Composer dependency in the Orchestra Platform application that consumes the themes, typically with composer require orchestra/theme-installer. Because it is a Composer plugin, Composer 2.2 and later will prompt you to allow it, or require an explicit config.allow-plugins entry, before it will run. Once allowed, any package declared with type orchestra-theme installs into themes/ automatically.
- How do I declare a theme package so it installs into themes/ instead of vendor/?
- In the theme package's composer.json, set "type": "orchestra-theme" and provide a valid package name plus its autoload and asset structure. Composer then routes the package to the registered installer rather than the default location. If the type is misspelled or missing, the package silently falls back to vendor/ and the theme will not be found at runtime.
- Can I change the themes directory path used by the installer?
- The installer targets a configurable themes/ path rather than a hardcoded vendor/ location, which is the core of its value. That configuration lives with the consuming Orchestra application rather than inside the plugin, so verify the resolved path in each environment. Confirm it matches your build scripts, .gitignore rules, file permissions, and asset publishing steps.
- Why does my CI build or Docker deploy fail after adding this plugin?
- Plugin execution is blocked by default in Composer 2.2 and later, so non-interactive installs fail until the plugin is whitelisted in config.allow-plugins. This is a supply-chain governance decision rather than a routine config tweak, and it usually surfaces first in CI or container builds instead of local development. Add the allow-plugins entry deliberately and record who approved it.
- Is orchestra/theme-installer a Laravel package or an Orchestra Platform specific package?
- It is built for Orchestra Platform, which is itself a Laravel-based extension platform. On a vanilla Laravel application without Orchestra Platform it has no real role, because there is no platform theme convention for it to serve. Blade view namespaces, view paths, and Vite asset compilation already cover ordinary Laravel theming without adding a Composer plugin.
- Does orchestra/theme-installer handle theme activation, switching, or settings?
- No. It installs files and does nothing else; activation, switching, per-theme settings, and per-tenant assignment are outside its scope. Treat it strictly as a Composer installer and plan theme management separately. Conflating installation with management is the most likely way to end up expecting capabilities the package does not provide.
- Are theme files removed when I uninstall a theme package?
- Uninstall semantics for this custom installer are not documented, so test them explicitly before relying on them. Verify that removing a theme package cleans up its directory under themes/ rather than leaving orphaned files and compiled assets behind. Add that check to your upgrade runbook and validate it in staging first.
- Why did my theme land in vendor/ instead of the themes/ directory?
- The most common cause is a missing or misspelled "type": "orchestra-theme" in the theme package's composer.json, which makes Composer fall back to the default installer. The other common cause is the plugin not being allowed to run, so its installer never registers. Both failures are silent at install time and typically appear later as a theme not found error in staging or production.
- Is orchestra/theme-installer actively maintained, and what are the adoption risks?
- Orchestra Platform is a small, tightly-scoped ecosystem with very few downstream dependents and single-maintainer exposure, so third-party validation is limited. The package's value depends entirely on tracking Orchestra's theme conventions and Composer's composer-plugin-api version, and a Composer 3 plugin change would need an upstream fix. If you adopt it, decide in advance whether you have the appetite and a named owner to fork and maintain a Composer plugin indefinitely.
Weaver
How can I help you explore Laravel packages today?