Rodrigo Pombo

@pomber

Migrating to Code Hike 1.0

Incremental adoption guide

If you were using Code Hike before v1 and want to migrate to the new version, this guide is for you. To learn more about the new features, read the v1 announcement post.

Code Hike v1 is different from the previous versions in many ways, so migrating won't be trivial. The good news is that the two version can coexist, so you can adopt the new version incrementally.

Installing v1 (without removing v0)

Since the new version of Code Hike is a different package, you can install it alongside the old one:

npm install codehike

Update your configuration file (depending on the framework, for example next.config.mjs for Next.js) to use the new package:

1
// codehike v0
2
import { remarkCodeHike } from "@code-hike/mdx"
3
+
// codehike v1
4
+
import * as v1 from "codehike/mdx"
5

6
+
/** @type {import('codehike/mdx').CodeHikeConfig} */
7
+
const chConfig = {
8
+
  syntaxHighlighting: { theme: "github-dark" },
9
+
}
10

11
const mdxOptions = {
12
  remarkPlugins: [
13
+
    [v1.remarkCodeHike, chConfig],
14
    [remarkCodeHike, { theme: "github-dark", lineNumbers: false }],
15
  ],
16
+
  recmaPlugins: [[v1.recmaCodeHike, chConfig]],
17
}

With this setup, you can start using the new features of v1 while keeping the old ones working with v0.

Migrating codeblocks and annotations

To avoid changing all your codeblocks at once, you can use the ignoreCode option to only use v1 for the codeblocks you want.

1
import { remarkCodeHike } from "@code-hike/mdx"
2
import * as v1 from "codehike/mdx"
3

4
/** @type {import('codehike/mdx').CodeHikeConfig} */
5
const chConfig = {
6
  syntaxHighlighting: { theme: "github-dark" },
7
+
  components: { code: "MyCode" },
In v1, you define your own component to render codeblocks
8
+
  ignoreCode: ({ meta }) => !meta.startsWith("use-v1"),
Opt-in to v1 when the codeblock metastring starts with use-v1
9
}
10

11
const mdxOptions = {
12
  remarkPlugins: [
13
    [v1.remarkCodeHike, chConfig],
14
    [remarkCodeHike, { theme: "github-dark", lineNumbers: false }],
15
  ],
16
  recmaPlugins: [[v1.recmaCodeHike, chConfig]],
17
}

In your MDX files, you can start adopting v1 by adding the use-v1 metastring to the codeblocks you want to migrate:

# Hello world

```js
console.log("this is codehike v0")
```

```js use-v1
console.log("this is codehike v1")
```

Instead of "use-v1", you can use any string. Just make sure it's easy to find and replace when you finish the migration.

Comparison table

Here's the equivalent features between v0 and v1, they aren't exactly the same, but they are similar: