or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-rollup--plugin-json

Convert .json files to ES6 modules for Rollup bundling

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@rollup/plugin-json@6.1.x

To install, run

npx @tessl/cli install tessl/npm-rollup--plugin-json@6.1.0

index.mddocs/

@rollup/plugin-json

A Rollup plugin that converts JSON files to ES6 modules, enabling seamless integration of JSON data into JavaScript/TypeScript projects. The plugin transforms .json files into importable modules with configurable options for named exports, code formatting, tree-shaking optimization, and compact output generation.

Package Information

  • Package Name: @rollup/plugin-json
  • Package Type: npm (Rollup plugin)
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install @rollup/plugin-json --save-dev

Core Imports

import json from "@rollup/plugin-json";

For CommonJS:

const json = require("@rollup/plugin-json");

Basic Usage

// rollup.config.js
import json from "@rollup/plugin-json";

export default {
  input: "src/index.js",
  output: {
    dir: "output",
    format: "cjs"
  },
  plugins: [json()]
};

With the plugin configured, you can import JSON files as ES6 modules:

// src/data.json
{
  "name": "my-package",
  "version": "1.0.0",
  "description": "Example package"
}

// src/index.js
import data from "./data.json";
import { name, version } from "./data.json"; // Named exports (default behavior)

console.log(data.name); // "my-package"
console.log(name);      // "my-package"
console.log(version);   // "1.0.0"

Capabilities

Plugin Factory Function

Creates a Rollup plugin instance that transforms JSON files to ES6 modules.

/**
 * Creates a Rollup plugin that converts JSON files to ES6 modules
 * @param options - Configuration options for the plugin
 * @returns Rollup plugin instance
 */
export default function json(options?: RollupJsonOptions): Plugin;

File Filtering

Control which JSON files are processed using include/exclude patterns.

interface RollupJsonOptions {
  /**
   * All JSON files will be parsed by default,
   * but you can also specifically include files
   */
  include?: FilterPattern;
  /**
   * All JSON files will be parsed by default,
   * but you can also specifically exclude files
   */
  exclude?: FilterPattern;
}

Usage Example:

// Only process JSON files in specific directories
json({
  include: ["src/**/*.json", "data/**/*.json"],
  exclude: ["node_modules/**", "test/**/*.json"]
})

Tree-shaking Optimization

Configure variable declaration types for optimal tree-shaking.

interface RollupJsonOptions {
  /**
   * For tree-shaking, properties will be declared as variables, using
   * either `var` or `const`.
   * @default false
   */
  preferConst?: boolean;
}

Usage Example:

// Generate const declarations for better tree-shaking
json({
  preferConst: true
})

// Generated output:
// const name = "my-package";
// const version = "1.0.0";
// export { name, version };

Output Formatting

Control the formatting and structure of generated ES6 modules.

interface RollupJsonOptions {
  /**
   * Specify indentation for the generated default export
   * @default '\t'
   */
  indent?: string;
  /**
   * Ignores indent and generates the smallest code
   * @default false
   */
  compact?: boolean;
}

Usage Example:

// Custom indentation
json({
  indent: "  " // Use 2 spaces instead of tabs
})

// Compact output for production
json({
  compact: true // Minimal whitespace
})

Named Exports Configuration

Control whether individual JSON properties are exported as named exports.

interface RollupJsonOptions {
  /**
   * Generate a named export for every property of the JSON object
   * @default true
   */
  namedExports?: boolean;
  /**
   * Generate named exports for properties that are not valid JavaScript identifiers
   * @default false
   */
  includeArbitraryNames?: boolean;
}

Usage Example:

// Disable named exports, only export default
json({
  namedExports: false
})

// Enable arbitrary property names as exports
json({
  includeArbitraryNames: true
})

// For JSON with invalid identifier properties:
// { "my-key": "value", "123abc": "test" }
// Generates: export { "my-key", "123abc" };

Types

/**
 * Rollup plugin configuration options for JSON processing
 * Note: includeArbitraryNames is supported in implementation but missing from official TypeScript interface
 */
export interface RollupJsonOptions {
  include?: FilterPattern;
  exclude?: FilterPattern;
  preferConst?: boolean;
  indent?: string;
  compact?: boolean;
  namedExports?: boolean;
  includeArbitraryNames?: boolean; // Available in implementation, not in TypeScript interface
}

/**
 * Filter pattern type from @rollup/pluginutils
 * Can be a string, array of strings, or regular expression
 */
type FilterPattern = string | RegExp | Array<string | RegExp> | null;

/**
 * Rollup plugin interface
 */
interface Plugin {
  name: string;
  transform?: (code: string, id: string) => any;
}

Error Handling

The plugin provides descriptive error messages for common issues:

  • JSON Parse Errors: When a .json file contains invalid JSON, the plugin throws an error with the file path and original parse error details
  • Transform Errors: Any issues during the transformation process include the file ID for debugging
// Example error output:
// Error: Could not parse JSON file
// File: /path/to/invalid.json
// Cause: SyntaxError: Unexpected token } in JSON at position 15

Advanced Configuration

Complete configuration example with all options:

import json from "@rollup/plugin-json";

export default {
  input: "src/index.js",
  output: {
    dir: "dist",
    format: "esm"
  },
  plugins: [
    json({
      // Process only specific files
      include: ["src/**/*.json", "data/**/*.json"],
      exclude: ["node_modules/**"],
      
      // Tree-shaking optimization
      preferConst: true,
      
      // Output formatting
      indent: "  ",
      compact: false,
      
      // Export configuration
      namedExports: true,
      includeArbitraryNames: true
    })
  ]
};