Skip to content

Update all MDX usage to v3 #10106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jinjiang wants to merge 13 commits into
base: master
Choose a base branch
from
+26,557 −38,813
Open

Update all MDX usage to v3 #10106

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
e530934
chore: update envs to remove mdx v1
Jinjiang Dec 3, 2025
a443eab
chore: update mdx-loader and mdx-transpiler into mdx v3
Jinjiang Dec 3, 2025
8aca136
chore: update env cache key in circleci config
Jinjiang Dec 3, 2025
65fbf7c
chore: update @apollo/client to fix type conflicts
Jinjiang Dec 3, 2025
6e6ded9
chore: debug graphql version conflicts
Jinjiang Dec 4, 2025
c059a51
chore: fix graphql version conflicts
Jinjiang Dec 4, 2025
5db3ca6
chore: debug bit ci pr
Jinjiang Dec 4, 2025
ca366ed
chore: fix react/react type error
Jinjiang Dec 4, 2025
1fe7e0b
chore: fix react/react type error
Jinjiang Dec 5, 2025
891eff5
chore: debug bit ci pr
Jinjiang Dec 5, 2025
59c7ef8
chore: debug bit ci pr
Jinjiang Dec 5, 2025
fcfb356
chore: debug bit ci pr
Jinjiang Dec 5, 2025
cde2250
fix(bit): handle URL objects in filesystem read debug output
davidfirst Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,040 changes: 832 additions & 208 deletions .bitmap
View file
Open in desktop

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions .circleci/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,7 @@ commands:
- restore_cache:
key: bitsrc-registry10
- restore_cache:
key: core-aspect-env-v0.0.80-v1
key: core-aspect-env-v0.1.0-v1
- run: npm view @teambit/bit version > ./version.txt
- restore_cache:
key: v3-linux-bvm-folder-{{ checksum "version.txt" }}
Expand Down Expand Up @@ -451,7 +451,7 @@ commands:
- restore_cache:
key: bitsrc-registry10
- restore_cache:
key: core-aspect-env-v0.0.80-v1
key: core-aspect-env-v0.1.0-v1
- run: npm view @teambit/bit version > ./version.txt
- restore_cache:
key: v3-linux-bvm-folder-{{ checksum "version.txt" }}
Expand Down Expand Up @@ -557,7 +557,7 @@ jobs:
name: bbit install
command: cd bit && bbit install
- save_cache:
key: core-aspect-env-v0.0.80-v1
key: core-aspect-env-v0.1.0-v1
paths:
- /home/circleci/Library/Caches/Bit/capsules/caec9a107
# - run: cd bit && bbit compile
Expand Down Expand Up @@ -612,7 +612,7 @@ jobs:
- restore_cache:
key: bitsrc-registry10
- restore_cache:
key: core-aspect-env-v0.0.80-v1
key: core-aspect-env-v0.1.0-v1
- run:
name: 'check circular dependencies'
command: 'cd bit && ./scripts/circular-deps-check/ci-check.sh'
Expand Down
6 changes: 3 additions & 3 deletions components/legacy/e2e-helper/excluded-fixtures/workspace-with-tsconfig-issue/workspace.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,9 @@
"packageManager": "teambit.dependencies/pnpm",
"policy": {
"dependencies": {
"@teambit/mdx.ui.mdx-scope-context": "1.0.0",
"@teambit/react.react-env": "1.0.77",
"@teambit/typescript.typescript-compiler": "2.0.38"
"@teambit/mdx.ui.mdx-scope-context": "1.0.7",
"@teambit/react.react-env": "1.1.0",
"@teambit/typescript.typescript-compiler": "2.0.64"
},
"peerDependencies": {}
},
Expand Down
44,031 changes: 14,962 additions & 29,069 deletions pnpm-lock.yaml
View file
Open in desktop

Large diffs are not rendered by default.

