Code Hike

Common errors

• TypeError: ke.createContext is not a function OR createContext only works in Client Components. Add the "use client" directive at the top of the file to use it.

  cause Attempting to use React Context API or other client-side React features within a server component, often when rendering MDX content in Next.js App Router without proper client component boundaries.
  fix Add `'use client'` at the top of the React component file that directly or indirectly uses `createContext` or other client-only React hooks/APIs.

• Error: Code Hike couldn't resolve this annotation: !from [filepath]. [absolute_filepath] doesn't exist.

  cause The `!from` directive used in Markdown to import external code cannot resolve the specified file path, usually because the MDX compiler function was called without setting the `file` path or context correctly.
  fix Ensure the MDX compilation environment correctly provides the `file.history` or equivalent context that allows Code Hike to resolve relative file paths, especially when integrating with custom MDX loaders or bundler configurations.

• ERROR at root Error for `steps`: Required { "expected": "array", "received": "undefined" }

  cause When using Code Hike's layout components (e.g., `Scrollycoding`, `Slideshow`) or the `parse` utility, the decorated Markdown content is not correctly structured or passed as the expected `steps` array prop.
  fix Verify that your Markdown content uses the correct decoration syntax (e.g., `!decorationName`) and that the parsing logic in your React component correctly extracts and passes the `steps` prop. Review Code Hike's documentation examples for content structuring.

Warnings

• breaking Version 1.0.0 introduced significant breaking changes with 'Fine-grained Markdown' and 'Headless codeblocks'. Migration from v0.x requires updating MDX configurations and custom code block components.
  Fix: Consult the official migration guide for Code Hike v1.0. Incremental adoption is supported by using `ignoreCode` in your configuration to opt-in specific code blocks to v1.
• gotcha The `highlight` function is asynchronous, making components that use it (e.g., custom code block components) React Server Components (RSCs). This might require specific framework configurations or handling for non-RSC environments.
  Fix: Ensure your framework supports RSCs for components using `highlight`. If not, configure Code Hike to perform highlighting during the MDX compilation step by defining `syntaxHighlighting.theme` in `chConfig` directly in `next.config.mjs`.
• gotcha When using built-in themes like `github-from-css` or `material-from-css`, you must define the corresponding CSS variables for colors in your global stylesheet for proper light/dark mode support. Simply importing the theme won't apply the styles correctly.
  Fix: Copy the required CSS variables from the Code Hike documentation for your chosen theme and include them in your project's global CSS, adapting selectors (e.g., `:root`, `@media (prefers-color-scheme: dark)`).
• gotcha Astro is not officially supported by Code Hike because MDX files are compiled to Astro components instead of React components, which is incompatible with Code Hike's React-based architecture.
  Fix: Code Hike is designed for React-based MDX setups. Consider using frameworks like Next.js, Remix, Docusaurus, Nextra, or Fuma Docs that are compatible.
• gotcha Users have reported intermittent build issues and 'TurbopackInternalError' when using Code Hike with Next.js's Turbopack bundler, especially with non-serializable options in `next.config.mjs` or newer Next.js versions.
  Fix: Ensure all options passed to `remarkCodeHike` and `recmaCodeHike` in `next.config.mjs` are serializable. If issues persist, consider disabling Turbopack or using a stable version of Next.js that has proven compatibility. Report specific errors on the Code Hike GitHub.

Install

• npm install codehike npm
• yarn add codehike yarn
• pnpm add codehike pnpm

Imports

• remarkCodeHike
  wrong:

  const { remarkCodeHike } = require('codehike/mdx')

  correct:

  import { remarkCodeHike, recmaCodeHike } from 'codehike/mdx'

  These are MDX plugins, primarily used in `next.config.mjs` or similar MDX configuration files. ESM syntax is preferred. `recmaCodeHike` is for JavaScript AST transformations.
• { Pre, RawCode, highlight }
  wrong:

  import { CodeHike } from 'codehike'

  correct:

  import { Pre, RawCode, highlight } from 'codehike/code'

  The `Pre` component is for rendering highlighted code, `RawCode` is a type, and `highlight` is an async function for syntax highlighting. `CodeHike` was a common import in v0.x, but v1 encourages building custom components from these primitives.
• CSS Styles
  wrong:

  import '@code-hike/mdx/dist/index.css'

  correct:

  import 'codehike/style.css'

  For `v1.x`, the primary stylesheet is `codehike/style.css`. Earlier versions (v0.x) used `@code-hike/mdx/dist/index.css`. Some themes also require custom CSS variables to be defined for proper light/dark mode support.

Quickstart

This quickstart demonstrates the core setup for Code Hike with MDX and a custom React Server Component for rendering code blocks with highlighting and annotations.

import { remarkCodeHike, recmaCodeHike } from 'codehike/mdx'
import { Pre, RawCode, highlight } from 'codehike/code'
import 'codehike/style.css'

// next.config.mjs (or similar MDX configuration)
const chConfig = {
  // Define a custom component to render code blocks
  components: { code: 'MyCode' },
  syntaxHighlighting: {
    theme: 'github-dark'
  }
}

const mdxOptions = {
  remarkPlugins: [[remarkCodeHike, chConfig]],
  recmaPlugins: [[recmaCodeHike, chConfig]],
  jsx: true,
}

// app/components/MyCode.tsx (React Server Component)
// This component renders an annotated code block.
export async function MyCode({ codeblock }: { codeblock: RawCode }) {
  const highlighted = await highlight(codeblock, "github-dark");
  return <Pre code={highlighted} />;
}

// app/page.mdx (example MDX content)
// ```js
// console.log("Hello from Code Hike!")
// // ! focus
// ```