Laravel Nova Turbo Laravel Package

Getting Started

• Install the package with Composer and let Laravel discover its service provider (or register it manually if your app does not use package discovery).
• Publish the package config if available, then review the main switches:
  • auto_refresh_in_dev — skip lazy loading in local development.
  • resource_paths — directories scanned for Nova resources.
  • regenerate_on_cache_clear — regenerate automatically on cache:clear.
• Generate the cache:

  php artisan nova:turbo-cache
  

• Look first at the package config and the NovaTurbo facade. These are the main integration points for paths and external resources.
• First use case: a large Nova installation with many resources where every request loads all resources. Install, generate the cache, and compare page response times and loaded resource counts. The release targets 100+ resource installs with up to 59% faster responses and ~95% fewer resources loaded per page.

Implementation Patterns

• Deploy-time cache generation: Add cache generation to your deploy pipeline after config/cache clearing and before serving traffic:

  php artisan cache:clear
  php artisan nova:turbo-cache
  

  If regenerate_on_cache_clear is enabled, cache:clear can regenerate automatically, but an explicit nova:turbo-cache step is clearer and safer in deployments.

• Keep resource_paths complete: Include every directory where Nova resources live, e.g. app resources, domain modules, and package resources. Missing paths cause resources to be skipped from lazy loading.

• Register external resources before caching: For resources from modules or packages, register them through the facade in a service provider, then regenerate the cache:

  use NovaTurbo;
  
  public function boot(): void
  {
      NovaTurbo::resources([
          // Module\Nova\SomeResource::class,
      ]);
  }
  

• Local development: Set auto_refresh_in_dev to true to bypass lazy loading while developing. When testing cache behavior locally, set it to false and rerun php artisan nova:turbo-cache after resource changes.

• Relationship mapping: The package detects and caches relationships such as BelongsTo, HasMany, and MorphTo. You generally do not map these manually, but regenerate the cache after changing relationship methods or morph maps.

• Cache lifecycle commands:

  php artisan nova:turbo-cache         # generate/refresh cache
  php artisan nova:turbo-cache --clear # clear cache
  

  Use --clear when debugging stale or missing resource behavior.

• Production-like testing: Because local mode can disable lazy loading, verify performance and resource visibility in a staging environment with auto_refresh_in_dev disabled.

Gotchas and Tips

• Stale cache is the first suspect: If resources disappear from navigation, pages, or relationship fields, clear and regenerate:

  php artisan nova:turbo-cache --clear
  php artisan nova:turbo-cache
  

• Cache invalidation is not automatic for all app changes: Cache versioning covers package updates, and cache:clear regeneration can be enabled, but adding/removing/moving resources or changing relationships still requires regeneration.

• External resources must be registered before generation: If a module resource is missing, confirm it is registered via NovaTurbo::resources() and that the cache was regenerated afterward.

• Check resource_paths when resources are missing: Custom resource directories, domain modules, and package paths must be explicitly included.

• Be careful with development mode: auto_refresh_in_dev is useful locally but can hide lazy-loading issues. Test in a production-like environment before relying on the performance gains.

• Do not edit generated cache files: Treat the PHP array cache as build output. Clear/regenerate instead of modifying it manually.

• Opcache and deployments: The package uses PHP array files with opcache support. In deployments where opcache does not invalidate changed files automatically, ensure your deploy process resets or reloads PHP-FPM/opcache as usual.

• Morph relationships and morph maps: If you change morph aliases or relationship definitions, regenerate the cache so detected relationships stay accurate.

• Use the commands in CI/deploy, not per request: Cache generation belongs in deployment or explicit maintenance workflows, not in application request handling.