How to Run the Prompt Engineering Guide Locally: Next.js and Nextra Setup

To run the Prompt Engineering Guide locally, install Node.js ≥18.0.0 and pnpm, clone the dair-ai/Prompt-Engineering-Guide repository, execute pnpm install to resolve dependencies listed in package.json, and run pnpm dev to start the Next.js development server at http://localhost:3000/.

The Prompt Engineering Guide is a static documentation site built with Next.js 13 and the Nextra documentation theme. Running the guide locally allows you to preview MDX content changes, test multilingual translations, and interact with the custom React components before deploying.

Prerequisites

Before starting, ensure your environment meets these requirements:

• Node.js ≥18.0.0 – Download the LTS version from nodejs.org or use a version manager like nvm
• pnpm – The project uses pnpm as its package manager. Install it globally with:

  npm i -g pnpm

Step-by-Step Local Installation

Follow these commands to get the guide running on your machine:

1. Clone the repository and navigate into the directory

   git clone https://github.com/dair-ai/Prompt-Engineering-Guide.git
   cd Prompt-Engineering-Guide

2. Install project dependencies

   pnpm install

   This reads the dependency list from [package.json](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/package.json) and installs Next.js, React, Nextra, and the documentation theme.

3. Start the development server

   pnpm dev

   This executes the dev script defined in the "scripts" section of [package.json](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/package.json#L5-L7), which launches next dev with hot-module reloading enabled.

4. Open the local site Navigate to http://localhost:3000/ in your browser. The server watches for changes to MDX pages in the pages/ directory and React components in components/, automatically rebuilding when you save files.

Project Architecture Overview

Understanding the key architectural components helps when customizing or debugging the local instance:

• Next.js 13 – The core React framework handling routing and server-side rendering, configured in [next.config.js](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/next.config.js)
• Nextra – The documentation theme providing MDX rendering and navigation, customized via [theme.config.tsx](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/theme.config.tsx)
• i18n Configuration – Multilingual support is defined in the i18n section of [next.config.js](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/next.config.js#L8-L11), specifying available locales and the default language
• Webpack SVG Loader – Custom webpack rules in [next.config.js](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/next.config.js#L12-L24) replace the default file-loader with @svgr/webpack, allowing SVG files to be imported as React components
• Custom Components – Interactive UI elements like copy-buttons and counters reside in the components/ directory

Key Configuration Files

When running the guide locally, these files control the build and rendering behavior:

File	Purpose	Key Details
package.json	Dependency management and scripts	Contains the "dev": "next dev" script that launches the local server
next.config.js	Next.js and Nextra configuration	Lines 8-11 define i18n locales; lines 12-24 configure the SVG webpack loader
theme.config.tsx	UI customization	Controls logo, navigation structure, and SEO metadata for the Nextra theme

Summary

• The Prompt Engineering Guide requires Node.js ≥18.0.0 and pnpm to run locally
• Use pnpm install to resolve dependencies from package.json, then pnpm dev to start the development server
• The site runs on http://localhost:3000/ with automatic reloading for MDX and component changes
• Core configuration lives in next.config.js (i18n locales and webpack rules) and theme.config.tsx (theme settings)
• The components/ directory contains custom React widgets that render within the documentation pages

Frequently Asked Questions

What is the exact command to start the local development server?

Run pnpm dev from the project root. This executes the dev script defined in package.json, which internally calls next dev to compile the site and watch for file changes on port 3000.

Can I use npm or yarn instead of pnpm?

While the repository is configured for pnpm (evident from the lockfile and installation instructions), you can technically use npm or yarn by running the equivalent install and dev commands. However, using pnpm ensures dependency resolution matches the project's lockfile exactly.

How do I add support for a new language when running locally?

Edit the i18n object in [next.config.js](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/next.config.js#L8-L11) to include your new locale in the locales array. Create a corresponding directory in the pages/ folder for your language content, and the Nextra theme will automatically include it in the navigation when you restart the pnpm dev server.

Why are SVG icons rendering as React components instead of image files?

The project uses a custom webpack configuration in [next.config.js](https://github.com/dair-ai/Prompt-Engineering-Guide/blob/main/next.config.js#L12-L24) that processes SVG files through @svgr/webpack. This allows components to import SVGs directly as React elements for styling and animation, rather than static assets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}