Installation

While the easiest way to start a new project with Prose UI is by cloning one of the templates, we provide the instructions below to help you set up a brand-new project with Prose UI on your own.

Here's how to create and configure a Next.js project with next/mdx and Prose UI.

Note

Note that this is a very basic setup. For an example that uses an MDX bundler, content collections, and a separate MDX content folder, refer to our docs starter template.

Create a new project and install dependencies

Start by creating a Next.js project, choosing defaults in the prompts.

npx create-next-app@latest

Note that if you're using @next/mdx, as we do in this example setup, you have to make sure your project is using Webpack and not Turbopack.

Next.js 16 comes with Turbopack by default, so you'll need to disable it explicitly when creating the project with the npx command above.

Enter your project’s folder and install the dependencies for rendering MDX and Prose UI. We're using pnpm, but feel free to use your preferred package manager.

pnpm add @prose-ui/core @prose-ui/next @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

Set up MDX components

Create an mdx-components.tsx file in the root of your project. This file will be used to override the default components used by MDX.

import { mdxComponents } from "@prose-ui/next";
import type { MDXComponents } from "mdx/types";

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
    ...mdxComponents,
  };
}

Set up MDX rendering

Configure your project to use MDX with Prose UI by modifying your next.config.ts in the following way:

import createMDX from "@next/mdx";
import { remarkPlugins } from "@prose-ui/core";

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
};

const withMDX = createMDX({
  options: {
    remarkPlugins: remarkPlugins(),
  },
});

export default withMDX(nextConfig);

Adjust the layout

Go to your app/layout.tsx and replace the content it returns with the code below to ensure that your pages have the correct fonts and styles applied.

<html lang="en" className={`dark ${geistSans.variable} ${geistMono.variable}`}>
  <body className="prose-ui antialiased">
    <div className="mx-auto max-w-3xl px-8">{children}</div>
  </body>
</html>

Add Prose UI CSS styles

Next, go to your src/app/globals.css file and import Prose UI styles at the top:

@import "@prose-ui/next/prose-ui.css";
@import "@prose-ui/next/katex.min.css";

The katex.min.css import is required only if you use math formulas.

Optional step: if you want to override fonts in Prose UI, update the variables for the base, heading, and mono fonts in your globals.css. For more details on styling, refer to the styling page.

:root {
  --p-font-family: var(--font-geist-sans);
  --p-font-family-heading: var(--font-geist-sans);
  --p-font-family-mono: var(--font-geist-mono);
}

Add MDX content

Rename src/app/page.tsx to src/app/page.mdx and replace the content with your Markdown/MDX. For example:

# Hello, world!

The Viking landers, part of NASA's [Viking program](https://en.wikipedia.org/wiki/Viking_program), were the first U.S. missions to successfully land on Mars and transmit images and scientific data back to Earth in 1976.

<Frame align="center">
  <Image
    src="https://nssdc.gsfc.nasa.gov/image/spacecraft/viking_lander.jpg"
    alt="Viking lander"
  />
  <Caption>Viking lander</Caption>
</Frame>

That's it! Run pnpm dev and open your project in the browser.