@babel/plugin-syntax-json-strings

@babel/plugin-syntax-json-strings is a Babel syntax plugin that enables parsing of JSON strings syntax, specifically allowing Unicode line separator (U+2028) and paragraph separator (U+2029) characters within JavaScript strings. This plugin provides the syntax parsing capability required for JSON superset compliance.

Package Information

• Package Name: @babel/plugin-syntax-json-strings
• Package Type: npm (Babel syntax plugin)
• Language: JavaScript
• Installation: npm install --save-dev @babel/plugin-syntax-json-strings

Note: This package is distributed as a standalone npm package and is not part of the main Babel monorepo source code. It follows the standard Babel syntax plugin architecture pattern.

Core Imports

// Default export (plugin function)
const jsonStringsPlugin = require("@babel/plugin-syntax-json-strings");

ES6 import:

import jsonStringsPlugin from "@babel/plugin-syntax-json-strings";

Basic Usage

This plugin is added to your Babel configuration to enable JSON strings syntax parsing:

babel.config.js:

module.exports = {
  plugins: [
    "@babel/plugin-syntax-json-strings"
  ]
};

package.json:

{
  "babel": {
    "plugins": ["@babel/plugin-syntax-json-strings"]
  }
}

Once enabled, the parser can handle JavaScript strings containing U+2028 and U+2029 characters:

// These characters become parseable in JS strings:
const lineWithLineSeparator = "Line one\u2028Line two";
const lineWithParagraphSeparator = "Paragraph one\u2029Paragraph two";

Note: This is a syntax-only plugin. It enables parsing but does not transform the code. For actual transformation of these characters, use @babel/plugin-proposal-json-strings which depends on this plugin.

Capabilities

Plugin Function

The main export is a Babel plugin function that configures the parser to support JSON strings syntax.

/**
 * Babel plugin function that enables JSON strings syntax parsing
 * @param {Object} api - Babel API object with version assertion utilities
 * @returns {Object} Babel plugin configuration object
 */
export default function(api: BabelAPI): BabelPlugin;

interface BabelAPI {
  /** Assert that the Babel version is compatible */
  assertVersion(version: number): void;
}

interface BabelPlugin {
  /** Plugin identifier */
  name: "syntax-json-strings";
  /** Method that modifies parser options to enable jsonStrings syntax */
  manipulateOptions(opts: BabelOptions, parserOpts: ParserOptions): void;
}

interface BabelOptions {
  /** Babel transformation options */
  [key: string]: any;
}

interface ParserOptions {
  /** Array of parser plugins to enable */
  plugins: (string | [string, any])[];
}

Plugin Configuration Object

The plugin returns a configuration object that follows the standard Babel plugin pattern:

interface BabelPlugin {
  /** 
   * Plugin identifier used by Babel
   * Set to "syntax-json-strings" 
   */
  name: "syntax-json-strings";
  
  /**
   * Modifies parser options to enable JSON strings syntax
   * Adds "jsonStrings" to the parser plugins array
   * @param opts - Babel transformation options (not used by syntax plugins)
   * @param parserOpts - Babel parser options object
   */
  manipulateOptions(opts: BabelOptions, parserOpts: ParserOptions): void;
}

Dependencies

The plugin requires the following dependencies:

• @babel/helper-plugin-utils: Used to create the plugin with proper API version checking
• @babel/core: Peer dependency required for Babel compatibility (^7.0.0-0)

Implementation Details

This is a syntax-only plugin that follows the standard Babel syntax plugin pattern:

1. Version Validation: Uses api.assertVersion(7) to ensure compatibility with Babel 7+
2. Parser Option Modification: Implements manipulateOptions to add "jsonStrings" to the parser plugins array
3. Syntax Parsing Only: Enables parsing but performs no code transformation
4. Inheritance Support: Can be inherited by other plugins (e.g., @babel/plugin-proposal-json-strings)

The plugin enables parsing of these Unicode characters in JavaScript strings:

• U+2028 LINE SEPARATOR: Unicode line separator character
• U+2029 PARAGRAPH SEPARATOR: Unicode paragraph separator character

These characters are valid in JSON but cause syntax errors in JavaScript without this plugin.

Error Handling

The plugin performs Babel API version assertion during initialization. If an incompatible Babel version is detected, the plugin will throw an error during the build process.

Related Packages

• @babel/plugin-proposal-json-strings: Transforms JSON strings with Unicode separators and inherits from this syntax plugin for parsing support
• @babel/helper-plugin-utils: Utility functions for creating Babel plugins, used by this plugin for proper API integration
• @babel/parser: The Babel parser that this plugin extends to support JSON strings syntax