---
title: Upgrading Expressive Code
---

import { Steps } from '@astrojs/starlight/components'
import PackageManagers from '@components/PackageManagers.astro'

If your site is already using Expressive Code, this page guides you through the process of upgrading it to the latest version.

Please select your framework to jump to the respective upgrade instructions:

- [Astro](#astro)
- [Starlight](#starlight)
- [Next.js](#nextjs)

## Astro

To upgrade your Astro site to the latest version of Expressive Code, follow these steps:

<Steps>

1. Change into the directory of your Astro site.

2. Install the latest version of `astro-expressive-code`:

    <PackageManagers pkg="astro-expressive-code@latest" />

3. Check our [release history](/releases/) for breaking changes that might affect your site, and apply any necessary changes.

4. You're done! 🎉

</Steps>

## Starlight

Starlight already has a dependency on `astro-expressive-code`, so you don't need to install or upgrade Expressive Code separately on Starlight sites.

We always try to keep Starlight's dependencies up to date, so upgrading Starlight should automatically upgrade Expressive Code as well:

<Steps>

1. Follow the instructions in [Starlight's documentation](https://starlight.astro.build/getting-started/#updating-starlight) to upgrade your site to the latest version of Starlight.

2. You're done! 🎉

</Steps>

### Overriding Expressive Code within Starlight

If you've already installed the latest version of Starlight and want to use a later version of `astro-expressive-code` than the one it comes with, you can use the **overrides** feature of your package manager.

:::caution
This is an advanced strategy that might lead to incompatibilities, and we recommend waiting for the next Starlight release instead. If you continue, please check if your site still works as expected after the upgrade.
:::

<Steps>

1. Add the following `overrides` section to your `package.json`:

    ```json title="package.json" collapse={11-18} ins={20-22}
    {
      "name": "my-starlight-site",
      "version": "0.0.1",
      "type": "module",
      "scripts": {
        "dev": "astro dev",
        "build": "astro build",
        "preview": "astro preview",
      },
      "dependencies": {
        "@astrojs/starlight": "^0.13.1",
        "astro": "^3.3.0",
        "mdast-util-from-markdown": "^2.0.0",
        "mdast-util-to-markdown": "^2.1.0",
        "mdast-util-to-string": "^4.0.0",
        "sharp": "^0.32.5",
        "tsm": "^2.3.0",
        "unist-util-visit": "^4.1.2"
      },
      "overrides": {
        "astro-expressive-code": "latest"
      }
    }
    ```

  2. Run the install command of your package manager to apply the override:

      <PackageManagers />

  3. Check our [release history](/releases/) for breaking changes that might affect your site, and apply any necessary changes.

  4. You're done! 🎉

</Steps>

## Next.js

To upgrade your Next.js site to the latest version of Expressive Code, follow these steps:

<Steps>

1. Change into the directory of your Next.js site.

2. Install the latest version of `rehype-expressive-code`:

    <PackageManagers pkg="rehype-expressive-code@latest" />

3. Check our [release history](/releases/) for breaking changes that might affect your site, and apply any necessary changes.

4. You're done! 🎉

</Steps>
