Inflearn brand logo image

인프런 커뮤니티 질문&답변

포팃님의 프로필 이미지
포팃

작성한 질문수

Next.js 완벽 마스터 (v15): 노션 기반 개발자 블로그 만들기 (with 커서AI)

Next.js Markdown MDX 시작하기 (MDX 렌더링 오류시 강의 설명란 참고하세요!)

Markdown MDX 관련 질문입니다.

해결된 질문

작성

·

163

0

에러화면

image.png
  • /mdx-page 렌더링이 안됩니다...

 

작업 순서

  • 패키지 설치

    npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx
  • next.config.ts

    import type { NextConfig } from 'next';
    import createMDX from '@next/mdx';
    
    const nextConfig: NextConfig = {
      /* config options here */
      // experimental: {
      //   typedRoutes: true,
      // },
      images: {
        remotePatterns: [
          {
            hostname: 'picsum.photos',
          },
          {
            hostname: 'images.unsplash.com',
          },
          {
            hostname: 'www.notion.so',
          },
          {
            hostname: 'prod-files-secure.s3.us-west-2.amazonaws.com',
          },
        ],
      },
      pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
    };
    
    const withMDX = createMDX({
      // Add markdown plugins here, as desired
    });
    
    // Merge MDX config with Next.js config
    export default withMDX(nextConfig);
    
  • mdx-components.tsx

    import type { MDXComponents } from 'mdx/types';
    
    export function useMDXComponents(components: MDXComponents): MDXComponents {
      return {
        ...components,
      };
    }
  • app/mdx-page/page.mdx

    # Welcome to my MDX page!
    
    This is some **bold** and _italics_ text.
    
    This is a list in markdown:
    
    - One
    - Two
    - Three
    
    Checkout my React component:
  • package.json

    {
      "name": "notion-blog-nextjs",
      "version": "0.1.0",
      "private": true,
      "scripts": {
        "dev": "next dev --turbopack",
        "build": "next build",
        "start": "next start",
        "lint": "next lint",
        "lint:fix": "next lint --fix",
        "format": "prettier --write ."
      },
      "dependencies": {
        "@mdx-js/loader": "^3.1.0",
        "@mdx-js/react": "^3.1.0",
        "@next/mdx": "^15.3.2",
        "@notionhq/client": "^3.0.1",
        "@radix-ui/react-select": "^2.2.4",
        "@radix-ui/react-separator": "^1.1.6",
        "@radix-ui/react-slot": "^1.2.2",
        "@types/mdx": "^2.0.13",
        "class-variance-authority": "^0.7.1",
        "clsx": "^2.1.1",
        "date-fns": "^4.1.0",
        "lucide-react": "^0.507.0",
        "next": "15.2.5",
        "postcss": "^8.5.3",
        "react": "^19.0.0",
        "react-dom": "^19.0.0",
        "react-icons": "^5.5.0",
        "tailwind-merge": "^3.2.0"
      },
      "devDependencies": {
        "@eslint/eslintrc": "^3",
        "@eslint/js": "^9.26.0",
        "@tailwindcss/postcss": "^4.1.5",
        "@types/node": "^20",
        "@types/react": "^19",
        "@types/react-dom": "^19",
        "eslint": "^9",
        "eslint-config-next": "15.2.5",
        "eslint-config-prettier": "^10.1.2",
        "globals": "^16.0.0",
        "prettier": "^3.5.3",
        "prettier-plugin-tailwindcss": "^0.6.11",
        "tailwindcss": "^4.1.5",
        "tw-animate-css": "^1.2.9",
        "typescript": "^5"
      }
    }
    

 

답변 2

1

짐코딩님의 프로필 이미지
짐코딩
지식공유자

안녕하세요! 🙂

Next.js에서 MDX 페이지 에러 트러블슈팅

저도 테스트해 보니 Next.js 프로젝트에서 MDX 페이지가 갑자기 작동하지 않는 현상을 확인할 수 있었습니다. 문제와 해결책에 대해 자세히 설명드리겠습니다.

문제 상황

프로젝트에서 app/mdx-page/page.mdx 파일을 생성하여 MDX 페이지를 구현했습니다. 이전에는 정상적으로 작동했지만, 다시 테스트하니 다음과 같은 오류가 발생했습니다:

Error: An unexpected Turbopack error occurred. Please see the output of next dev for more details.
스크린샷 2025-05-12 오후 2.59.16.png.webp

 

원인 분석

문제의 근본 원인은 의존성 패키지 버전 관리에 있었습니다. package.json 파일을 확인해보면:

