Vite Tooling

Files#

We recommend using Vite to manage your addon's asset build process. To use Vite, you'll need the following files inside your addon.

your-addon/
  resources/
   dist/
   js/
    addon.js
   css/
    addon.css
  src/
   ServiceProvider.php
  vite.config.js
  package.json

package.json#

Here's package.json, which contains the commands you'll need to run, and the dependencies needed to run Vite.

• The laravel-vite-plugin package allows a simpler wrapper around common Vite options, and provides hot reloading.
• The @statamic/cms package allows you to import Vue components from Statamic. As it's not a "real" npm package, the code is being pulled from your addon's vendor directory.

{
    "private": true,
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    },
    "dependencies": {
        "@statamic/cms": "file:./vendor/statamic/cms/resources/dist-package"
    },
    "devDependencies": {
        "laravel-vite-plugin": "^1.2.0",
        "vite": "^6.3.4"
    }
}

vite.config.js#

Here's vite.config.js, which configures Vite itself.

• The Laravel Vite plugin defaults to the public directory to place the compiled code because it's intended to be used in your app. We've changed it to resources/dist as we think it's a nicer convention when using in an addon. Of course, you may customize it. Whichever directory you choose, you'll need to make sure it exists.
• The statamic plugin allows you to import Statamic's Vue components and CSS files.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import statamic from '@statamic/cms/vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/js/addon.js',
                'resources/css/addon.css'
            ],
            publicDirectory: 'resources/dist',
        }),
        statamic(),
    ],
});

Service Provider#

Here's ServiceProvider.php, which is the PHP entry point to your addon. You should add a $vite property which mirrors the paths in your vite.config.js file.

  class ServiceProvider extends AddonServiceProvider
  {
 +    protected $vite = [ 
 +        'input' => [
 +            'resources/js/addon.js',
 +            'resources/css/addon.css',
 +        ],
 +        'publicDirectory' => 'resources/dist',
 +    ]; 
 }

Hot Tip!

If you use the php please make:fieldtype command, these files will be created automatically for you.

Tailwind CSS#

If you want to use Tailwind CSS in your addon's views, you'll need to install & configure Tailwind.

1. First, install tailwindcss:

   npm install tailwindcss
   

2. In your addon's CSS file, import Statamic's tailwind.css file:

   @import "@statamic/cms/tailwind.css";
   

   You don't need to @import "tailwindcss", as it'll be imported by Statamic's tailwind.css file.

Development#

If you visit the Control Panel before running any commands, you will be greeted with a Vite manifest not found error. You'll need to install dependencies (the first time only) and start the development server.

npm install
npm run dev

Now that the Vite server is running, the error in the Statamic CP should be gone once you refresh.

With the development server running, hot reloading should be working. When you save a CSS or JS file, it should be reflected in the browser without you needing to manually refresh.

Hot Tip!

If you're using Valet with a secured site, your JS might not be loading correctly due to access control checks. You'll need Vite know about your Laravel site in vite.config.js.

 export default defineConfig({
     plugins: [
         laravel({
+            valetTls: 'yoursite.test', //
             input: [

To avoid needing to run the development script every time you visit the Control Panel, you may wish to build your CSS & JS.

npm run build

You may need to symlink your addon's resources/dist directory the first time so it points to your addon's directory:

ln -s ./addons/your/addon/resources/dist public/vendor/package

Vue Devtools#

Vue Devtools are disabled by default, for security reasons.

Statamic provides an opt-in dev build, allowing you to use Vue Devtools and see un-minified code, useful when debugging custom Vue components.

Your app must have debug mode enabled:

APP_DEBUG=true

The dev build can either be published via the vendor:publish command:

php artisan vendor:publish --tag=statamic-cp-dev

Alternatively, it can be symlinked:

ln -s /path/to/vendor/statamic/cms/resources/dist-dev public/vendor/statamic/cp-dev

Statamic will attempt to use the dev build as long as the public/vendor/statamic/cp-dev directory exists. You shouldn't commit these or use this on production.

Deployment#

When you're ready to deploy your addon, either to your own application or getting it ready to go into the marketplace, you should compile the production assets.

Make sure that the Vite dev server is not running, then run:

npm run build

The files will be compiled into resources/dist.

If you'd like to test that everything is working you can run php artisan vendor:publish in your app and choose your addon's tag. The compiled assets should be copied into public/vendor/your-addon and they should be loaded in the Control Panel.