@ptahjs/vite-plugin-json

Dynamic JSON Configuration Management for Vite

🚀 Features

• 🛠️ Virtual Module Support: Use a virtual module (virtual:JsonConfig) to dynamically load JSON configurations.
• ⚡ HMR: Watches the JSON source file and hot-reloads in dev mode without rebuilding.
• 🌐 BASE_URL-aware: Build-mode fetch respects import.meta.env.BASE_URL, so it works under sub-path deployments.
• 🧩 SSR-safe: Falls back to {} when fetch/window are unavailable (e.g. SSR / Node).
• 🐞 Graceful Fallback: Missing or invalid JSON files degrade to {} with a warning instead of crashing.
• 🪛 Customizable: Configure the source path and the emitted output filename with ease.

⚡ Installation

Install the plugin via pnpm:

pnpm add @ptahjs/vite-plugin-json --dev

Or using npm:

npm install @ptahjs/vite-plugin-json --dev

Or using yarn:

yarn add @ptahjs/vite-plugin-json --dev

⚙️ Usage

Add the plugin to your Vite configuration in vite.config.js:

import { defineConfig } from "vite";
import JsonConfig from "@ptahjs/vite-plugin-json";

export default defineConfig({
    plugins: [
        JsonConfig({
            path: "./src/config.json", // Path to your JSON file (relative to Vite root)
            outputName: "config.json", // Name of the emitted JSON file in build
        }),
    ],
});

The emitted file lands in Vite's build output directory (build.outDir, defaults to dist/). The plugin does not control the output directory — configure it via Vite's own build.outDir option if needed.

Example JSON File

An example config.json file:

{
    "apiEndpoint": "https://api.example.com",
    "debug": true
}

🧲 How It Works

Development Mode (serve)

• The plugin creates a virtual module (virtual:JsonConfig) to dynamically provide the JSON configuration.
• The virtual module can be imported in your application:

import JsonConfig from "virtual:JsonConfig";

JsonConfig((config) => {
    console.log("Loaded config:", config);
});

Build Mode (build)

• The JSON configuration is emitted as an asset to Vite's build output directory (default dist/) under the configured outputName (e.g. dist/config.json).
• The virtual module's default export fetches this file at runtime, respecting import.meta.env.BASE_URL:

import JsonConfig from "virtual:JsonConfig";

JsonConfig((config) => {
    console.log("Loaded config:", config);
});

Alternatively, you can fetch the file directly (adjust the URL to match your outputName and base path):

fetch(import.meta.env.BASE_URL + "config.json")
    .then((response) => response.json())
    .then((config) => {
        console.log("Loaded config:", config);
    });

📦 Build Output Format

The plugin itself is published as an ES Module. vite.config.js builds only the es format, producing dist/index.es.js (consumed via the package's import export). No CJS or UMD bundles are produced.

📝 Options

💻 Example Scenarios

1. Dynamic Configuration in Development
   Use the plugin in serve mode to load configuration dynamically without rebuilding the project.

2. Static Configuration in Production
   Build the project with a statically generated configuration file for better performance.

🔧 Development

Clone the repository and install dependencies:

git clone https://github.com/PtahJs/vite-plugin-json.git
cd vite-plugin-json
pnpm install

Build the plugin:

pnpm build

🔗 Contributing

Contributions are welcome! If you encounter issues or have feature requests, feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

📧 Contact

For questions or support, feel free to reach out at bobofpl@gmail.com.