Receiving a "docs is not iterable" error / Map file not being generated

[danpiths]

Hey all!
I have been facing an issue where i am not able to render anything on the /docs route due to a docs is not iterable error. I would appreciate any help here 🙇🏻

I upgraded fumadocs/mdx from 8.2.34 to 10.0.2. I migrated the code according to the docs by

• shifting mdx-components.tsx to MDX's components prop
• shifted configuration from createMDX to defineConfig/defineDocs
• created a source.config.ts file
• added a step to run fumadocs-mdx everytime before i start a dev server (it does not automatically create the .source folder on next dev, i have to run fumadocs-mdx for the generation)
  • ℹ️ i don't know if this should be the normal behaviour but the fumadocs-mdx generates the following file structure; wherein i have to rename source.config.mjs to index.mjs as the import from .source does not work directly.

apps/maxim/.source
├── index.d.ts
└── source.config.mjs

error that occurs

 ⨯ TypeError: docs is not iterable
    at resolveFiles (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/vendor-chunks/fumadocs-mdx.js:230:23)
    at Object.files (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/vendor-chunks/fumadocs-mdx.js:282:25)
    at createOutput (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/vendor-chunks/fumadocs-core.js:2114:49)
    at loader (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/vendor-chunks/fumadocs-core.js:2100:10)
    at /Users/dan/code/maximhq/maxim/apps/maxim/.next/server/app/workspace/[workspaceId]/docs/[[...slug]]/page.js:22021:76
    at Function.__webpack_require__.a (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/webpack-runtime.js:100:13)
    at Module.(rsc)/./source.ts (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/app/workspace/[workspaceId]/docs/[[...slug]]/page.js:22003:21)
    at __webpack_require__ (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/webpack-runtime.js:25:43)
    at /Users/dan/code/maximhq/maxim/apps/maxim/.next/server/app/workspace/[workspaceId]/docs/[[...slug]]/page.js:22334:65
    at Function.__webpack_require__.a (/Users/dan/code/maximhq/maxim/apps/maxim/.next/server/webpack-runtime.js:100:13) {
  type: 'TypeError',
  page: '/workspace/clyduotxl0000jcf8w7bltwq6/docs'
}

source.config.ts

import { defineConfig, defineDocs } from "fumadocs-mdx/config";
import { remarkInstall } from "fumadocs-docgen";

export const { docs, meta } = defineDocs({
	docs: {
		dir: process.env.NODE_ENV === "development" ? "./apps/maxim/docs" : "./docs",
		files: ["./**/*.{md,mdx,json}"],
	},
	meta: {
		dir: process.env.NODE_ENV === "development" ? "./apps/maxim/docs" : "./docs",
		files: ["./**/*.{md,mdx,json}"],
	},
});
export default defineConfig({
	mdxOptions: {
		// @ts-ignore
		remarkPlugins: [[remarkInstall, { persist: { id: "documentation-package-manager" } }]],
	},
});

docs object (logged from the generated .source)

{
  _doc: 'collections',
  type: 'doc',
  dir: './apps/maxim/docs',
  schema: ZodObject {
    spa: [Function: bound safeParseAsync] AsyncFunction,
    _def: {
      shape: [Function: shape],
      unknownKeys: 'strip',
      catchall: [ZodNever],
      typeName: 'ZodObject'
    },
    parse: [Function: bound parse],
    safeParse: [Function: bound safeParse],
    parseAsync: [Function: bound parseAsync] AsyncFunction,
    safeParseAsync: [Function: bound safeParseAsync] AsyncFunction,
    refine: [Function: bound refine],
    refinement: [Function: bound refinement],
    superRefine: [Function: bound superRefine],
    optional: [Function: bound optional],
    nullable: [Function: bound nullable],
    nullish: [Function: bound nullish],
    array: [Function: bound array],
    promise: [Function: bound promise],
    or: [Function: bound or],
    and: [Function: bound and],
    transform: [Function: bound transform],
    brand: [Function: bound brand],
    default: [Function: bound default],
    catch: [Function: bound catch],
    describe: [Function: bound describe],
    pipe: [Function: bound pipe],
    readonly: [Function: bound readonly],
    isNullable: [Function: bound isNullable],
    isOptional: [Function: bound isOptional],
    _cached: null,
    nonstrict: [Function: passthrough],
    augment: [Function: extend]
  },
  files: [ './**/*.{md,mdx,json}' ]
}

