vite-plugin-jsonx

1.2.2 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.2.2) that enables importing JSON5 and JSONC files as ES modules in Vite projects. Supports customizable parser options for both formats, ships TypeScript declarations, and requires Vite >=4.0.0 and Node >=20. Released under MIT, maintained on GitHub. Compared to raw JSON imports, it allows comments, trailing commas, and relaxed syntax while integrating seamlessly with Vite's build pipeline.

Common errors

error [vite] Internal server error: Plugin must be an object. ↓

cause Passing jsonX (function reference) instead of jsonX() in plugins array.

fix

Change plugins: [jsonX] to plugins: [jsonX()].

error Cannot find module './data.json5' or its corresponding type declarations. ↓

cause Missing TypeScript ambient type declarations for .json5/.jsonc files.

fix

Add /// <reference types="vite-plugin-jsonx/client" /> to your env.d.ts file.

error TypeError: jsonX is not a function ↓

cause Incorrect import style (default import instead of named import).

fix

Use import { jsonX } from 'vite-plugin-jsonx' (named import).

Warnings

gotcha The plugin must be invoked (jsonX()) not passed as reference. If you pass jsonX without parentheses, Vite will throw an error: 'Plugin must be an object'. Ensure you call the function. ↓

fix Change plugins: [jsonX] to plugins: [jsonX()]

gotcha TypeScript users must add the client types reference in env.d.ts. Without it, importing .jsonc/.json5 files will cause TS error 'Cannot find module'. ↓

fix Add /// <reference types="vite-plugin-jsonx/client" /> to your env.d.ts

breaking Vite version requirement: Vite >=4.0.0. Using with older Vite versions will fail silently or break the build. ↓

fix Upgrade Vite to 4.0.0 or later.

breaking Node version requirement: Node >=20. Older Node versions may encounter runtime errors because the package uses modern JS features. ↓

fix Upgrade Node.js to version 20 or higher.

gotcha The imported content is a plain object, not a special module shape. Ensure your code expects the correct data structure (e.g., default export is the parsed JSON object). ↓

fix Use import statements as shown in docs; for dynamic imports, use default property: const data = await import('./data.jsonc').then(m => m.default)

Install

npm install vite-plugin-jsonx

yarn add vite-plugin-jsonx

pnpm add vite-plugin-jsonx

Imports

jsonX
wrong
```
import jsonX from 'vite-plugin-jsonx'
```
correct
```
import { jsonX } from 'vite-plugin-jsonx'
```
Named export (not default). The plugin only exports a named function.

plugin type

wrong

export default { plugins: [jsonX] }

correct

import type { UserConfig } from 'vite'; import { jsonX } from 'vite-plugin-jsonx'; export default { plugins: [jsonX()] } satisfies UserConfig

Must call jsonX() (invoke function) to get plugin instance; passing the function without parentheses will break.

client types reference
wrong
```
import 'vite-plugin-jsonx/client'
```
correct
```
/// <reference types="vite-plugin-jsonx/client" />
```
Add to env.d.ts for TypeScript ambient module declarations for .jsonc/.json5 imports. Improper import won't augment types.

Quickstart

Sets up the plugin in vite.config.ts with optional parser options, imports a .json5 file, and logs its property.

// vite.config.ts
import { defineConfig } from 'vite';
import { jsonX } from 'vite-plugin-jsonx';

export default defineConfig({
  plugins: [
    jsonX({
      // optional: pass custom parser options
      json5ParserOptions: { quote: 'double' },
      jsoncParserOptions: { reviver: (key, value) => value }
    })
  ]
});

// src/data.json5
{
  name: 'Example',
  version: 1.0,
  // comment
}

// src/main.ts
import config from './data.json5';
console.log(config.name); // 'Example'