Adding Publish Tags to Laravel Package Resources

When a Laravel package includes files that users might want to customize, publish tags let them copy selected files into their application. A publish tag is a name a package’s service provider uses to group instructions for copying package files to destinations in the user’s application. The service provider is the Laravel class that connects package features to the framework. A user runs php artisan vendor:publish --tag=... to copy one group without publishing the package’s other groups.

Choose tags based on what users want to customize, and document which files each tag publishes and where they go. Users can then find and publish configuration, views, migrations, or other resources without reading the package source. Laravel’s package-development documentation shows how to register these mappings and select them from the command line.

Register resources under separate tags

Use a separate tag when users might want to publish one resource category without copying another. In this example, the CourierServiceProvider exposes configuration, views, and migrations independently:

mergeConfigFrom(
            __DIR__.'/../config/courier.php',
            'courier',
        );
    }

    public function boot(): void
    {
        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');

        $this->loadViewsFrom(
            __DIR__.'/../resources/views',
            'courier',
        );

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');

        $this->publishesMigrations([
            __DIR__.'/../database/migrations' => database_path('migrations'),
        ], 'courier-migrations');
    }
}

Each publishes call maps a package path to a destination in the host application. The second argument names the group users select with --tag. The publishesMigrations method registers migrations for publishing under its tag.

loadViewsFrom lets Laravel find package views at runtime, while the separate publishes mapping gives users a local copy to customize. Configuration follows a similar pattern: mergeConfigFrom makes package defaults available, while the publishing mapping lets users create a local configuration file.

Choose tag names that identify both the package and the resource category, such as courier-config and courier-views. Users should not have to infer what a tag means from the provider’s class name.

Show the commands and destinations

Each tag identifies the group of files Laravel copies, and its mapping sets their destination. Document both so users know what each command will change:

# Publish only the package configuration
php artisan vendor:publish --tag=courier-config

# Publish only the package views
php artisan vendor:publish --tag=courier-views

# Publish only the package migrations
php artisan vendor:publish --tag=courier-migrations

# Publish all resources registered by this provider
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

The --provider option selects all publish mappings registered by that provider, while --tag selects one named group. Use a tag when users need a narrower choice. Laravel documents both command forms in its package resource instructions.

A package’s documentation should give users a resource catalog they can scan without opening the service provider:

Add the exact command beside each entry, and explain any follow-up action. For example, after publishing migrations, users run php artisan migrate when the package requires those database changes. A package might also publish language files or public assets; list their destinations and purpose in the same catalog if the package provides them.

Explain overwriting and runtime behavior

Users can publish resources again when they need files from a package update. Laravel’s documentation provides the --force option for overwriting files that were already published. Warn users that the flag overwrites files in the destination, including their local edits.

Laravel can load some package resources directly, so users can use them without copying them into their application. Publishing makes a local, customizable copy available; it does not automatically register every resource for runtime use.

Package helper libraries can simplify provider setup. For example, Spatie Laravel Package Tools provides helpers for common package resources and tags. These helpers follow that library’s conventions. A package that uses Laravel’s service-provider API directly registers publish mappings with Laravel’s own methods.

Check the published mappings

In a test application, run the corresponding vendor:publish command for each tag. Check that Laravel copies the expected files to the documented destination and leaves files assigned only to another tag untouched; this catches mismatches between the service provider and resource catalog before users encounter them.

Laravel’s package APIs and command behavior can vary across framework releases, so check the documentation for the Laravel version your package supports before relying on a version-specific method or command option.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com