...
"@next/mdx": "^15.1.7"
...

여기서 ^ 기호는 semver(시맨틱 버전) 규칙에 따라 "15.1.7 이상, 16.0.0 미만"의 모든 버전을 허용한다는 의미입니다. 문제는 자동으로 업데이트된 버전에서 Turbopack과의 호환성 이슈가 발생했기 때문입니다.

해결 방법

이 문제를 해결하는 두 가지 효과적인 방법이 있습니다:

1. 의존성 버전 고정하기

"@next/mdx": "15.1.7"

^ 기호를 제거하여 정확히 15.1.7 버전을 사용하도록 고정합니다. 이렇게 하면 예기치 않은 버전 업데이트로 인한 호환성 문제를 방지할 수 있습니다.

2. Turbopack 없이 개발 서버 실행하기

npx next dev  # --turbopack 플래그 없이 실행

또는 package.json에 별도 명령어를 추가하여 유연하게 사용할 수 있습니다:

"scripts": {
  "dev": "next dev --turbopack",
  "dev:webpack": "next dev",  // npm run dev:webpack으로 실행
  "build": "next build",
  "start": "next start",
  "lint": "next lint",
  "lint:fix": "next lint --fix",
  "format": "prettier --write ."
}

추가 팁

MDX 테스트 페이지는 임시 용도로만 사용하고, 실제 블로그 상세 페이지는 다른 방식으로 구현할 예정입니다. 그렇기 때문에 간단히 Turbopack 없이 테스트하는 것이 더 효율적일 수 있습니다.

 

위 해결방법으로 진행하면 아래 처럼 잘 나오는 걸 확인할 수 있습니다 🙂

스크린샷 2025-05-12 오후 2.58.25.png.webp

 

포팃님의 프로필 이미지
포팃
질문자

감사합니다!
Turbopack 없이 실행했더니 작동해서 넘어갔는데 의존성 버전 고정해서 해결하는 방법도 있었네요;;;

자세하게 설명해주셔서 감사합니다^^ 강의 너무 잘 보고 있습니다!ㅎㅎ

0

안녕하세요, 인프런 AI 인턴입니다. 포팃님.

MDX 페이지를 렌더링하려 할 때 발생하는 이슈는 주로 설정이나 패키지 호환성 문제에서 비롯될 수 있습니다. 아래에 몇 가지 주요 원인과 해결 방법을 설명드리겠습니다.

문제 원인 및 해결 방법

  1. Next.js와 Turbopack 문제:

    • Runtime Error와 관련된 메시지를 보면, Turbopack과 관련된 문제가 발생한 것 같습니다. Turbopack은 여전히 실험 기능이기 때문에 문제를 일으킬 수 있습니다. next dev --turbopack 대신 next dev로 다시 시도해보세요.
  2. Dependencies 버전 호환성 확인:

    • reactreact-dom의 버전이 안정 릴리스가 아닌 19.0.0으로 설정되어 있습니다. 현재 안정 버전(2023년 10월 기준)은 18.x.x입니다. 각 패키지가 React 19를 지원하지 않을 수 있습니다. 두 패키지를 18.x.x 버전으로 다운그레이드 해보세요.
   npm install react@18 react-dom@18
  1. 타입 선언 버전 문제:

    • @types/mdx, @types/react, @types/react-dom 등의 타입 패키지 버전이 React 버전과 호환되지 않을 수 있습니다. @types/react@types/react-dom18.x.x 버전으로 맞추는 것이 좋습니다.
  2. 페이지 경로 및 설정 확인:

    • pageExtensionsmd, mdx가 추가되어 있는 것은 올바른 설정입니다. 하지만 app/mdx-page/page.mdx 경로와 파일명이 맞는지, 혹시 오타는 없는지 다시 한 번 확인해 주세요.
  3. Next.js 설정 파일 내 정의 오류 확인:

    • next.config.ts 파일에서 withMDXnextConfig를 올바르게 병합했는지 확인합니다. 만약 MDX 설정이 올바르게 되지 않았다면, 기본적인 next.config.js 설정으로 돌아가 MDX 설정을 무효화한 상태로 테스트 해보는 것도 한 방법입니다.

참고자료 제공

다음 문서를 확인해 보시면 관련 문제의 다른 사례와 더 깊이 있는 설명을 보실 수 있습니다:
- Next.js MDX 설정 관련 공식 가이드
- React와 Next.js의 버전 호환성 문제를 해결하는 방법

저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다.
현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏
추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.

포팃님의 프로필 이미지
포팃

작성한 질문수

질문하기