meta object (logged from the generated .source)

{
  _doc: 'collections',
  type: 'meta',
  dir: './apps/maxim/docs',
  schema: ZodObject {
    spa: [Function: bound safeParseAsync] AsyncFunction,
    _def: {
      shape: [Function: shape],
      unknownKeys: 'strip',
      catchall: [ZodNever],
      typeName: 'ZodObject'
    },
    parse: [Function: bound parse],
    safeParse: [Function: bound safeParse],
    parseAsync: [Function: bound parseAsync] AsyncFunction,
    safeParseAsync: [Function: bound safeParseAsync] AsyncFunction,
    refine: [Function: bound refine],
    refinement: [Function: bound refinement],
    superRefine: [Function: bound superRefine],
    optional: [Function: bound optional],
    nullable: [Function: bound nullable],
    nullish: [Function: bound nullish],
    array: [Function: bound array],
    promise: [Function: bound promise],
    or: [Function: bound or],
    and: [Function: bound and],
    transform: [Function: bound transform],
    brand: [Function: bound brand],
    default: [Function: bound default],
    catch: [Function: bound catch],
    describe: [Function: bound describe],
    pipe: [Function: bound pipe],
    readonly: [Function: bound readonly],
    isNullable: [Function: bound isNullable],
    isOptional: [Function: bound isOptional],
    _cached: null,
    nonstrict: [Function: passthrough],
    augment: [Function: extend]
  },
  files: [ './**/*.{md,mdx,json}' ]
}

[fuma-nama]

Could I see your next config?

[danpiths]

got it, will look into the issue more. i'm mostly certain that your guess is right, since i am using a custom server and don't see any next.js specific logs in my terminal anyway. will update the thread as soon as i am able to get to the root of it.
thank you for all the help 🙌🏻

[danpiths]

hey sorry to bring this up again.
i was looking into the process.argv thing and realised that we currently are using a custom server implementation of next.js (this uses next.js essentially as a library), thus we use node to run our server.ts file which in turn runs the next requestHandler through a server created from the http library and thus next dev would not be available in the process.argv

i would point out though that in order to have a production build and serve it we execute next build command which is able to generate the proper .source folder but the dev experience suffers still.

thank you for any and all the help you can provide here 🙇🏻

[fuma-nama]

Inspired by some other projects like https://velite.js.org, we start the server when:

import path from 'node:path';
import type { NextConfig } from 'next';
import type { Configuration } from 'webpack';
import { findConfigFile } from '@/config/load';
import { start } from '@/map';
import { type Options as MDXLoaderOptions } from '../loader-mdx';

export interface CreateMDXOptions {
  /**
   * Path to source configuration file
   */
  configPath?: string;
}

const outDir = path.resolve('.source');
const defaultPageExtensions = ['mdx', 'md', 'jsx', 'js', 'tsx', 'ts'];

export function createMDX({
  configPath = findConfigFile(),
}: CreateMDXOptions = {}) {
  // Next.js performs multiple iteration on the `next.config.js` file
  // the first time contains the original arguments of `next dev`
  // we only execute on the first iteration
  const isDev = process.argv.includes('dev');
  const isBuild = process.argv.includes('build');

  if (isDev || isBuild) {
    void start(isDev, configPath, outDir);
  }

(see the start function).
I can export that start function later, which allows you to start the server manually, but you have to pay extra attention when calling the start APi as it's basically an internal stuff.

[danpiths]

ohh got it so for now i manually check for dev environment using process.env.NODE_ENV === "development" and then push to process.argv the value "dev" inside the next.config.mjs file before calling createMDX. i didn't have an idea where the check was happening and was therefore not able to make out where i needed to do this.

const isEnvDev = process.env.NODE_ENV === "development";
isEnvDev && process.argv.push("dev")
const withMDX = createMDX();

a hacky workaround but it works so yay! 🎉

thank you again for all the help and for all the efforts put into maintaining this project 🙌🏻 . appreciate it a lot :)