Audit and fix Next.js, Docusaurus, and Fastify build compatibility in monorepo

[Lakes41]

Background

The monorepo mixes three different build systems (Next.js 14, Docusaurus, Fastify) with incompatible or conflicting configurations. Recent build failures in apps/dashboard and deprecation warnings in apps/docs suggest version mismatches, incompatible TypeScript settings, or misconfigured transpilation.

Problem

1. Docusaurus v3 deprecation warnings: The apps/docs build logs show deprecated config options that will break in v4
2. Next.js transpilation: The dashboard may not properly transpile monorepo packages
3. Fastify TypeScript setup: apps/access-api may lack proper TypeScript and ESM support
4. Version inconsistency: Each app may have different Node/TypeScript/pnpm version requirements, not documented

Expected Outcome

• All app build systems are compatible with the monorepo structure
• Deprecation warnings are addressed proactively
• Clear version requirements documented (Node, TypeScript, pnpm)
• CI/CD ensures compatibility across major version changes
• Apps build deterministically and reproducibly

Suggested Implementation

1. Audit versions in each app's package.json:

   • apps/docs: Docusaurus version, React version
   • apps/dashboard: Next.js version, React version
   • apps/access-api: Fastify version, Node.js version
   • apps/discord-bot: Discord.js version

   Create a spreadsheet or VERSIONS.md documenting them.

2. Fix Docusaurus deprecation in apps/docs:

   • Update docusaurus.config.js to migrate siteConfig.onBrokenMarkdownLinks to siteConfig.markdown.hooks.onBrokenMarkdownLinks:

   // apps/docs/docusaurus.config.js
   const config = {
     // ...
     markdown: {
       hooks: {
         onBrokenMarkdownLinks: 'warn',
       },
     },
   };

   • Remove the deprecated onBrokenMarkdownLinks option from the root level

3. Update Next.js configuration in apps/dashboard:

   • Ensure next.config.js transpiles monorepo packages:

   const nextConfig = {
     transpilePackages: ['@guildpass/env', '@guildpass/integration-client'],
   };

   • Set typescript.tsconfigPath if needed

4. Configure Fastify TypeScript in apps/access-api:

   • Ensure tsconfig.json targets Node.js version
   • Configure ESM or CommonJS consistently
   • Document in apps/access-api/README.md

5. Create VERSIONS.md in the workspace root:

   # Dependency Versions
   
   ## Node.js
   - Minimum: 18.x
   - Recommended: 20.x
   
   ## pnpm
   - Minimum: 8.x
   - Recommended: 9.x
   
   ## TypeScript
   - Version: ^5.3
   
   ## App-Specific
   - Next.js (`apps/dashboard`): 14.x
   - Docusaurus (`apps/docs`): 3.x
   - Fastify (`apps/access-api`): 4.x
   - Discord.js (`apps/discord-bot`): 14.x
   
   ## Update Policy
   Major version updates require approval from the core team.

6. Add GitHub Actions matrix for testing across Node versions:

   strategy:
     matrix:
       node-version: [18.x, 20.x]

7. Document in README.md:

   ## Prerequisites
   - Node.js 18+ (see VERSIONS.md)
   - pnpm 8+ (see VERSIONS.md)

Acceptance Criteria

• All deprecation warnings in app builds are resolved
• apps/docs Docusaurus config updated to v3 standard (no warnings)
• apps/dashboard Next.js build succeeds with proper transpilation
• apps/access-api Fastify setup is documented and builds cleanly
• VERSIONS.md documents all major dependencies and Node/pnpm versions
• README.md links to VERSIONS.md for setup requirements
• CI/CD tests build across multiple Node versions
• All apps build successfully with documented versions

Affected Files/Directories

• apps/docs/docusaurus.config.js
• apps/dashboard/next.config.js
• apps/dashboard/tsconfig.json
• apps/access-api/tsconfig.json
• apps/access-api/README.md
• VERSIONS.md (create)
• .github/workflows/ci.yml (update with matrix)
• README.md (update)

[vijay11149]

can i work on this issue

[grantfox-oss]

🦊 GrantFox — @vijay11149 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #342)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.