@babel/plugin-syntax-flow

@babel/plugin-syntax-flow is a Babel syntax plugin that enables parsing of Flow type annotations in JavaScript code. It is a lightweight plugin that adds Flow syntax support to Babel's parser without performing any transformations, allowing developers to use Flow type syntax in their code by configuring Babel to recognize Flow-specific language constructs.

Important: This plugin only enables parsing of Flow syntax - it does not transform or remove Flow type annotations. For transformation, use @babel/plugin-transform-flow-strip-types or @babel/preset-flow.

Package Information

• Package Name: @babel/plugin-syntax-flow
• Package Type: npm
• Language: TypeScript (compiled to JavaScript with CommonJS/ESM exports)
• Installation: npm install --save-dev @babel/plugin-syntax-flow or yarn add @babel/plugin-syntax-flow --dev

Core Imports

import plugin from "@babel/plugin-syntax-flow";
import type { Options } from "@babel/plugin-syntax-flow";

For CommonJS:

const plugin = require("@babel/plugin-syntax-flow");
// TypeScript users can import the Options type:
// import type { Options } from "@babel/plugin-syntax-flow";

Basic Usage

Add the plugin to your Babel configuration:

// babel.config.js
module.exports = {
  plugins: ["@babel/plugin-syntax-flow"]
};

With options:

// babel.config.js
module.exports = {
  plugins: [
    ["@babel/plugin-syntax-flow", { all: true }]
  ]
};

Example Flow code that can be parsed:

// @flow
function add(x: number, y: number): number {
  return x + y;
}

type User = {
  id: number,
  name: string,
  email?: string
};

const user: User = {
  id: 1,
  name: "John Doe"
};

Capabilities

Default Export

The main plugin function created using the declare helper from @babel/helper-plugin-utils.

/**
 * Flow syntax plugin created with declare() helper
 * Configures Babel to parse Flow type annotations
 */
declare const plugin: (
  api: PluginAPI,
  options: Options,
  dirname: string
) => {
  name: "syntax-flow";
  manipulateOptions(opts: any, parserOpts: { plugins: Array<string | [string, any]> }): void;
};

export default plugin;

interface PluginAPI {
  version: string;
  assertVersion(range: number | string): void;
}

Options Export

Configuration options interface that is also exported as a named export.

/**
 * Configuration options for the Flow syntax plugin
 */
export interface Options {
  /** When enabled, treats all files as if they have the @flow pragma */
  all?: boolean;
  /** @deprecated Removed in Babel 8. Previously controlled Flow enums parsing (now always enabled) */
  enums?: boolean;
}

Usage Example:

// Enable Flow parsing for all files
{
  "plugins": [
    ["@babel/plugin-syntax-flow", { "all": true }]
  ]
}

Plugin Behavior

The plugin works by manipulating Babel's parser options to enable Flow syntax recognition:

1. Parser Plugin Registration: Adds ["flow", { all, enums }] to parserOpts.plugins array
2. TypeScript Conflict Prevention: In Babel 7, automatically skips Flow registration if TypeScript plugin is already present
3. Pragma Handling: When all: true, treats all files as if they contain the @flow pragma
4. Version-Specific Behavior:
   • Babel 7: Passes both all and enums options to Flow parser
   • Babel 8: Only passes all option (enums always enabled)
5. Compatibility Check: Uses api.assertVersion(REQUIRED_VERSION(7)) to ensure Babel 7+ compatibility

Technical Details:

• The plugin implements the manipulateOptions hook which modifies parser options before parsing begins
• It adds the Flow parser plugin to Babel's internal parser configuration
• The actual Flow syntax parsing is handled by Babel's built-in Flow parser plugin
• This is a "syntax-only" plugin - it doesn't provide any AST transformations or visitors

Error Handling

The plugin validates configuration options and throws descriptive errors:

// Error thrown for invalid .all option
throw new Error(".all must be a boolean, or undefined");

// Error thrown in Babel 8 for deprecated .enums option  
throw new Error("The .enums option has been removed and it's now always enabled. Please remove it from your config.");

// Warning in Babel 7 for deprecated .enums option
console.warn("The .enums option has been removed and it's now always enabled.");

Error Conditions:

• Throws error if .all option is not a boolean or undefined
• In Babel 8: Throws error if deprecated .enums option is provided (any value)
• In Babel 7: Issues console warning if deprecated .enums option is set to false
• Version compatibility errors are handled by the Babel API via assertVersion(REQUIRED_VERSION(7))

Compatibility

• Node.js: >=6.9.0 (Babel 7), ^20.19.0 || >=22.12.0 (Babel 8)
• Babel: ^7.0.0-0 (peer dependency)
• Dependencies: @babel/helper-plugin-utils (workspace dependency)
• Module System: Dual CommonJS/ESM exports (package.json "type": "module")
• TypeScript: Full type definitions included (.d.ts files)
• Export Paths:
  • Main: ./lib/index.js
  • Types: ./lib/index.d.ts
  • Package info: ./package.json