Skip to content

Commit a2d8395

Browse files
danedendaneden
authoredAug 29, 2020
Add with-mdx-remote example (#16613)
This change adds a new example, `with-mdx-remote`, which leverages [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote) to use MDX files as content for a dynamic route. In addition to the basic functionality, the example adds a note about somewhat advanced usage that allows the use of conditionally-loaded custom MDX components. cc @jescalan
·
@vercel/devlow-bench@0.3.4v9.5.3-canary.26
1 parent 8217597 commit a2d8395

File tree

11 files changed

+357
-0
lines changed

11 files changed

+357
-0
lines changed
 

‎examples/with-mdx-remote/.gitignore

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.js
7+
8+
# testing
9+
/coverage
10+
11+
# next.js
12+
/.next/
13+
/out/
14+
15+
# production
16+
/build
17+
18+
# misc
19+
.DS_Store
20+
*.pem
21+
22+
# debug
23+
npm-debug.log*
24+
yarn-debug.log*
25+
yarn-error.log*
26+
27+
# local env files
28+
.env.local
29+
.env.development.local
30+
.env.test.local
31+
.env.production.local
32+
33+
# vercel
34+
.vercel

‎examples/with-mdx-remote/README.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# MDX Remote Example
2+
3+
This example shows how a simple blog might be built using the [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote) library, which allows mdx content to be loaded via `getStaticProps` or `getServerSideProps`. The mdx content is loaded from a local folder, but it could be loaded from a database or anywhere else.
4+
5+
The example also showcases [next-remote-watch](https://github.com/hashicorp/next-remote-watch), a library that allows next.js to watch files outside the `pages` folder that are not explicitly imported, which enables the mdx content here to trigger a live reload on change.
6+
7+
Since `next-remote-watch` uses undocumented Next.js APIs, it doesn't replace the default `dev` script for this example. To use it, run `npm run dev:watch` or `yarn dev:watch`.
8+
9+
## Deploy your own
10+
11+
Deploy the example using [Vercel](https://vercel.com):
12+
13+
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/import/project?template=https://github.com/vercel/next.js/tree/canary/examples/with-mdx-remote)
14+
15+
## How to use
16+
17+
Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
18+
19+
```bash
20+
npx create-next-app --example with-mdx-remote with-mdx-remote-app
21+
# or
22+
yarn create next-app --example with-mdx-remote with-mdx-remote-app
23+
```
24+
25+
Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
26+
27+
## Notes
28+
29+
### Conditional custom components
30+
31+
When using `next-mdx-remote`, you can pass custom components to the MDX renderer. However, some pages/MDX files might use components that are used infrequently, or only on a single page. To avoid loading those components on every MDX page, you can use `next/dynamic` to conditionally load them.
32+
33+
For example, here's how you can change `getStaticProps` to conditionally add certain components:
34+
35+
```js
36+
import dynamic from 'next/dynamic'
37+
38+
// ...
39+
40+
export async function getStaticProps() {
41+
const { content, data } = matter(source)
42+
43+
const components = {
44+
...defaultComponents,
45+
SomeHeavyComponent: /<SomeHeavyComponent/.test(content)
46+
? dynamic(() => import('SomeHeavyComponent'))
47+
: null,
48+
}
49+
50+
const mdxSource = await renderToString(content, { components })
51+
}
52+
```
53+
54+
If you do this, you'll also need to check in the page render function which components need to be dynamically loaded. You can pass a list of component names via `getStaticProps` to accomplish this.

‎examples/with-mdx-remote/components/CustomLink.js

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import Link from 'next/link'
2+
3+
export default function CustomLink({ as, href, ...otherProps }) {
4+
return (
5+
<>
6+
<Link as={as} href={href}>
7+
<a {...otherProps} />
8+
</Link>
9+
<style jsx>{`
10+
a {
11+
color: tomato;
12+
}
13+
`}</style>
14+
</>
15+
)
16+
}

‎examples/with-mdx-remote/components/Layout.js

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
export default function Layout({ children }) {
2+
return (
3+
<>
4+
<div className="wrapper">{children}</div>
5+
<style jsx>{`
6+
.wrapper {
7+
max-width: 36rem;
8+
margin: 0 auto;
9+
padding: 1.5rem;
10+
}
11+
`}</style>
12+
<style jsx global>{`
13+
* {
14+
margin: 0;
15+
padding: 0;
16+
}
17+
18+
:root {
19+
--site-color: royalblue;
20+
--divider-color: rgba(0, 0, 0, 0.4);
21+
}
22+
23+
html {
24+
font: 100%/1.5 system-ui;
25+
}
26+
27+
a {
28+
color: inherit;
29+
text-decoration-color: var(--divider-color);
30+
text-decoration-thickness: 2px;
31+
}
32+
33+
a:hover {
34+
color: var(--site-color);
35+
text-decoration-color: currentcolor;
36+
}
37+
38+
h1,
39+
p {
40+
margin-bottom: 1.5rem;
41+
}
42+
43+
code {
44+
font-family: 'Menlo';
45+
}
46+
`}</style>
47+
</>
48+
)
49+
}

‎examples/with-mdx-remote/components/TestComponent.js

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
export default function TestComponent({ name = 'world' }) {
2+
return (
3+
<>
4+
<div>Hello, {name}!</div>
5+
<style jsx>{`
6+
div {
7+
background-color: #111;
8+
border-radius: 0.5em;
9+
color: #fff;
10+
margin-bottom: 1.5em;
11+
padding: 0.5em 0.75em;
12+
}
13+
`}</style>
14+
</>
15+
)
16+
}

‎examples/with-mdx-remote/package.json

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "with-mdx-remote",
3+
"version": "1.0.0",
4+
"scripts": {
5+
"dev": "next",
6+
"dev:watch": "next-remote-watch ./posts",
7+
"build": "next build",
8+
"start": "next start"
9+
},
10+
"dependencies": {
11+
"gray-matter": "^4.0.2",
12+
"next": "latest",
13+
"next-mdx-remote": "^1.0.0",
14+
"next-remote-watch": "0.2.0",
15+
"react": "^16.13.1",
16+
"react-dom": "^16.13.1"
17+
},
18+
"license": "MIT"
19+
}

‎examples/with-mdx-remote/pages/index.js

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import fs from 'fs'
2+
import matter from 'gray-matter'
3+
import Link from 'next/link'
4+
import path from 'path'
5+
import Layout from '../components/Layout'
6+
import { postFilePaths, POSTS_PATH } from '../utils/mdxUtils'
7+
8+
export default function Index({ posts }) {
9+
return (
10+
<Layout>
11+
<h1>Home Page</h1>
12+
<p>
13+
Click the link below to navigate to a page generated by{' '}
14+
<code>next-mdx-remote</code>.
15+
</p>
16+
<ul>
17+
{posts.map((post) => (
18+
<li key={post.filePath}>
19+
<Link
20+
as={`/posts/${post.filePath.replace(/\.mdx?$/, '')}`}
21+
href={`/posts/[slug]`}
22+
>
23+
<a>{post.data.title}</a>
24+
</Link>
25+
</li>
26+
))}
27+
</ul>
28+
</Layout>
29+
)
30+
}
31+
32+
export function getStaticProps() {
33+
const posts = postFilePaths.map((filePath) => {
34+
const source = fs.readFileSync(path.join(POSTS_PATH, filePath))
35+
const { content, data } = matter(source)
36+
37+
return {
38+
content,
39+
data,
40+
filePath,
41+
}
42+
})
43+
44+
return { props: { posts } }
45+
}

‎examples/with-mdx-remote/pages/posts/[slug].js

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
import fs from 'fs'
2+
import matter from 'gray-matter'
3+
import hydrate from 'next-mdx-remote/hydrate'
4+
import renderToString from 'next-mdx-remote/render-to-string'
5+
import dynamic from 'next/dynamic'
6+
import Head from 'next/head'
7+
import Link from 'next/link'
8+
import path from 'path'
9+
import CustomLink from '../../components/CustomLink'
10+
import Layout from '../../components/Layout'
11+
import { postFilePaths, POSTS_PATH } from '../../utils/mdxUtils'
12+
13+
// Custom components/renderers to pass to MDX.
14+
// Since the MDX files aren't loaded by webpack, they have no knowledge of how
15+
// to handle import statements. Instead, you must include components in scope
16+
// here.
17+
const components = {
18+
a: CustomLink,
19+
// It also works with dynamically-imported components, which is especially
20+
// useful for conditionally loading components for certain routes.
21+
// See the notes in README.md for more details.
22+
TestComponent: dynamic(() => import('../../components/TestComponent')),
23+
Head,
24+
}
25+
26+
export default function PostPage({ source, frontMatter }) {
27+
const content = hydrate(source, { components })
28+
return (
29+
<Layout>
30+
<header>
31+
<nav>
32+
<Link href="/">
33+
<a>👈 Go back home</a>
34+
</Link>
35+
</nav>
36+
</header>
37+
<div className="post-header">
38+
<h1>{frontMatter.title}</h1>
39+
{frontMatter.description && (
40+
<p className="description">{frontMatter.description}</p>
41+
)}
42+
</div>
43+
<main>{content}</main>
44+
45+
<style jsx>{`
46+
.post-header h1 {
47+
margin-bottom: 0;
48+
}
49+
50+
.post-header {
51+
margin-bottom: 2rem;
52+
}
53+
.description {
54+
opacity: 0.6;
55+
}
56+
`}</style>
57+
</Layout>
58+
)
59+
}
60+
61+
export const getStaticProps = async ({ params }) => {
62+
const postFilePath = path.join(POSTS_PATH, `${params.slug}.mdx`)
63+
const source = fs.readFileSync(postFilePath)
64+
65+
const { content, data } = matter(source)
66+
67+
const mdxSource = await renderToString(content, {
68+
components,
69+
// Optionally pass remark/rehype plugins
70+
mdxOptions: {
71+
remarkPlugins: [],
72+
rehypePlugins: [],
73+
},
74+
scope: data,
75+
})
76+
77+
return {
78+
props: {
79+
source: mdxSource,
80+
frontMatter: data,
81+
},
82+
}
83+
}
84+
85+
export const getStaticPaths = async () => {
86+
const paths = postFilePaths
87+
// Remove file extensions for page paths
88+
.map((path) => path.replace(/\.mdx?$/, ''))
89+
// Map the path into the static paths object required by Next.js
90+
.map((slug) => ({ params: { slug } }))
91+
92+
return {
93+
paths,
94+
fallback: false,
95+
}
96+
}

‎examples/with-mdx-remote/posts/example-post.mdx

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Example Post
3+
description: This frontmatter description will appear below the title
4+
---
5+
6+
This is an example post, with a [link](https://nextjs.org) and a React component:
7+
8+
<TestComponent name="next-mdx-remote" />
9+
10+
The title and description are pulled from the MDX file and processed using `gray-matter`. Additionally, links are rendered using a custom component passed to `next-mdx-remote`.
11+
12+
Go back [home](/).

‎examples/with-mdx-remote/posts/hello-world.mdx

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Hello World
3+
---
4+
5+
This is an example post. There's another one [here](/posts/example-post).

‎examples/with-mdx-remote/utils/mdxUtils.js

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import fs from 'fs'
2+
import path from 'path'
3+
4+
// POSTS_PATH is useful when you want to get the path to a specific file
5+
export const POSTS_PATH = path.join(process.cwd(), 'posts')
6+
7+
// postFilePaths is the list of all mdx files inside the POSTS_PATH directory
8+
export const postFilePaths = fs
9+
.readdirSync(POSTS_PATH)
10+
// Only include md(x) files
11+
.filter((path) => /\.mdx?$/.test(path))

0 commit comments

Comments
 (0)
Please sign in to comment.