Vue3 JSON Editor

Common errors

• Failed to resolve component: Vue3JsonEditor

  cause The Vue3JsonEditor component was not properly registered or imported in the parent Vue component.
  fix Ensure you have `import { Vue3JsonEditor } from 'vue3-json-editor'` in your script and added it to the `components` option: `components: { Vue3JsonEditor }`.

• TypeError: Cannot read properties of undefined (reading 'mode')

  cause The `v-model` bound JSON data was not initialized as an object or was otherwise `undefined` or `null` when the component tried to access its properties.
  fix Initialize your `v-model` data property with an empty object (e.g., `{}`) or a valid JSON object. For example, `const state = reactive({ json: {} })`.

• Uncaught TypeError: can't access property 'exports', ks is undefined (or similar module resolution errors)

  cause This typically indicates a module resolution incompatibility, often occurring in Vite/ESM-first environments trying to consume a library with CommonJS peculiarities, or a breaking change in how the package bundles its exports.
  fix For Vite projects, if the issue persists, consider adding `@originjs/vite-plugin-commonjs` to your `vite.config.js` to improve CommonJS compatibility. Also, review recent changes in the library's changelog for breaking build-related changes.

Warnings

• breaking This library is a fork specifically for Vue 3. It is not compatible with Vue 2 projects, and attempting to use it in a Vue 2 environment will result in errors related to Vue 3-specific APIs and component registration.
  Fix: Ensure your project is running Vue 3.x. For Vue 2 projects, seek a compatible JSON editor component or migrate your application to Vue 3.
• gotcha The `v-model` binding for `vue3-json-editor` expects a JSON object for 'tree' mode and a JSON string for 'text' mode. Mismatching the data type with the editor's `mode` property can lead to unexpected behavior or errors.
  Fix: Always initialize `v-model` with an appropriate JavaScript object (for `mode='tree'`) or a JSON string (for `mode='text'`). The `onJsonChange` event provides the updated value in the correct type.
• gotcha When using the `setup` function in Vue 3, reactive state for `v-model` must be correctly defined using `reactive` or `ref`. Directly assigning a plain object to `v-model` without reactivity will prevent proper updates from the editor.
  Fix: Wrap your JSON data in `reactive` or `ref`. For example, `const state = reactive({ json: {} })` and then spread `...toRefs(state)` in the return object, or use `const json = ref({})`.
• gotcha Some users have reported `TypeError: Cannot read property 'getMode' of null` or similar runtime errors, especially in specific build environments like Quasar with Vue 3 CLI or after certain version updates, suggesting issues with module resolution or component initialization.
  Fix: Check for common module resolution issues (e.g., in `vite.config.js` for Vite projects, consider `@originjs/vite-plugin-commonjs` if using CommonJS dependencies). Ensure the component is correctly registered and mounted. Verify that the editor's internal dependencies are resolving correctly.

Install

• npm install vue3-json-editor npm
• yarn add vue3-json-editor yarn
• pnpm add vue3-json-editor pnpm

Imports

• Vue3JsonEditor
  wrong:

  const Vue3JsonEditor = require('vue3-json-editor')

  correct:

  import { Vue3JsonEditor } from 'vue3-json-editor'

  The library primarily uses named exports and is designed for ESM environments, although CommonJS is also supported. Using `require` might lead to incorrect module resolution or bundling issues in modern Vue 3/Vite projects.
• defineComponent

  import { defineComponent } from 'vue'

  Standard Vue 3 Composition API utility, commonly used when defining components with `setup` function.
• reactive

  import { reactive } from 'vue'

  Standard Vue 3 reactivity API for creating reactive state objects.
• toRefs

  import { toRefs } from 'vue'

  Standard Vue 3 utility for converting a reactive object's properties into a collection of refs, often used when returning state from a `setup` function.

Quickstart

This quickstart demonstrates how to integrate `vue3-json-editor` into a Vue 3 component using the Composition API, binding a JSON object with `v-model` and handling change and error events.

<template>
  <div>
    <p>JSON Editor Example</p>
    <Vue3JsonEditor
      v-model="json"
      :show-btns="true"
      :expandedOnStart="true"
      mode="tree"
      @json-change="onJsonChange"
      @has-error="onJsonError"
    />
  </div>
</template>

<script lang="ts">
import { defineComponent, reactive, toRefs } from 'vue'
import { Vue3JsonEditor } from 'vue3-json-editor'

export default defineComponent({
  components: {
    Vue3JsonEditor
  },
  setup () {
    const state = reactive({
      json: { 
        name: "John Doe", 
        age: 30, 
        isStudent: false, 
        courses: ["Math", "Science"] 
      }
    })

    function onJsonChange (value: object) {
      console.log('JSON has changed:', value)
      // You might want to update the reactive 'json' state here if not using v-model directly.
    }

    function onJsonError (error: any) {
      console.error('JSON error:', error)
    }

    return {
      ...toRefs(state),
      onJsonChange,
      onJsonError
    }
  }
})
</script>

<style>
/* Basic styling for demonstration */
body { font-family: sans-serif; margin: 20px; }
div { max-width: 800px; margin: 0 auto; }
</style>