FORM WIDGET: vueforge

YAML configuration:

my_field:
    label: My Field
    type: vueforge
    component: TagInput
    viteEntry: assets/vue/components/TagInput.vue
    props:
        placeholder: "Add a tag..."

Properties:

• component (string, default "JsonEditor") — the Vue component to mount. Must be registered in the plugin's ESM hydrator's component map, or via registerVueForgeComponent() for your own components.
• viteEntry (string, default "assets/vue/components/{component}.vue") — source path used to look up the built asset in Vite's manifest.
• props (array, default empty) — extra static props merged with the field's current value (passed to the component as modelValue).

Bundled example components:

• TagInput — array state (chips/tags input).
• JsonEditor — nested key/value object state.

Building your own widget: Run: php artisan vueforge:make {Plugin} {Name} Example: php artisan vueforge:make Acme.Blog TagList

This generates a PHP widget class (extending VueWidget, with $component/$viteEntry pre-filled) and a matching Vue 3 <script setup lang="ts"> component stub already wired to the state-sync composable. Register the generated widget in your plugin's Plugin::registerFormWidgets(), then use the printed YAML type: code in your fields.yaml.

Value round-trip:

1. Load — the widget reads the model attribute, JSON-encodes it, and renders it into the mount point's data attributes plus a hidden input.
2. Hydrate — the frontend hydrator finds the mount point, dynamically imports the named component, and mounts it with the parsed props.
3. Edit — the component's state stays synced to the hidden input's value on every change.
4. Save — October's normal form submit posts the hidden input's JSON string; the widget parses and sanitizes it (rejecting malformed JSON, stripping anything that isn't plain array/scalar data) before it's saved to the database.

Requirements: October CMS 4.2+, PHP 8.2+, Node 18+/npm for building frontend assets.

Full README and architecture notes are in the GitHub repository: https://github.com/amjadiqbal/oc-vueforge-plugin

Built by Amjad Iqbal (amjad.com.pk). Available for October CMS / Laravel / Vue freelance work: https://urlshortly.com/upwork

October CMS v4.2+ runs TWO separate, unrelated Vue 3 systems in the backend — confusing them is the most common mistake:

1. October's own native system (System\Classes\VueComponentBase + the VueMaker trait, scaffolded by "php artisan make:vuecomponent"). No SFCs, no TypeScript, no build step — components are plain JS objects loaded as global ESM modules.
2. VueForge (this plugin) — a FormWidgetBase subclass that hydrates a real Vue 3 .vue single-file component (Composition API, <script setup>, TypeScript) compiled by Vite. VueForge does NOT register through VueComponentBase/VueMaker and is not a replacement for it — it solves a different problem (arbitrary form-field UIs, not backend page chrome).

Key things that changed in October 4.2+ that affect anyone building custom Vue 3 backend controls:

• The AJAX framework is "Larajax", exposed as window.jax — not oc.ajax() or jQuery's .request().
• Backend partial/AJAX updates fire "ajax:update-complete"; Turbo page swaps fire "page:updated" — not jQuery's ajaxUpdate/ajaxComplete.
• A mitt()-based event bus replaces the old implicit Vue 2 root event bus — there is no more global $root.$on/$emit.
• Assets are resolved via Vite's manifest.json, keyed by source path, not a fixed output filename.
• File::checkBaseDir() restricts partial/view resolution to paths under the application's own base_path() by default — symlinking a plugin in from outside the app during development will silently break widget rendering; a real (non-symlinked) install does not have this problem.

If you are building a small, form-scoped interactive control (a tag list, a key/value editor, anything backed by a single field's JSON), use VueForge. If you are building backend page UI that needs to interoperate with October's own Vue components and their shared mitt event bus, use October's native VueComponentBase instead — the two systems are not meant to be mixed on the same mount point.

Full technical detail, including two real bugs found and fixed while verifying this against source: see docs/VUE3_MIGRATION_GUIDE.md in the GitHub repository.