Nova State Select Laravel Package

Getting Started

v1.0.0 is the initial release of this Nova field, so start by confirming exactly what it ships and which Nova version it targets.

1. Inspect the package before installing

   • Check composer.json for the laravel/nova constraint and PHP version.
   • Check the README for install commands, screenshots, and supported Nova versions.
   • Look for a service provider, config file, dist/ assets, and Vue components.

2. Install and register

   composer require vendor/nova-field
   

   If the package provides publishable assets or config:

   php artisan vendor:publish --provider="Vendor\NovaField\FieldServiceProvider"
   

   Nova custom fields usually register their JS/CSS through Nova::serving() in the package service provider. If the package does not do this automatically, register it in app/Providers/NovaServiceProvider.php:

   use Laravel\Nova\Events\ServingNova;
   use Laravel\Nova\Nova;
   
   public function boot(): void
   {
       Nova::serving(function (ServingNova $event) {
           Nova::script('nova-field', __DIR__.'/../vendor/vendor/nova-field/dist/js/field.js');
           Nova::style('nova-field', __DIR__.'/../vendor/vendor/nova-field/dist/css/field.css');
       });
   }
   

3. Add it to a resource

   use Vendor\NovaField\Field;
   
   public function fields(NovaRequest $request): array
   {
       return [
           ID::make()->sortable(),
           Field::make('Label', 'column_name')
               ->rules('required'),
       ];
   }
   

4. Where to look first

   • src/ for the field class: look for make(), resolve(), fill(), withMeta(), and jsonSerialize().
   • resources/js/components/ for FormField.vue, DetailField.vue, and IndexField.vue.
   • dist/ to confirm compiled assets exist and are current.
   • The package service provider to confirm asset registration.

First use case: add the field to one Nova resource, open the create/edit form, save a value, and verify it renders on the detail and index screens. That exercise will quickly reveal whether the package includes all three Vue components or only form support.

Implementation Patterns

Basic resource usage

Field::make('Status', 'status')
    ->rules('required', 'string', 'max:255')
    ->help('Shown on the resource form.');

Form-only or detail-only display Use Nova’s standard visibility methods if the field supports them:

Field::make('Internal Note', 'internal_note')
    ->onlyOnForms();

Field::make('Computed Label', 'computed_label')
    ->exceptOnForms();

Passing configuration to Vue Most Nova fields expose metadata through withMeta():

Field::make('Color', 'color')
    ->withMeta([
        'options' => [
            'red' => '#ff0000',
            'blue' => '#0000ff',
        ],
    ]);

In the Vue component, read it from this.field.options.

Transforming values Use resolveUsing() for display transformations and fillUsing() when the stored value needs normalization:

Field::make('Slug', 'slug')
    ->resolveUsing(fn ($value) => strtoupper($value))
    ->fillUsing(function ($request, $model, $attribute) {
        $model->{$attribute} = strtolower($request->input($attribute));
    });

Dependent fields If the field supports Nova’s dependsOn():

Field::make('City', 'city')
    ->dependsOn(['country'], function (Field $field, NovaRequest $request) {
        $field->withMeta([
            'country' => $request->input('country'),
        ]);
    });

Otherwise, fall back to a custom Vue component that watches the dependent field through Nova’s field API.

Validation Prefer Nova field rules over custom Vue validation so server-side validation remains authoritative:

Field::make('Amount', 'amount')
    ->rules('required', 'numeric', 'min:0')
    ->creationRules('unique:orders,amount')
    ->updateRules('sometimes');

Resource pattern Keep the field declaration in the resource’s fields() method and avoid embedding business logic in Vue. If the field needs options from the database, compute them in the resource or a small service and pass them via withMeta().

Index and detail screens Check whether the package includes IndexField.vue and DetailField.vue. If not, the field may show a raw value or nothing outside forms. For day-to-day use, decide early whether the field is form-only or needs full CRUD display support.

Gotchas and Tips

• Nova version compatibility is the first risk. Nova is commercial and version constraints are strict. Confirm the package supports your installed Nova major version before relying on it. A v1.0.0 field may target only one Nova release line.
• Check whether dist/ is committed. Many Nova field packages ship compiled assets. If dist/ is missing, run the package’s build steps:

  cd vendor/vendor/nova-field
  npm install
  npm run prod
  

  If you cannot build inside vendor/, the package is not ready for normal Composer-only installation.
• Asset registration is easy to miss. If the field renders as an empty input or plain text, inspect the browser console and Network tab. Missing Nova::script() registration or a stale compiled file is the usual cause.
• Clear caches after changes.

  php artisan optimize:clear
  php artisan view:clear
  

  If Nova caches assets in your setup, republish or rebuild them according to your Nova version.
• Do not duplicate asset registrations. Registering the same script/style twice can cause Vue component conflicts or duplicate event handlers.
• Field label vs attribute matters. Field::make('Display Label', 'database_column') is the expected pattern. If the field uses a computed value, make sure both resolveUsing() and fillUsing() are handled; otherwise the field may display correctly but fail to save.
• withMeta() values must be serializable. Avoid closures or complex objects unless the package explicitly supports them. Convert models to arrays or simple DTOs first.
• Validation depends on the Vue component emitting the right value. If server-side rules fail unexpectedly, inspect the request payload in the browser. A custom component that emits an object instead of a scalar will not satisfy string, numeric, or similar rules.
• Index/detail support is not guaranteed. Initial releases often focus on the form component. Test index and detail views explicitly; if they are unsupported, use ->hideFromIndex() and ->hideFromDetail() until the package adds them.
• Pin the version for production. Since this is v1.0.0, treat the API as unstable. Use an exact constraint such as "vendor/nova-field": "1.0.0" until you have reviewed later releases.
• Debugging checklist:
  1. Confirm the field class is autoloaded.
  2. Confirm the resource field is declared with the correct attribute.
  3. Confirm the service provider registers the compiled JS/CSS.
  4. Check the browser console for Vue errors.
  5. Inspect the field’s serialized metadata in the Nova request response.
  6. Verify the saved value in the database after submitting the form.
• Extension points to inspect in src/: resolve(), fill(), withMeta(), jsonSerialize(), and any package-specific methods documented in the README. Those are the safest places to customize behavior without forking the Vue components.