Nova Devtool Laravel Package

Getting Started

Minimal Setup for Daily Use

1. Install the package in your Laravel project (or Nova component):

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

2. Enable Vue DevTools (critical for debugging):

   php vendor/bin/testbench nova:devtool enable-vue-devtool
   

3. Run Nova locally with auto-authentication (via testbench.yaml):

   composer run serve
   

   (Add user: nova@laravel.com to testbench.yaml under workbench to auto-login.)

First Use Case: Debugging a Custom Nova Field

• Problem: A custom field isn’t rendering as expected.
• Solution:
  1. Enable Vue DevTools (step 2 above).
  2. Inspect the field in Chrome DevTools (F12).
  3. Use the Vue DevTools panel to trace component lifecycle and props.

Implementation Patterns

1. Workbench Integration (Isolated Development)

• Pattern: Use testbench to spin up a disposable Nova environment for each feature branch.

  php vendor/bin/testbench nova:devtool setup
  

• Workflow:
  1. Commit changes to a feature branch.
  2. Run testbench nova:devtool setup to create a fresh workbench directory.
  3. Test changes in isolation without polluting your main project.
• Integration Tip: Add a Makefile alias for convenience:

  nova-test:
      testbench nova:devtool setup && composer run serve
  

2. Dependency Management

• Pattern: Standardize frontend dependencies across Nova projects.

  php vendor/bin/testbench nova:devtool install
  

  (Installs Axios, Lodash, Tailwind CSS, and Vue.)
• Workflow:
  • Use this command once per project to avoid manual package.json edits.
  • Re-run after major Nova updates to sync dependencies.

3. Vue DevTools Toggle

• Pattern: Enable DevTools only during development.

  # Enable (for debugging)
  php vendor/bin/testbench nova:devtool enable-vue-devtool
  
  # Disable (for production builds)
  php vendor/bin/testbench nova:devtool disable-vue-devtool
  

• Integration Tip: Add these to your package.json scripts:

  "scripts": {
    "dev": "nova enable-vue-devtool && mix",
    "prod": "nova disable-vue-devtool && mix --production"
  }
  

4. Webpack Mix Integration

• Pattern: Replace nova.mix.js with the devtool’s mixin (for Nova 4+):

  // webpack.mix.js
  let mix = require('laravel-mix');
  mix.extend('nova', new require('laravel-nova-devtool'));
  mix.setPublicPath('dist').nova();
  

• Why: Avoids publishing nova.mix.js per component and keeps builds consistent.

5. TypeScript Support

• Pattern: Generate a tsconfig.json for TypeScript projects:

  php vendor/bin/testbench nova:devtool tsconfig
  

• Workflow:
  • Run this once when adding TypeScript to a Nova component.
  • Extend the generated config for project-specific rules.

Gotchas and Tips

Pitfalls

1. Webpack 5 Compatibility:

   • Issue: Fails to compile with webpack 5.10.6 (fixed in v1.9.1).
   • Fix: Update webpack-cli and laravel-mix:

     npm update webpack-cli laravel-mix
     

   • Tip: Pin versions in package.json if using older Nova versions:

     "devDependencies": {
       "webpack-cli": "^4.10.0",
       "laravel-mix": "^6.0.9"
     }
     

2. Vue DevTools Not Showing:

   • Cause: DevTools are disabled or Vue isn’t properly loaded.
   • Debug:
     • Verify enable-vue-devtool ran without errors.
     • Check browser console for Vue-related warnings.
     • Ensure mix.js includes the devtool plugin (see Webpack Mix Integration).

3. Workbench Authentication Failures:

   • Cause: testbench.yaml misconfiguration or missing user.
   • Fix:
     • Ensure user: nova@laravel.com is set (or use your Nova admin email).
     • Run php artisan nova:auth if the user isn’t registered.

4. NPM Dependency Conflicts:

   • Cause: Nova’s package.json and devtool’s dependencies clash.
   • Fix: Use npm install --force or resolve conflicts manually:

     npm install --save-dev @laravel/nova-devtool --force
     

Debugging Tips

• Vue Component Issues:

  • Use Vue DevTools to inspect props/data in real-time.
  • Check the "Components" tab to verify your custom field/tool is registered.

• Build Errors:

  • Run mix --verbose to see detailed Webpack logs.
  • Clear caches:

    php artisan cache:clear
    npm run dev
    

• Nova Service Provider:

  • If Nova isn’t loading, verify NovaServiceProvider is registered in config/app.php:

    'providers' => [
        // ...
        Laravel\Nova\NovaServiceProvider::class,
    ],
    

Extension Points

1. Custom Commands:

   • Extend the devtool by creating a custom command in your project:

     use Laravel\NovaDevtool\Console\NovaDevtoolCommand;
     
     class CustomNovaDevTool extends NovaDevtoolCommand {
         protected $signature = 'nova:custom-task';
         protected $description = 'Run a custom Nova devtool task';
     
         public function handle() {
             // Add logic here
         }
     }
     

2. Webpack Mix Extensions:

   • Override devtool’s mixin behavior by publishing its config:

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

   • Modify config/nova-devtool.php to adjust build settings.

3. Workbench Automation:

   • Customize the testbench.yaml template by publishing devtool assets:

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

   • Edit resources/views/vendor/nova-devtool/testbench.yaml to add pre-configured tools (e.g., auto-installed Nova packages).

Pro Tips

• Laravel 13+ Support:

  • Use v1.9.0+ for Laravel 13 compatibility. Older versions may require manual adjustments to config/nova.php.

• CI/CD Integration:

  • Add devtool commands to your CI pipeline for automated testing:

    # .github/workflows/test.yml
    - run: php vendor/bin/testbench nova:devtool enable-vue-devtool
    - run: npm ci && npm run dev
    

• Nova Upgrades:

  • When upgrading Nova, run:

    php vendor/bin/testbench nova:devtool install --update
    

  • Check the changelog for breaking changes.

• Performance:

  • Disable Vue DevTools in production (disable-vue-devtool) to reduce bundle size.
  • Use mix.nova() with --production flag for optimized builds.