Skip to main content

@lexical/compiler/PureAnnotations

Interfaces​

PureAnnotationsOptions​

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:98

Extends​

Properties​

enforce?​

optional enforce?: "post" | "pre"

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:103

Vite plugin ordering. Defaults to 'post' so the transform runs after TypeScript and JSX have been compiled away.

exclude?​

optional exclude?: RegExp | readonly RegExp[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:105

Module ids to skip. Defaults to none.

filename?​

optional filename?: string

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:35

Path of the module being transformed, used to choose the TypeScript and JSX parser plugins (and named as the source map's source).

Inherited from​

TransformPureAnnotationsOptions.filename

functions?​

optional functions?: Iterable<string, any, any>

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:40

Names of the factories whose module-scope calls are annotated. Defaults to PURE_FACTORY_FUNCTIONS.

Inherited from​

TransformPureAnnotationsOptions.functions

include?​

optional include?: RegExp | readonly RegExp[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:112

Module ids to transform. Defaults to every .js/.jsx/.ts/.tsx (and .mjs/.cjs/.mts/.cts) module, including those in node_modules so that a Lexical package consumed through its source export condition is annotated.

inline?​

optional inline?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:52

Replace calls to the factories whose result is a trivial expression over their arguments (safeCast, defineExtension, configExtension, declarePeerDependency, defineImportRule) with that expression rather than annotating them — a literal needs no annotation to be dropped, and nothing is left to pin the definition it appears in.

Off by default, because it assumes the Lexical being built matches this package's version. Lexical's own build turns it on for the bundles it publishes.

Inherited from​

TransformPureAnnotationsOptions.inline

namespaces?​

optional namespaces?: Iterable<string, any, any>

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:58

Imported objects whose method calls are side-effect free, so that sel.tag('p').attr('data-x', true) is annotated the way a call to a factory function is. Defaults to PURE_NAMESPACES.

Inherited from​

TransformPureAnnotationsOptions.namespaces

parserPlugins?​

optional parserPlugins?: readonly unknown[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:60

Extra @babel/parser plugins to parse the module with.

Inherited from​

TransformPureAnnotationsOptions.parserPlugins

relativeImports?​

optional relativeImports?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:65

Set to false to skip reading relatively imported modules to look for a __NO_SIDE_EFFECTS__ declaration. Defaults to true.

Inherited from​

TransformPureAnnotationsOptions.relativeImports

sourceMap?​

optional sourceMap?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:67

Set to false to skip source map generation.

Inherited from​

TransformPureAnnotationsOptions.sourceMap

sources?​

optional sources?: RegExp | readonly RegExp[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:75

Module specifiers whose exports are trusted to be the factories, without reading the module they come from. Defaults to lexical and @lexical/*; a call to a same-named function from anywhere else is only annotated when the declaration it resolves to is itself marked __NO_SIDE_EFFECTS__.

Inherited from​

TransformPureAnnotationsOptions.sources

strict?​

optional strict?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:83

Throw when a call evaluated inside one of the definitions is not known to be side-effect free. Such a call pins the definition into every bundle that imports the module, however well annotated the definition itself is, so this turns a silent loss of tree-shaking into a build error naming the call. Off by default.

Inherited from​

TransformPureAnnotationsOptions.strict

PureAnnotationsPlugin​

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:120

The structural shape of the returned plugin. It is assignable to Vite's Plugin and to Rollup's Plugin, so it can be dropped into the plugins array of either.

Properties​

enforce?​

optional enforce?: "post" | "pre"

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:121

name​

name: string

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:122

Methods​

transform()​

transform(code, id): { code: string; map: PureAnnotationsSourceMap | null; } | null

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:123

Parameters​
code​

string

id​

string

Returns​

{ code: string; map: PureAnnotationsSourceMap | null; } | null

PureAnnotationsResult​

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:86

Properties​

code​

code: string

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:87

count​

count: number

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:89

The number of annotations that were inserted.

inlined​

inlined: number

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:94

The number of calls that were replaced by the literal they would have returned. Always 0 unless inline is set.

map?​

optional map?: PureAnnotationsSourceMap

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:95

PureAnnotationsSourceMap​

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:21

The subset of a source map that bundlers consume, matching what magic-string produces. Declared structurally so this package needs no dependency on any particular bundler's types.

Properties​

file?​

optional file?: string

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:22

mappings​

mappings: string

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:23

names​

names: string[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:24

sources​

sources: string[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:25

sourcesContent?​

optional sourcesContent?: (string | null)[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:26

version​

version: number

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:27

TransformPureAnnotationsOptions​

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:30

Extended by​

Properties​

filename?​

optional filename?: string

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:35

Path of the module being transformed, used to choose the TypeScript and JSX parser plugins (and named as the source map's source).

functions?​

optional functions?: Iterable<string, any, any>

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:40

Names of the factories whose module-scope calls are annotated. Defaults to PURE_FACTORY_FUNCTIONS.

inline?​

optional inline?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:52

Replace calls to the factories whose result is a trivial expression over their arguments (safeCast, defineExtension, configExtension, declarePeerDependency, defineImportRule) with that expression rather than annotating them — a literal needs no annotation to be dropped, and nothing is left to pin the definition it appears in.

Off by default, because it assumes the Lexical being built matches this package's version. Lexical's own build turns it on for the bundles it publishes.

namespaces?​

optional namespaces?: Iterable<string, any, any>

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:58

Imported objects whose method calls are side-effect free, so that sel.tag('p').attr('data-x', true) is annotated the way a call to a factory function is. Defaults to PURE_NAMESPACES.

parserPlugins?​

optional parserPlugins?: readonly unknown[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:60

Extra @babel/parser plugins to parse the module with.

relativeImports?​

optional relativeImports?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:65

Set to false to skip reading relatively imported modules to look for a __NO_SIDE_EFFECTS__ declaration. Defaults to true.

sourceMap?​

optional sourceMap?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:67

Set to false to skip source map generation.

sources?​

optional sources?: RegExp | readonly RegExp[]

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:75

Module specifiers whose exports are trusted to be the factories, without reading the module they come from. Defaults to lexical and @lexical/*; a call to a same-named function from anywhere else is only annotated when the declaration it resolves to is itself marked __NO_SIDE_EFFECTS__.

strict?​

optional strict?: boolean

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:83

Throw when a call evaluated inside one of the definitions is not known to be side-effect free. Such a call pins the definition into every bundle that imports the module, however well annotated the definition itself is, so this turns a silent loss of tree-shaking into a build error naming the call. Off by default.

Variables​

INLINE_FACTORY_FORMS​

const INLINE_FACTORY_FORMS: ReadonlyMap<string, string> = impl.INLINE_FACTORY_FORMS

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:151

The factories that inline replaces with a literal, and the form each one takes: identity returns its single argument and args returns all of its arguments as an array. Each is marked @lexical-inline <form> where it is defined.

PURE_FACTORY_FUNCTIONS​

const PURE_FACTORY_FUNCTIONS: readonly string[] = impl.PURE_FACTORY_FUNCTIONS

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:134

The Lexical factories that are annotated with __NO_SIDE_EFFECTS__ at their definition and whose module-scope call sites therefore need a __PURE__ annotation for bundlers to tree-shake unused definitions.

PURE_NAMESPACES​

const PURE_NAMESPACES: readonly string[] = impl.PURE_NAMESPACES

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:143

Objects imported from a Lexical package whose method calls are side-effect free, so that a module-scope sel.tag('p') is annotated the way a factory call is. Only the outermost call of a chain is annotated: rollup, terser and esbuild all drop the whole chain from that one.

Functions​

pureAnnotations()​

pureAnnotations(options?): PureAnnotationsPlugin

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:202

A Vite/Rollup plugin that inserts the __PURE__ annotations that let bundlers tree-shake unused Lexical extension, command, and rule definitions.

The published dist bundles already carry the annotations, so this is for builds that compile Lexical from its TypeScript source (the source export condition, a git checkout, or a vendored copy) — and for annotating the extensions and commands your own application defines.

import {pureAnnotations} from '@lexical/compiler';

export default defineConfig({plugins: [pureAnnotations()]});

Parameters​

options?​

PureAnnotationsOptions

Returns​

PureAnnotationsPlugin

pureCallNames()​

pureCallNames(code, options?): object

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:176

The local names in code whose module-scope calls the transform would annotate: functions are called directly, namespaces are objects whose method calls are annotated. A name qualifies by being imported from a Lexical package, declared in the module as side-effect free, or imported from a relative module that declares it that way. For tooling that needs the same decision without rewriting the module — a lint rule that removes a hand-written annotation only where the build puts one back. Throws on source it cannot parse.

Parameters​

code​

string

options?​

TransformPureAnnotationsOptions

Returns​

object

functions​

functions: ReadonlySet<string>

namespaces​

namespaces: ReadonlySet<string>

transformPureAnnotations()​

transformPureAnnotations(code, options?): PureAnnotationsResult | null

Defined in: packages/lexical-compiler/src/PureAnnotations.ts:159

Insert a __PURE__ annotation before every module-scope call to one of the side-effect-free Lexical factories that does not already have one. Returns null when the module needs no annotations.

Parameters​

code​

string

options?​

TransformPureAnnotationsOptions

Returns​

PureAnnotationsResult | null