This PR contains:

• bugfix
• feature
• refactor
• documentation
• other

Are tests included?

• yes (bugfixes and features will not be merged without tests)
• no

Breaking Changes?

• yes (breaking changes will not be merged unless absolutely necessary)
• no

List any relevant issue numbers:

Description

This is a big feature that has been in the works since early that year. It was the result of a workshop on that topic and has been thoroughly refined since then. It introduces JSX support in three flavors:

• preserving JSX: This keeps JSX tags in the output but will take care of tree-shaking and name deconflicting. This is the main reason this feature is introduced in the first place. With the next major Rollup version, I would ideally like to remove support for returning an AST from plugins. Together with the removal of acorn plugin support, this means it is no longer possible to run Rollup with unsupported syntax. As JSX was one major use case, we are adding this now as a core feature, which will also provide better tree-shaking support and avoid hacks for handling deconflicting.
• classic transformation: This is the classic React transformation, but it can be configured for any other framework, see below.
• automatic transformation: This uses the "new" React transformation, but with fallback to the classic transformation in edge cases.

In a way, were are now matching what TypeScript is providing. Special thanks to @Martin-Idel, @felixhuttmann, @AlexDroll and @tiptr who contributed to the original workshop.

Copied from the new documentation:

jsx

type JsxPreset = 'react' | 'react-jsx' | 'preserve' | 'preserve-react';

type JsxOptions =
	| {
			mode: 'preserve';
			factory: string | null;
			fragment: string | null;
			importSource: string | null;
			preset: JsxPreset | null;
	  }
	| {
			mode: 'classic';
			factory: string;
			fragment: string;
			importSource: string | null;
			preset: JsxPreset | null;
	  }
	| {
			mode: 'automatic';
			factory: string;
			importSource: string;
			jsxImportSource: string;
			preset: JsxPreset | null;
	  };

Allows Rollup to process JSX syntax to either preserve or transform it depending on the jsx.mode. If set to false, an error will be thrown if JSX syntax is encountered. You may also choose a preset that will set all options together:

• "react": For transpiling JSX to React.createElement calls, where React is the default import from "react". This is the same as setting "jsx": "react" in the TypeScript compiler options.

  ({
  	mode: 'classic',
  	factory: 'React.createElement',
  	fragment: 'React.Fragment',
  	importSource: 'react'
  });

• "react-jsx": This will use the new optimized React transformation introduced with React 17 and is similar to setting "jsx": "react-jsx" in the TypeScript compiler options.

  ({
  	mode: 'automatic',
  	factory: 'React.createElement',
  	importSource: 'react',
  	jsxImportSource: 'react/jsx-runtime'
  });

• "preserve": This will preserve JSX in the output. This will still tree-shake unused JSX code and may rename JSX identifiers if there are conflicts in the output.

  ({
  	mode: 'preserve',
  	factory: null,
  	fragment: null,
  	importSource: null
  });

• "preserve-react": This will preserve JSX in the output but ensure that the default export of "react" is in scope as the React variable.

  ({
  	mode: 'preserve',
  	factory: 'React.createElement',
  	fragment: 'React.Fragment',
  	importSource: 'react'
  });

jsx.mode

This will determine how JSX is processed:

• "preserve": Will keep JSX syntax in the output.

• "classic": This will perform a JSX transformation as it is needed by older React versions or other frameworks like for instance Preact. As an example, here is how you would configure jsx for Preact:

  ({
  	mode: 'classic',
  	factory: 'h',
  	fragment: 'Fragment',
  	importSource: 'preact'
  });

  This would perform the following transformation:

  // input
  console.log(<div>hello</div>);
  
  // output
  import { h } from 'preact';
  console.log(/*#__PURE__*/ h('div', null, 'hello'));

• "automatic": This will perform a JSX transformation using the new JSX transform introduced with React 17. In this mode, Rollup will try to use helpers from the jsx.jsxImportSource to transform JSX. As there are certain edge cases, this mode may still fall back to using the classic transformations when using the key property together with spread attributes. To this end, you can still specify jsx.importSource, jsx.factory, and jsx.fragment to configure classic mode.

jsx.factory

The function Rollup uses to create JSX elements in "classic" mode or as a fallback in "automatic" mode. This is usually React.createElement for React or h for other frameworks. In "preserve" mode, this will ensure that the factory is present if a jsx.importSource is specified, or otherwise not overridden by local variables. Only in "preserve" mode it is possible to set this value to null, in which case Rollup will not take care to keep any particular factory function in scope.

If the value contains a "." like React.createElement and an jsx.importSource is specified, Rollup will assume that the left part, e.g. React, refers to the default export of the jsx.importSource. Otherwise, Rollup assumes it is a named export.

jsx.fragment

The element function Rollup uses to create JSX fragments. This is usually React.Fragment for React or Fragment for other frameworks. In "preserve" mode, this will ensure that the fragment is present as an import if an jsx.importSource is specified, or otherwise not overridden by local variables. Only in "preserve" mode it is possible to set this value to null, in which case Rollup will not take care to keep any particular fragment function in scope.

If the value contains a "." like React.Fragment and an jsx.importSource is specified, Rollup will assume that the left part, e.g. React, refers to the default export of the jsx.importSource. Otherwise, Rollup assumes it is a named export.

jsx.importSource

Where to import the element factory function and/or the fragment element from. If left to null, Rollup will assume that factory and fragment refer to global variables and make sure they are not shadowed by local variables.

jsx.jsxImportSource

When using "automatic" mode, this will specify from where to import the jsx, jsxs and Fragment helpers needed for that transformation. It is not possible to get those from a global variable.

jsx.preset

Allows choosing one of the presets listed above while overriding some options.

// ---cut-start---
/** @type {import('rollup').RollupOptions} */
// ---cut-end---
export default {
	jsx: {
		preset: 'react',
		importSource: 'preact',
		factory: 'h'
	}
	// ...
};