Merq Laravel Nova Theme Responsive Laravel Package

Getting Started

Install the theme via Composer:

composer require ghalwash/merq-laravel-nova-theme-responsive

Publish the theme assets (the exact tag may vary—check the package README):

php artisan vendor:publish --provider="Ghalwash\MerqLaravelNovaThemeResponsive\ThemeServiceProvider"

Register the theme. For Nova 3.x, add the theme name to config/nova.php:

'theme' => 'merq-responsive',

Alternatively, some Nova versions expect registration in app/Providers/NovaServiceProvider.php:

use Laravel\Nova\Nova;

public function boot()
{
    parent::boot();
    Nova::theme('merq-responsive');
}

Where to look first: Open the package’s README.md and src/ThemeServiceProvider.php to confirm the exact registration method for your Nova version. Also inspect config/nova.php for a theme key.

First use case: After installation, open your Nova admin panel in a mobile browser or resize your desktop window. The sidebar should collapse into a hamburger menu, tables should become horizontally scrollable, and forms should stack vertically instead of overflowing.

Implementation Patterns

• Drop-in responsive admin: Use the theme as-is when you need Nova to be usable on phones and tablets without building a custom theme. It’s a low-risk CSS-only change.

• Combine with custom Nova tools: The theme only overrides layout CSS, so existing cards, metrics, and custom tools generally continue to work. Test each tool on small screens after installing.

• Extend via asset publishing: Publish the theme’s assets and override specific rules in your own CSS file. Register your CSS after the theme using Nova::style() in NovaServiceProvider:

  Nova::style('custom-nova-overrides', __DIR__.'/../resources/css/nova-overrides.css');
  

• Use as a base for a custom theme: Fork the package or copy its CSS into your own theme if you need to make substantial design changes. This avoids depending on an unmaintained package while keeping the responsive foundation.

• Development workflow: Install in a local environment, test across breakpoints using browser dev tools (iPhone SE, iPad, etc.), then deploy. Run php artisan nova:publish after installation to ensure assets are copied to public/vendor.

• Version pinning: Since the package was last released in May 2020, pin it to a specific version in composer.json and test upgrades carefully—especially if you later upgrade Nova.

Gotchas andTips

• Nova version compatibility: The package targets Nova 2.x/3.x. It will likely not work with Nova 4+ (which uses Vite and a different theming system). Check your composer.json Nova constraint before installing. For Nova 4, look for actively maintained alternatives or build a custom theme.
• Theme registration differs by Nova version: Nova 2/3 may use config/nova.php ('theme' => '...') while some setups require Nova::theme() in NovaServiceProvider. If the theme doesn’t apply, try the other method.
• Clear caches after installation: Run php artisan nova:publish, php artisan view:clear, and php artisan cache:clear. Browser caching can also hide changes—hard-refresh or use incognito mode.
• Verify asset publication: Check that CSS files exist under public/vendor/merq-responsive/ (or similar). If missing, re-run the publish command with the correct --tag or --provider.
• Debugging missing styles: Open browser dev tools, inspect the <head> for the theme’s <link> tag, and check the Network tab for 404s. Ensure your APP_URL and asset paths are correct.
• Conflicts with other Nova packages: Packages that inject custom CSS/JS may override the theme’s responsive rules. Disable other Nova customizations temporarily to isolate the issue.
• Limited community support: With only 14 stars and no dependents, expect little maintenance. If you rely on it long-term, consider forking the repository and applying your own fixes.
• Extension points: The theme’s CSS is the primary extension point. Publish the assets, copy the CSS into your own theme, and modify breakpoints or component styles directly. There are no PHP configuration options beyond registration.
• Test on real devices: Responsive CSS can behave differently on actual mobile browsers versus emulators, especially with Nova’s Vue components and sticky headers.