What is lighthouse.mdx?
Lighthouse.mdx is a file format that combines two technologies: Lighthouse (Google’s website auditing tool) and MDX (a way to write JSX in Markdown files). It’s essentially a report generated by Google Lighthouse that’s saved in a special Markdown format which can include interactive React components. This allows developers to create web performance reports that are both readable like regular documents and interactive like web applications.
Let's break it down
Lighthouse is Google’s open-source tool that analyzes web pages and generates reports on performance, accessibility, SEO, and best practices. MDX stands for Markdown + JSX, which means you can write regular Markdown text but also embed React components directly in the file. When combined as lighthouse.mdx, this creates a report format that can display static audit information in Markdown while also allowing dynamic, interactive elements like charts, graphs, or expandable sections using React components.
Why does it matter?
This format matters because it bridges the gap between static documentation and interactive web applications. Traditional Lighthouse reports are HTML files that can be viewed in browsers, but lighthouse.mdx files can be integrated directly into documentation sites, blogs, or developer portals. This makes it easier for teams to share performance insights in a more engaging way, combining the simplicity of Markdown with the power of React for data visualization and interactive elements.
Where is it used?
Lighthouse.mdx files are primarily used in developer documentation systems, especially those built with tools like Next.js, Gatsby, or other React-based static site generators. They’re common in technical blogs, company knowledge bases, and performance monitoring dashboards. Many development teams use them to create living documentation that shows current website performance metrics, and they’re often found in design system documentation or frontend team internal tools.
Good things about it
The format allows for rich, interactive reports that are still easy to read and write like plain text. It enables developers to create custom visualizations for performance data, add interactive filters or sorting to audit results, and integrate reports seamlessly into existing documentation workflows. The combination makes complex performance data more accessible and engaging, and since it’s based on Markdown, it’s version-control friendly and can be easily edited by non-technical team members.
Not-so-good things
The format requires knowledge of both Markdown and React, which can be a barrier for some users. It’s not natively supported by all documentation tools, so specific setup is needed to render lighthouse.mdx files properly. File sizes can become larger than traditional Markdown due to embedded components and data. Additionally, the interactive elements may not work in all environments, and there’s a learning curve for teams unfamiliar with MDX syntax and React component integration.