Buddies of Budgie Site

This repository houses the Next.js-based website for Buddies of Budgie, an open source organization building the Budgie Desktop environment.

Live Site: buddiesofbudgie.org

Tech Stack

• Framework: Next.js 16 (App Router) with React 19
• Language: TypeScript
• Styling: Tailwind CSS 4
• UI Components: shadcn/ui with Radix primitives
• Content: MDX with @next/mdx (file-based, statically generated)
• Internationalization: next-intl
• Linting/Formatting: Biome
• Package Manager: Yarn 4 (Berry)
• Build Tool: Webpack (Turbopack disabled for MDX compatibility)

Project Structure

site/
├── src/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   │   ├── about/        # About page components
│   │   ├── blog/         # Blog components
│   │   ├── home/         # Home page components
│   │   ├── mdx/          # MDX component overrides
│   │   └── ui/           # shadcn/ui components
│   ├── content/          # MDX content files
│   │   ├── about/        # About pages (FAQ, etc.)
│   │   └── blog/         # Blog posts
│   ├── data/             # Static data files
│   ├── messages/         # i18n translation files
│   └── styles/           # Global styles
├── public/               # Static assets
├── mdx-components.tsx    # Global MDX components configuration
└── next.config.js        # Next.js configuration

Development

Prerequisites

We use nvm (Node Version Manager) to ensure consistency across development environments. We target the latest Node.js LTS version.

1. Install nvm following their installation guide
2. Run nvm use in the project root to use the correct Node version
3. (Optional) Set up automatic version switching

Setup

This project uses Yarn 4 (Berry). First-time setup:

# Enable corepack (ships with Node.js 16+)
corepack enable

# Install dependencies
yarn install

Development Server

Start the development server with webpack (required for MDX support):

yarn dev

Open http://localhost:3000 in your browser.

Available Commands

yarn dev              # Start development server (with webpack)
yarn build            # Build for production (with webpack)
yarn start            # Start production server
yarn lint             # Type check + Biome lint with auto-fix
yarn ci               # Type check + Biome lint (no fix, for CI)
yarn format           # Format code with Biome
yarn check-types      # TypeScript type check only

Upgrading Dependencies

To upgrade dependencies interactively:

yarn upgrade-interactive

Building for Production

yarn build

The build output will be in .next/ directory. The site is configured for standalone output (output: 'standalone' in next.config.js).

Content Management

Blog Posts

Blog posts are MDX files in src/content/blog/. Each post requires frontmatter:

---
title: "Post Title"
author: AuthorId
publishDate: "2026-01-01T00:00:00.000Z"
featuredImage: /images/blog/2026/01/image.jpg
excerpt: Short description
tags:
  - news
  - releases
---

Your content here...

MDX Components

Custom MDX components are defined in:

• src/components/mdx/mdx-components.tsx - Component definitions
• mdx-components.tsx (root) - Global configuration using useMDXComponents

Available custom components:

• <Admonition type="info|note|tip|caution|warning|danger"> - Callout boxes
• <Alert severity="info|warning|error|success"> - Legacy alert component (maps to Admonition)
• <FAQSection> and <FAQItem> - FAQ components
• <OCCallout> - Open Collective donation callout

Architecture Notes

MDX Handling

The site uses @next/mdx with dynamic imports for MDX content. Key points:

• No next-mdx-remote - We use Next.js's native MDX support with @next/mdx
• Dynamic imports - Blog posts and content are imported dynamically: (await import('@site/content/blog/${slug}.mdx')).default
• Frontmatter stripping - Handled by remark-frontmatter and remark-mdx-frontmatter plugins
• Webpack required - Turbopack has compatibility issues with dynamic MDX imports, so we use webpack (--webpack flag)

Static Generation

All pages are statically generated at build time:

• Blog posts: Generated via generateStaticParams
• FAQ page: export const dynamic = 'force-static'
• About pages: Fully static

Internationalization

Currently supports English only. Translations are in src/messages/en.json and accessed via useTranslations from next-intl.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Run linting: yarn lint
5. Build to verify: yarn build
6. Commit with a descriptive message
7. Push to your fork and submit a pull request

Code Style

• Use Biome for linting and formatting (automatically applied on save with most editors)
• TypeScript strict mode enabled - avoid any types
• Components should be functional with TypeScript
• Follow existing naming conventions

Troubleshooting

MDX Build Errors

If you encounter MDX-related build errors:

1. Ensure you're using webpack: yarn build --webpack
2. Clear build cache: rm -rf .next && yarn build
3. Verify @mdx-js/loader is installed: yarn why @mdx-js/loader

Type Errors

Run type checking separately to see detailed errors:

yarn check-types

Resources

• Next.js Documentation
• Next.js App Router Guide
• MDX Documentation
• Tailwind CSS Documentation
• shadcn/ui Components

License

This project is open source and available under the terms specified in the LICENSE file.