Cannot deploy to Github pages because "@astrojs/mdx" fails to import

[erralb]

What version of starlight are you using?

0.27.1

What version of astro are you using?

4.15.4

What package manager are you using?

pnpm

What operating system are you using?

Linux

What browser are you using?

Chrome

Describe the Bug

Following the Github pages deployment guide, I am getting the following error at build :

> astro check && astro build
10:42:03 AM [vite] Error when evaluating SSR module /home/runner/work/bdd/bdd/astro.config.mjs: failed to import "@astrojs/mdx"

|- Error: Cannot find module '@astrojs/mdx' imported from '/home/runner/work/bdd/bdd/astro.config.mjs'
    at nodeImport (file:///home/runner/work/bdd/bdd/node_modules/.pnpm/vite@5.4.4/node_modules/vite/dist/node/chunks/dep-BEhTnQAI.js:52989:19)
    at ssrImport (file:///home/runner/work/bdd/bdd/node_modules/.pnpm/vite@5.4.4/node_modules/vite/dist/node/chunks/dep-BEhTnQAI.js:52856:22)
    at eval (/home/runner/work/bdd/bdd/astro.config.mjs:5:37)
    at async instantiateModule (file:///home/runner/work/bdd/bdd/node_modules/.pnpm/vite@5.4.4/node_modules/vite/dist/node/chunks/dep-BEhTnQAI.js:52914:5)

[astro] Unable to load your Astro config
 ELIFECYCLE  Command failed with exit code 1.
Error: Process completed with exit code 1.

Locally, it works fine (with astro build and astro dev)

My astro.config.mjs file :

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import mdx from '@astrojs/mdx';
import expressiveCode from "astro-expressive-code";
import remarkMermaid from 'remark-mermaidjs'

// https://astro.build/config
export default defineConfig({
    site: 'https://erralb.github.io/bdd',
    integrations: [
        starlight({
                 //......
        }),
        expressiveCode(),
        mdx(),
    ],
    markdown: {
        // Applied to .md and .mdx files
        remarkPlugins: [remarkMermaid],
    },
});

My deployment file :

name: Deploy to GitHub Pages

on:
  # Trigger the workflow every time you push to the `main` branch
  # Using a different branch name? Replace `main` with your branch’s name
  push:
    branches: [ main ]
  # Allows you to run this workflow manually from the Actions tab on GitHub.
  workflow_dispatch:

# Allow this job to clone the repo and create a page deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3
        with:
          # path: . # The root location of your Astro project inside the repository. (optional)
          node-version: 22.3 # The specific version of Node that should be used to build your site. Defaults to 20. (optional)
          package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

The repo is publicly available for trying to reproduce the bug, any help would be much appreciated !

Link to Minimal Reproducible Example

https://github.com/erralb/bdd

Participation

• [ ] I am willing to submit a pull request for this issue.

[delucis]

Hi @erralb! Your project does not include @astrojs/mdx in its dependencies so that’s why you’re getting that error.

In general for a Starlight project you don’t need to add MDX or astro-expressive-code manually like in your Astro config file: https://github.com/erralb/bdd/blob/128c39b92be3a134b3035ee2ba027112d64428ac/astro.config.mjs#L122-L123

Starlight adds both of those for you.

[erralb]

Thanks @delucis , it solved my problem.

I added this while following this documentation to add the MermaidJS plugin. I actually also had other problems afterwards with Playwright and Github actions, but at least my first problem is solved thanks !

[delucis]

Thanks for sharing the blog post! Makes sense there I guess because they’re recommending those extra integrations for a plain Astro site, but Starlight comes with them built in. Glad you got it working 🙌