11 changes: 4 additions & 7 deletions scopes/mdx/mdx/mdx.compiler.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@ import { join } from 'path';
import { outputFileSync } from 'fs-extra';
import type { Compiler, TranspileFileOutput, TranspileFileParams } from '@teambit/compiler';
import type { BuiltTaskResult, BuildContext } from '@teambit/builder';
import { compileSync as mdxCompileSync } from '@teambit/mdx.compilers.mdx-transpiler';
import minimatch from 'minimatch';
import { transpileFileContent as babelTranspileFileContent } from '@teambit/compilation.modules.babel-compiler';
import type { TransformOptions } from '@babel/core';
import { compileSync as mdxCompileSync } from '@mdx-js/mdx';
import { basicMdxOptions } from '@teambit/mdx.modules.mdx-v3-options';

export type MDXCompilerOpts = {
ignoredExtensions?: string[];
Expand Down Expand Up @@ -33,14 +34,10 @@ export class MDXCompiler implements Compiler {
}

transpileFile(fileContent: string, options: TranspileFileParams): TranspileFileOutput {
const afterMdxCompile = mdxCompileSync(fileContent, {
filepath: options.filePath,
// this compiler is not indented to compile according to the bit flavour.
bitFlavour: false,
});
const afterMdxCompile = mdxCompileSync(fileContent, basicMdxOptions);
const filePathAfterMdxCompile = this.replaceFileExtToJs(options.filePath);
const afterBabelCompile = babelTranspileFileContent(
afterMdxCompile.contents,
afterMdxCompile.toString(),
Comment on lines +37 to +40
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MDX v3 compileSync returns a VFile object, not a plain object with a contents property. You should call .toString() method on the result to get the compiled output. However, it appears this is already being done correctly on line 40. Please verify that basicMdxOptions is properly configured for the expected output format.

Copilot uses AI. Check for mistakes.
{
rootDir: options.componentDir,
filePath: filePathAfterMdxCompile,
Expand Down
24 changes: 21 additions & 3 deletions scopes/mdx/mdx/mdx.detector.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
import type { DependencyDetector, FileContext } from '@teambit/dependency-resolver';
import { compileSync } from '@teambit/mdx.compilers.mdx-transpiler';
import { compileSync } from '@mdx-js/mdx';
import { mdxOptions } from '@teambit/mdx.modules.mdx-v3-options';

type ImportSpecifier = {
/**
* relative/absolute or module name. e.g. the `y` in the example of `import x from 'y';`
*/
fromModule: string;

/**
* is default import (e.g. `import x from 'y';`)
*/
isDefault?: boolean;

/**
* the name used to identify the module, e.g. the `x` in the example of `import x from 'y';`
*/
identifier?: string;
};

Comment on lines +4 to 21
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ImportSpecifier type is duplicated from what was likely exported by the old MDX transpiler. Consider importing this type from a shared location or the MDX package if available, rather than redefining it locally. This will reduce maintenance burden and potential drift from the canonical definition.

Suggested change
type ImportSpecifier = {
/**
* relative/absolute or module name. e.g. the `y` in the example of `import x from 'y';`
*/
fromModule: string;
/**
* is default import (e.g. `import x from 'y';`)
*/
isDefault?: boolean;
/**
* the name used to identify the module, e.g. the `x` in the example of `import x from 'y';`
*/
identifier?: string;
};
import type { ImportSpecifier } from '@mdx-js/mdx';

Copilot uses AI. Check for mistakes.
export class MDXDependencyDetector implements DependencyDetector {
constructor(private supportedExtensions: string[]) {}
Expand All @@ -9,8 +27,8 @@ export class MDXDependencyDetector implements DependencyDetector {
}

detect(source: string): string[] {
const output = compileSync(source);
const imports = output.getImportSpecifiers();
const output = compileSync(source, mdxOptions);
const imports = output.data.imports as ImportSpecifier[];
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to the doc-reader, accessing output.data.imports without checking if output.data exists could cause runtime errors. Add a null check: const imports = output.data?.imports as ImportSpecifier[] || []; to handle cases where the data property might be undefined.

Suggested change
const imports = output.data.imports as ImportSpecifier[];
const imports = output.data?.imports as ImportSpecifier[] || [];

Copilot uses AI. Check for mistakes.
if (!imports) return [];
Comment on lines +31 to 32
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In MDX v3, the compileSync function returns a VFile object which needs to be converted to a string using .toString() or accessed via .value property. The data.imports property may not exist unless specific plugins are configured to populate it. The expected structure for imports in MDX v3 is different from v1, and without proper plugin configuration, this will likely fail at runtime.

Suggested change
const imports = output.data.imports as ImportSpecifier[];
if (!imports) return [];
const imports = Array.isArray(output.data?.imports) ? output.data.imports as ImportSpecifier[] : [];
if (!imports.length) return [];

Copilot uses AI. Check for mistakes.
const files: string[] = imports.map((importSpec) => {
return importSpec.fromModule;
Expand Down
7 changes: 4 additions & 3 deletions scopes/mdx/mdx/mdx.doc-reader.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
import type { DocReader } from '@teambit/docs';
import { Doc } from '@teambit/docs';
import { compile } from '@teambit/mdx.compilers.mdx-transpiler';
import { compileSync } from '@mdx-js/mdx';
import { mdxOptions } from '@teambit/mdx.modules.mdx-v3-options';

export class MDXDocReader implements DocReader {
constructor(private extensions: string[]) {}

async read(path: string, contents: Buffer) {
const output = await compile(contents.toString('utf-8'), { filepath: path });
const metadata = output.getMetadata();
const output = compileSync(contents.toString('utf-8'), mdxOptions);
const metadata = output.data.frontmatter as any;
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code accesses output.data.frontmatter without checking if output.data exists first. MDX v3's compileSync may not always populate the data property, which could lead to a runtime error. Consider adding a null check: const metadata = output.data?.frontmatter as any || {};

Suggested change
const metadata = output.data.frontmatter as any;
const metadata = output.data?.frontmatter as any || {};

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MDX compilation result is cast to as any when accessing the frontmatter data. This loses type safety for the metadata extraction.

Consider defining a proper type interface for the MDX compilation output data structure instead of using as any.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In MDX v3, the compileSync function returns a VFile object, not a plain object with a data.frontmatter property. The frontmatter is typically extracted through remark plugins like remark-frontmatter and remark-mdx-frontmatter. Without proper plugin configuration in mdxOptions, accessing output.data.frontmatter may result in undefined at runtime, breaking the metadata extraction.

Suggested change
const metadata = output.data.frontmatter as any;
// Ensure mdxOptions includes remark-frontmatter and remark-mdx-frontmatter plugins for frontmatter extraction.
const metadata = (output.data && output.data.frontmatter) ? output.data.frontmatter : {};

Copilot uses AI. Check for mistakes.

const doc = Doc.from(path, metadata);
return doc;
Expand Down
12 changes: 9 additions & 3 deletions scopes/react/react/webpack/webpack.config.base.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,10 @@ import { postCssConfig } from './postcss.config';
// TODO: remove it once we can set policy from component to component then set it via the component.json
import '@teambit/react.babel.bit-react-transformer';
// Make sure the mdx-loader is a dependency
import '@teambit/mdx.modules.mdx-loader';

// eslint-disable-next-line import/no-unresolved
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The /* eslint-disable import/no-unresolved */ comment suggests there's an unresolved import issue with @mdx-js/loader. This typically indicates that the package is not properly installed or the types are not available. This should be resolved rather than suppressed, as it may cause issues in development and could indicate a missing dependency.

Suggested change
// eslint-disable-next-line import/no-unresolved

Copilot uses AI. Check for mistakes.
import '@mdx-js/loader';
import '@teambit/mdx.modules.mdx-pre-loader';
import { mdxOptions } from '@teambit/mdx.modules.mdx-v3-options';
const styleLoaderPath = require.resolve('style-loader');

const moduleFileExtensions = [
Expand Down Expand Up @@ -157,7 +159,11 @@ export default function (isEnvProduction = false): Configuration {
},
},
{
loader: require.resolve('@teambit/mdx.modules.mdx-loader'),
loader: require.resolve('@mdx-js/loader'),
options: mdxOptions,
},
{
loader: require.resolve('@teambit/mdx.modules.mdx-pre-loader'),
},
Comment on lines +162 to 167
Copy link

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect loader order for MDX processing

Webpack loaders execute from bottom to top in the use array. The current order has:

  1. @mdx-js/loader (executed second)
  2. @teambit/mdx.modules.mdx-pre-loader (executed first)

This means the pre-loader runs before the main MDX loader, but based on the naming convention, a "pre-loader" should process the file before it's passed to the main loader.

If this is intentional and the pre-loader should run first, consider renaming it to "mdx-post-loader" to clarify the execution order. Otherwise, reverse the order:

{
  loader: require.resolve('@teambit/mdx.modules.mdx-pre-loader'),
},
{
  loader: require.resolve('@mdx-js/loader'),
  options: mdxOptions,
},
Suggested change
loader: require.resolve('@mdx-js/loader'),
options: mdxOptions,
},
{
loader: require.resolve('@teambit/mdx.modules.mdx-pre-loader'),
},
loader: require.resolve('@teambit/mdx.modules.mdx-pre-loader'),
},
{
loader: require.resolve('@mdx-js/loader'),
options: mdxOptions,
},

Copilot uses AI. Check for mistakes.
],
},
Expand Down
7 changes: 6 additions & 1 deletion scopes/react/react/webpack/webpack.config.component.dev.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { ComponentID } from '@teambit/component-id';
// TODO: remove it once we can set policy from component to component then set it via the component.json
import '@teambit/react.babel.bit-react-transformer';
import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin';
import { mdxOptions } from '@teambit/mdx.modules.mdx-v3-options';

const matchNothingRegex = 'a^';

Expand Down Expand Up @@ -71,7 +72,11 @@ export default function (workDir: string, envId: string): Configuration {
},
},
{
loader: require.resolve('@teambit/mdx.modules.mdx-loader'),
loader: require.resolve('@mdx-js/loader'),
options: mdxOptions,
},
{
loader: require.resolve('@teambit/mdx.modules.mdx-pre-loader'),
},
Comment on lines 74 to 80
Copy link

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect loader order for MDX processing

Webpack loaders execute from bottom to top in the use array. The current order has:

  1. @mdx-js/loader (executed second)
  2. @teambit/mdx.modules.mdx-pre-loader (executed first)

This means the pre-loader runs before the main MDX loader, but based on the naming convention, a "pre-loader" should process the file before it's passed to the main loader.

If this is intentional and the pre-loader should run first, consider renaming it to "mdx-post-loader" to clarify the execution order. Otherwise, reverse the order:

{
  loader: require.resolve('@teambit/mdx.modules.mdx-pre-loader'),
},
{
  loader: require.resolve('@mdx-js/loader'),
  options: mdxOptions,
},

Copilot uses AI. Check for mistakes.
],
},
Expand Down
1 change: 0 additions & 1 deletion scripts/find-unused-packages.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,6 @@ const whitelist = [
'npm', // needed for e2e tests
'cross-env', // needed for e2e tests on Windows
'@typescript-eslint/typescript-estree', // required for @typescript-eslint/parser in .eslintrc.js
'@mdx-js/mdx', // required for @mdx-js/react in mdx files - maybe should be added to envs (like we have in env.jsonc)
// then we can remove it from here
'mocha-multi-reporters',
];
Expand Down
13 changes: 9 additions & 4 deletions workspace.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
"teambit.dependencies/dependency-resolver": {
"policy": {
"dependencies": {
"@apollo/client": "^3.6.0",
"@babel/core": "7.28.3",
"@babel/plugin-proposal-decorators": "7.28.0",
"@babel/plugin-transform-class-properties": "7.27.1",
Expand All @@ -32,7 +33,8 @@
"@graphql-tools/schema": "^10.0.0",
"@jest/test-result": "29.3.1",
"@lydell/node-pty": "^1.0.0",
"@mdx-js/mdx": "1.6.21",
"@mdx-js/loader": "^3.1.1",
"@mdx-js/mdx": "^3.1.1",
"@mdx-js/react": "1.6.22",
Copy link

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The @mdx-js/react package version is still at 1.6.22 (MDX v1), which is inconsistent with the MDX v3 upgrade. This package should be updated to a v3-compatible version (e.g., ^3.1.1) to ensure compatibility with @mdx-js/mdx and @mdx-js/loader which are now at v3.

Suggested change
"@mdx-js/react": "1.6.22",
"@mdx-js/react": "^3.1.1",

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent MDX package versions

The @mdx-js/mdx and @mdx-js/loader packages have been updated to v3 (^3.1.1), but @mdx-js/react remains at v1 (1.6.22).

For MDX v3, @mdx-js/react should also be updated to v3 to ensure compatibility. The v1 version may not work correctly with MDX v3 compiled output.

Suggested update:

"@mdx-js/react": "^3.1.1"
Suggested change
"@mdx-js/react": "1.6.22",
"@mdx-js/react": "^3.1.1",

Copilot uses AI. Check for mistakes.
"@modelcontextprotocol/sdk": "^1.22.0",
"@monaco-editor/react": "4.4.6",
Expand Down Expand Up @@ -276,9 +278,9 @@
"@teambit/lanes.ui.menus.lanes-overview-menu": "^0.0.11",
"@teambit/lanes.ui.navigation.lane-switcher": "^0.0.235",
"@teambit/legacy-bit-id": "^1.1.3",
"@teambit/mdx.compilers.mdx-transpiler": "^1.0.11",
"@teambit/mdx.generator.mdx-templates": "^1.0.14",
"@teambit/mdx.modules.mdx-loader": "^1.0.15",
"@teambit/mdx.modules.mdx-pre-loader": "^0.0.1",
"@teambit/mdx.modules.mdx-v3-options": "^0.0.2",
Comment on lines 280 to +283
Copy link

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The removal of @teambit/mdx.compilers.mdx-transpiler from the dependency policy should be verified. Since this component is still imported and used in other files (though now replaced with @mdx-js/mdx's compileSync), ensure that all references to this package have been properly removed or updated throughout the codebase to avoid unused dependencies or broken imports.

Copilot uses AI. Check for mistakes.
"@teambit/mdx.ui.mdx-layout": "^1.0.12",
"@teambit/mdx.ui.mdx-scope-context": "^1.0.7",
"@teambit/node.deps-detectors.detective-es6": "~0.0.6",
Expand All @@ -289,13 +291,15 @@
"@teambit/pkg.package-json.validator": "0.0.1",
"@teambit/preview.cli.dev-server-events-listener": "^0.0.1",
"@teambit/preview.modules.preview-modules": "^1.0.3",
"@teambit/preview.react-preview": "^1.0.102",
"@teambit/react.content.react-overview": "1.96.5",
"@teambit/react.instructions.react.adding-compositions": "0.0.7",
"@teambit/react.instructions.react.adding-tests": "0.0.6",
"@teambit/react.jest.react-jest": "^1.0.37",
"@teambit/react.react-env": "^1.1.0",
"@teambit/react.rendering.ssr": "^1.0.3",
"@teambit/react.ui.component-highlighter": "0.2.5",
"@teambit/react.webpack.react-webpack": "^1.0.50",
"@teambit/react.webpack.react-webpack": "^1.0.54",
"@teambit/scope.content.scope-overview": "1.96.8",
"@teambit/scope.ui.empty-scope": "^0.0.510",
"@teambit/scope.ui.hooks.use-scope": "^0.0.456",
Expand Down Expand Up @@ -490,6 +494,7 @@
"globby": "11.0.1",
"graceful-fs": "4.2.10",
"graphlib": "2.1.8",
"graphql": "15.8.0",
"graphql-disable-introspection": "^1.2.0",
"graphql-request": "6.1.0",
"graphql-subscriptions": "1.2.0",
Expand Down