[lexical-code][lexical-markdown] Extract Prism; make code fences opt-in#8197
[lexical-code][lexical-markdown] Extract Prism; make code fences opt-in#8197gurkerl83 wants to merge 7 commits intofacebook:mainfrom
Conversation
Move Prism implementation sources into `packages/lexical-code-prism/src`: - `CodeHighlighterPrism.ts` - `FacadePrism.ts` This commit is relocation-only: - no import rewiring - no behavior changes - no package/export wiring changes yet Follow-up commits will wire imports/exports and switch consumers.
Create initial @lexical/code-prism package scaffold. Adds: - package manifest - CJS package entry shim - source index entrypoint No runtime rewiring or API ownership changes yet.
Move Prism runtime API ownership from @lexical/code to @lexical/code-prism. - Rewire Prism implementation sources to depend on @lexical/code node APIs - Update @lexical/code exports/deps to remove Prism API surface - Update playground and integration fixtures to import Prism APIs from @lexical/code-prism - Add TS path mappings for @lexical/code-prism No markdown transformer composition changes in this commit.
Align Flow public type declarations with Prism extraction. - Add Flow declarations for @lexical/code-prism Prism API surface - Remove Prism-related declarations from @lexical/code Flow surface No runtime behavior changes in this commit.
- Remove markdown’s direct runtime dependency on @lexical/code. - Replace built-in CODE export with createMarkdownCodeBlockTransformer. - Add multiline transformer node predicates to preserve shortcut skip behavior. - Keep default TRANSFORMERS code-agnostic. - Update Flow/TS surfaces for the new composition API. - Rewire playground markdown transformer composition to use the factory. - Regenerate pnpm-lock.yaml with pnpm install --lockfile-only.
- Add a dedicated markdown composition test file for fenced code behavior. - Verify default TRANSFORMERS import fenced blocks as paragraphs. - Verify composed transformers ([...TRANSFORMERS, CODE]) import fenced blocks as CodeNode. - Keep broad LexicalMarkdown.test.ts focused on general markdown behavior. - Align test setup with createMarkdownCodeBlockTransformer composition usage.
- Add markdown README guidance for composing code fences with createMarkdownCodeBlockTransformer. - Update React plugin docs to show composed transformers usage with MarkdownShortcutPlugin. - Clarify that code-block shortcuts are opt-in via composition. - Update @lexical/code README to describe node/util ownership after Prism extraction. - Add @lexical/code-prism README describing Prism highlighting ownership.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This is a better direction but it breaks compatibility without any sort of real deprecation cycle. For a few releases @lexical/code is going to have to work as-is. The problem you want solved is not fixable in a single pass or in a single release, but you should be able to work around it by configuring your bundler to not include the prism stuff in the meantime in situations where you aren’t going to use it. |
|
Makes sense, and thanks for the guidance. A major release could be a better place for this kind of split. I also tried bundler-level mitigation in our app, but it was brittle in practice and didn’t reliably keep the Prism/code path out in all cases. For now, the compatibility requirement for @lexical/code as-is is clear, so I’ll leave this PR as-is. It may still be the wrong shape (especially around adding a compose layer), but it was intended as one exploration of stronger separation. |
|
Moving prism code to the new package makes sense, that part is directionally correct, but there should be deprecated re-exports from the main code package so that people can upgrade without changing the usage in lockstep. In the first pass, no behavior should change other than the addition of deprecation warnings and new packages/exports for the upgrade path. The playground and other sibling packages can be upgraded to use the new path to avoid deprecation warnings. No types or exports in @lexical/code should change. No behavior change to markdown should happen at all. No tests should need to change (other than imports, but only to avoid deprecation warnings) and all existing tests should pass. |
Summary
This PR removes the Prism-driven coupling between markdown and code packages by doing two coordinated changes:
@lexical/codeinto@lexical/code-prism.@lexical/markdown).Context
A previous attempt (#8196) proposed a lightweight
@lexical/code/nodesubpath to avoid importing the Prism-heavy@lexical/coderoot from markdown internals.Based on maintainer feedback (comment), this PR follows the structural direction instead:
Problem
@lexical/markdownand@lexical/codewere coupled such that optional code/highlighting paths affected markdown-only use cases. This made modular composition weaker than intended.Changes
1) Prism extraction
@lexical/code-prismpackage.@lexical/code-prism.2)
@lexical/codeslim-down@lexical/codekeeps code-node/core behavior.@lexical/coderoot.3) Markdown composition change
@lexical/markdownno longer has a direct runtime dependency on@lexical/code.TRANSFORMERSno longer includes code-fence behavior by default.createMarkdownCodeBlockTransformer(...)so code-fence behavior can be composed explicitly by consumers.isNodepredicate support so shortcut skip behavior remains correct for composed node types.4) Docs/tests updates
CodeNode),Semver-visible behavior change
@lexical/markdowndefaultTRANSFORMERSis now code-agnostic.Consumers that want fenced code block conversion to
CodeNodemust compose it explicitly.Migration
Validation
pnpm exec vitest run packages/lexical-markdown/src/__tests__/unit/LexicalMarkdown.test.ts packages/lexical-markdown/src/__tests__/unit/MarkdownTransformers.test.tspnpm exec vitest run packages/lexical-markdown/src/__tests__/unit/LexicalMarkdownCodeComposition.test.tspnpm exec vitest run scripts/__tests__/unit/build.test.tspnpm run flowpnpm run tscIssue links
Fixes #5381
Related to #4550 #5424 #6575