Nova Devtool Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev laravel/nova-devtool
   npm install --save-dev @laravel/nova-devtool
   

   Add the package to your composer.json under require-dev and install the NPM dependency.

2. First Use Case: Run the nova:devtool setup command to scaffold a Workbench-based Nova environment:

   php vendor/bin/testbench nova:devtool setup
   

   This creates a workbench directory with a minimal Nova setup, including:

   • Nova core files
   • Preconfigured routes
   • Default user setup

3. Serve Nova:

   composer run serve
   

   Access Nova at http://localhost:8000/nova (or your configured port).

Implementation Patterns

Workbench Integration

• Isolated Development: Use the workbench directory to develop Nova components (e.g., cards, fields, toolsets) without affecting your main application. Leverage Orchestra Workbench for:

  • Database isolation (separate .env files).
  • Independent Nova instance for testing.

• Workflow:

  1. Setup: Run nova:devtool setup once per project.
  2. Develop: Modify files in workbench/resources/js/nova or workbench/app/Nova.
  3. Test: Use composer run serve to preview changes in real-time.
  4. Share: Copy components from workbench to your main project.

Dependency Management

• Automated Install: Run nova:devtool install to add common Nova dependencies:

  • Axios (for API calls)
  • Lodash (utility functions)
  • Tailwind CSS (styling)
  • Vue DevTools (debugging) Configured via workbench/package.json.

• Customization: Extend workbench/webpack.mix.js to add custom Webpack configurations (e.g., Babel plugins, aliases).

Component Development

• Nova Resources: Create a new resource in workbench/app/Nova/Resources:

  php artisan nova:resource Post
  

  Use the Workbench environment to test CRUD operations.

• Vue Components: Develop custom Vue components in workbench/resources/js/nova/Components. Example:

  // workbench/resources/js/nova/Components/ExampleField.vue
  Nova.field.extend('ExampleField', {
      // Field logic
  });
  

  Register the component in workbench/resources/js/nova.js:

  Nova.booting((Vue, router) => {
      Vue.component('example-field', require('./Components/ExampleField'));
  });
  

• Tool Integration: Build custom Nova tools in workbench/app/Nova/Tools. Example:

  php artisan nova:tool ExampleTool
  

Gotchas and Tips

Pitfalls

1. Workbench Isolation:

   • Changes in workbench do not reflect in your main project. Manually copy files (e.g., resources/js/nova) to your production app.
   • Fix: Use a script to sync files:

     rsync -avz workbench/resources/js/nova/ ./resources/js/
     

2. NPM Dependency Conflicts:

   • Running nova:devtool install may override existing package.json dependencies.
   • Fix: Review workbench/package.json before merging changes.

3. Vue DevTools Misconfiguration:

   • If Vue DevTools fails to load, ensure @vue/devtools is installed and workbench/webpack.mix.js includes:

     mix.js('resources/js/nova.js', 'public/js')
         .vue()
         .postCss('resources/css/nova.css', 'public/css', []);
     

4. Database Seed Issues:

   • Workbench may not seed default users automatically. Manually run:

     php artisan tinker
     >>> \App\Models\User::factory()->create(['email' => 'nova@laravel.com']);
     

Debugging

• Nova Logs: Check workbench/storage/logs/nova.log for errors during development.

• Browser Console: Use composer run serve --hot for live reloading and inspect Vue components in Chrome DevTools.

• API Debugging: Enable Nova’s API debugging in workbench/config/nova.php:

  'debug' => env('NOVA_DEBUG', true),
  

Tips

1. Environment Variables: Use .env.workbench to override settings (e.g., NOVA_PATH=workbench):

   NOVA_PATH=workbench
   NOVA_PORT=8001
   

2. Custom Commands: Extend the package by publishing its config:

   php artisan vendor:publish --provider="Laravel\NovaDevtool\NovaDevtoolServiceProvider"
   

   Modify config/nova-devtool.php to add custom commands.

3. Testing: Use Pest or PHPUnit with Workbench:

   // tests/Feature/Nova/ExampleTest.php
   public function test_example()
   {
       $response = $this->actingAsUser(factory(User::class)->create())
                         ->get('/nova/resources/posts');
       $response->assertStatus(200);
   }
   

4. Performance: Disable Nova’s asset optimization in workbench/webpack.mix.js for faster development:

   mix.disableSuccessNotifications();
   

5. Extending the Package: Override the nova:devtool commands by publishing and modifying:

   php artisan vendor:publish --tag="nova-devtool-commands"
   

   Edit app/Console/Commands/NovaDevtoolSetupCommand.php.