Nova Packages Tool Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require nova-kit/nova-packages-tool --dev
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="NovaKit\NovaPackagesTool\NovaPackagesToolServiceProvider" --tag="config"
   

2. Basic Usage Run the tool to scaffold a new Nova package:

   php artisan nova:package create MyPackage
   

   This generates:

   • A packages/ directory with your package structure.
   • A composer.json for your package.
   • Basic files (e.g., package.json, resources/js, src/).

3. First Integration Register your package in config/nova.php under the packages key:

   'packages' => [
       NovaKit\NovaPackagesTool\NovaPackagesTool::class,
       Nova\NovaServiceProvider::class,
       // Add your package's service provider
       MyVendor\MyPackage\MyPackageServiceProvider::class,
   ],
   

Implementation Patterns

Common Workflows

1. Scaffolding a Package Use the nova:package command to generate a new package with:

   php artisan nova:package:create MyPackage --with-resources --with-tests
   

   • --with-resources: Includes Vue/React/Inertia resources.
   • --with-tests: Adds PHPUnit/Pest test boilerplate.

2. Adding a Nova Resource Generate a Nova resource inside your package:

   php artisan nova:package:resource Post --package=MyPackage
   

   This creates:

   • src/Resources/Post.php
   • resources/js/resources/Post.js
   • Migration and model stubs.

3. Tooling for Development

   • Live Reloading: Use nova:package watch to auto-reload assets during development.
   • Testing: Run php artisan nova:package test to execute package-specific tests.

4. Integration with Nova Extend Nova’s functionality by:

   • Publishing assets via Nova::serving() in your package’s service provider.
   • Overriding Nova’s default behavior using Nova::extend() or middleware.

Key Integration Points

• Service Provider: Register routes, assets, and tool extensions in MyPackageServiceProvider.
• Asset Compilation: Configure webpack.mix.js for your package’s frontend assets.
• Nova Extensions: Use Nova::tools() to add custom tools or modify existing ones.
• Publishing Config: Use publishes in your service provider to expose package settings.

Gotchas and Tips

Common Pitfalls

1. Asset Loading Conflicts

   • Ensure your package’s assets are properly namespaced in webpack.mix.js:

     mix.js('resources/js/package.js', 'dist/js')
         .vue()
         .postCss('resources/css/package.css', 'dist/css', []);
     

   • Use unique asset paths (e.g., dist/js/my-package.js) to avoid collisions.

2. Namespace Collisions

   • Prefix all classes, views, and assets with your package name (e.g., MyVendor\MyPackage\Resources\Post).
   • Avoid using Nova as a namespace prefix for your package classes.

3. Testing Quirks

   • Mock Nova’s container in tests:

     $this->app->instance(Nova::class, new class extends Nova {
         public function tool($name) { return null; }
     });
     

   • Use --package=MyPackage flag for package-specific test commands.

4. Configuration Overrides

   • If extending Nova’s config, use mergeConfigFrom in your service provider:

     $this->mergeConfigFrom(__DIR__.'/../config/my-package.php', 'nova.my-package');
     

Debugging Tips

• Asset Debugging: Check compiled assets with:

  php artisan nova:package assets:compile --package=MyPackage
  

• Route Debugging: Dump routes in your package’s service provider:

  Route::get('/nova/vendor/my-package/debug', function () {
      return response()->json(Route::getRoutes()->getByName('nova'));
  });
  

• Vue/React Debugging: Use nova:package watch and check browser console for errors.

Extension Points

1. Custom Commands Extend the tool by publishing custom commands:

   php artisan nova:package:command create MyCommand --package=MyPackage
   

2. Package Templates Override default templates by publishing them:

   $this->publishes([
       __DIR__.'/templates/' => resource_path('nova-packages-tool/templates'),
   ]);
   

3. Nova Tool Integration Create a custom Nova tool that interacts with your package:

   Nova::tools([MyPackageTool::class]);
   

   class MyPackageTool extends Tool
   {
       public function boot()
       {
           Nova::serving([$this, 'serveAssets']);
       }
   }