rollup-plugin-json-map-keys

1.2.0 verified Mon Apr 27 auth: no javascript

Rollup plugin that recursively transforms JSON values into their dot-separated key paths, useful for i18n key generation or object value replacement. Latest version 1.2.0 (2025-11-22) requires rollup >= 2. The package has seen recent maintenance including dependency updates and path restructuring. It is part of a monorepo with webpack loader and Jest transformer equivalents. Key differentiators: designed specifically for Rollup, outputs JSON with key paths, supports custom prefix via options.

Common errors

error Error: Cannot find module 'rollup-plugin-json-map-keys' ↓

cause Package not installed or misconfigured in package.json.

fix

Run 'npm install rollup-plugin-json-map-keys --save-dev'

error TypeError: jsonMapKeys is not a function ↓

cause CommonJS require returns module.exports object with default property.

fix

Use ES import: 'import jsonMapKeys from 'rollup-plugin-json-map-keys'' or use 'const jsonMapKeys = require('rollup-plugin-json-map-keys').default'

error Error: '@rollup/plugin-json' is required to use rollup-plugin-json-map-keys ↓

cause Plugin only transforms JSON files imported via Rollup JSON plugin; without it, no .json files are processed.

fix

Install and add @rollup/plugin-json to plugins array.

Warnings

breaking After version 1.2.0, the package was moved to a new monorepo. Imports from 'rollup-plugin-json-map-keys' still work, but ensure you use the latest version to avoid path resolution issues. ↓

fix Update to rollup-plugin-json-map-keys@1.2.0 or later; verify lockfile for correct package.

gotcha The plugin works only with JSON files imported via @rollup/plugin-json or a similar JSON loader. It does not handle inline JSON objects. ↓

fix Add @rollup/plugin-json to your Rollup plugins list.

deprecated The prefix option uses '[name]' placeholder for the JSON file name. This behavior is not explicitly documented in older versions. ↓

fix Review prefix syntax in README for version 1.2.0.

gotcha The plugin does not support nested key references; it only replaces leaf values with the full key path. If a value is an object, it is not replaced. ↓

fix Ensure your JSON structure has intended leaf values (strings) to be replaced.

Install

npm install rollup-plugin-json-map-keys

yarn add rollup-plugin-json-map-keys

pnpm add rollup-plugin-json-map-keys

Imports

default
wrong
```
const jsonMapKeys = require('rollup-plugin-json-map-keys')
```
correct
```
import jsonMapKeys from 'rollup-plugin-json-map-keys'
```
ESM-only export. CommonJS require returns module.exports which is an object { default: ... } in this package, so you'd need jsonMapKeys.default if using require.

jsonMapKeys (default)

wrong

import { jsonMapKeys } from 'rollup-plugin-json-map-keys'

correct

import jsonMapKeys from 'rollup-plugin-json-map-keys'

Plugin is exported as default export, not named.

Plugin type

wrong

import { Plugin } from 'rollup-plugin-json-map-keys'

correct

import type { Plugin } from 'rollup'; // for TS users then use as return type of function

No TypeScript types are bundled; users should import Plugin from Rollup itself.

Quickstart

Configures Rollup to replace JSON values with dot-separated key paths, demonstates typical usage with @rollup/plugin-json.

import jsonMapKeys from 'rollup-plugin-json-map-keys';
import json from '@rollup/plugin-json'; // to import JSON files

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'es'
  },
  plugins: [
    json(), // resolves .json imports
    jsonMapKeys({
      prefix: '[name]:' // optional prefix for key paths
    })
  ]
};