A single-page, statically exported tutorial site built with Next.js and MDX. It teaches a developer who has never used Keploy how to record real API calls against a Go service and replay them as tests, with the database switched off.
- Live site: https://keploy-go-quickstart-tutorial-ebon.vercel.app
- Repository: https://github.com/CodewithJha/keploy-go-quickstart-tutorial-final
- An original beginner tutorial written from a real Keploy run, not a copy of the official docs.
- A Next.js App Router site whose content is a single MDX file compiled at build time by
@next/mdx. - Custom React components used directly inside MDX: steps, callouts, checkpoints, troubleshooting cards, a workflow diagram and code blocks with copy buttons.
- Build-time syntax highlighting with light and dark themes, a theme toggle, a sticky table of contents with scroll-spy and a mobile contents menu.
The tutorial follows the "Running App Locally" variant of Keploy's Gin + MongoDB quickstart: a Gin URL shortener from keploy/samples-go, with the app on the host and MongoDB in Docker.
I ran it on macOS (Apple Silicon) with Go 1.27.1 and Keploy 3.8.58. That run recorded 5 test cases and 9 MongoDB mocks. keploy test then passed 5 of 5 with MongoDB stopped, and deliberately editing an expected response in one recorded test produced 4 passed and 1 failed. The commands, output and problems in the tutorial come from that run. Anything I did not run myself is labelled as such in the text.
| Area | Choice |
|---|---|
| Framework | Next.js 16.3.8 (App Router, Turbopack), React 19.2.8, TypeScript 5 |
| Content | @next/mdx 16.3.8 with @mdx-js/loader and @mdx-js/react 3 |
| MDX plugins | remark-gfm, rehype-slug, rehype-autolink-headings, rehype-pretty-code 0.14 + Shiki 4 |
| Styling | Tailwind CSS 4 via @tailwindcss/postcss, plus CSS design tokens in app/styles/ |
| Tooling | ESLint 9 (eslint-config-next), Prettier 3 with prettier-plugin-tailwindcss, pnpm 11 |
| Hosting | Vercel, static export |
There is no component library, icon package or animation library. Icons are inline SVGs in components/icons.tsx.
The sections in content/tutorial.mdx, in order:
- What you will build
- What is Keploy
- Prerequisites
- Get the sample app
- Prepare the app
- Install Keploy
- Record test cases
- Replay the tests
- Break a test on purpose
- Read what Keploy generated (a test case, the mocks)
- How Keploy works
- Why this matters for Go developers
- Common problems and fixes (problems I hit, mistakes to avoid)
- Verification checklist
- Clean up
- What you learned
- Next steps
Prerequisites:
- Node.js 22.13 or newer. Next.js 16 needs 20.9+, but the pinned pnpm 11.20.0 needs 22.13+.
- pnpm 11. With Corepack,
corepack enablepicks up the version frompackageManagerinpackage.json.
No environment variables are needed (see .env.example).
git clone https://github.com/CodewithJha/keploy-go-quickstart-tutorial-final.git
cd keploy-go-quickstart-tutorial-final
pnpm install
pnpm devThen open http://localhost:3000.
| Command | What it does |
|---|---|
pnpm dev |
Start the dev server |
pnpm lint |
Run ESLint |
pnpm typecheck |
Run tsc --noEmit |
pnpm format |
Format all files with Prettier |
pnpm format:check |
Check formatting without writing |
pnpm build |
Production build (static export to out/) |
pnpm start |
next start; not used, since the site is a static export |
pnpm buildnext.config.ts sets output: "export", so the build writes plain HTML, CSS and JS to out/. The only page is /, alongside the default not-found page, the favicon and the Open Graph image. To preview the export locally, serve out/ with any static server:
python3 -m http.server --directory out 3100app/
layout.tsx Root layout: fonts, metadata (Open Graph, Twitter), pre-paint theme script
page.tsx The single page: skip link, header, MDX content, sidebar TOC, footer
globals.css Tailwind entry; imports the files in app/styles/
styles/ tokens.css (colours, spacing), prose.css (MDX typography), code.css
icon.svg Favicon
opengraph-image.png Social preview image (alt text in opengraph-image.alt.txt)
components/
icons.tsx Inline SVG icons
layout/ SiteHeader, TutorialHeader, TableOfContents, MobileMenu, ThemeToggle, SiteFooter
mdx/ Components used by the MDX content (see below)
config/
site.ts Title, description, URLs, tested versions
nav.ts Header links
toc.ts Table of contents entries, shared by the sidebar and mobile menu
content/
tutorial.mdx The tutorial
lib/
theme.ts Inline script that sets the theme before first paint
get-text.ts Extracts plain text from a React tree for copy buttons
mdx-components.tsx Maps MDX elements and custom tags to React components
next.config.ts Static export and the MDX plugin pipeline
next.config.ts wraps the config with createMDX from @next/mdx and adds md/mdx to pageExtensions. app/page.tsx imports content/tutorial.mdx as a component and renders it inside the article.
mdx-components.tsx exports useMDXComponents, which registers these components so the MDX file can use them without imports:
| Tag | Purpose |
|---|---|
<Step> |
Numbered step with a title |
<Callout> |
Note, tip or warning box (type="info" | "tip" | "warning") |
<Checkpoint> |
Marks a point where the reader confirms the expected result |
<CommandBlock> |
One shell command with a $ prompt that is not copied |
<Problem> |
Troubleshooting card: why it happens, how to identify, fix, verify |
<WorkflowDiagram> |
Record and replay diagram built from HTML and CSS |
It also overrides pre with CodeBlock and figure with CodeFigure, so every fenced code block gets a toolbar with a language or file title and a copy button. CodeFrame holds that toolbar, and ScrollHint shows a small "Scroll" hint when a code line is wider than the screen.
Syntax highlighting runs at build time. rehype-pretty-code uses Shiki with the github-light and github-dark-dimmed themes, and CSS switches between them with the site theme, so no highlighting code ships to the browser.
Heading ids come from rehype-slug, and rehype-autolink-headings appends a # link to each heading. The table of contents is not generated from the MDX: it is the list in config/toc.ts, whose ids match the slugged h2 headings. TableOfContents highlights the current section on scroll and marks it with aria-current.
The MDX plugins are referenced by name in next.config.ts so they work with Turbopack.
The Vercel project is connected to this GitHub repository. Every push to main creates a production deployment; Vercel detects Next.js and runs pnpm build.
To deploy manually instead, from a linked checkout:
npx vercel deploy --prodBecause the output is a static export, out/ can also be served from any static host.
- Live: https://keploy-go-quickstart-tutorial-ebon.vercel.app
- Source: https://github.com/CodewithJha/keploy-go-quickstart-tutorial-final
Checks that were run on this project:
pnpm format:check,pnpm lint,pnpm typecheckandpnpm buildall pass.- Every in-page
#link in the builtout/index.htmlresolves to an element id, and every table of contents id matches a heading. - Every external URL in the MDX, config and README returns HTTP 200.
- The live site was tested in headless Google Chrome (via Playwright) at widths from 320 to 1920 pixels, in light and dark themes: no horizontal page overflow, long code scrolls inside its block, and the mobile menu, theme toggle and persistence, copy buttons, table of contents and keyboard focus all work, with no console errors or failed requests.
Browser testing was Chrome emulation only. Real touch devices, Safari, Firefox and screen readers were not tested, and colour contrast was not measured.
This is my submission for the Keploy DevRel candidate assignment. The brief was to run one of Keploy's Go quickstarts, write a new beginner-friendly tutorial from that experience, and publish it as a static single-page Next.js + MDX site on Vercel.
This is an independent write-up, not an official Keploy page. Keploy's CLI output and file formats change between versions, so what you see may differ from what is shown here.