Onboarding: realworld-apps/realworld

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Single-maintainer risk — review before adopting

• Last commit 3w ago
• Other licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (2 contributors visible)
• ⚠ Single-maintainer risk — top contributor 99% of commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

RealWorld is a specification repository and reference hub for building a Medium.com clone ('Conduit') that is identical across 100+ frontend and backend implementations. It provides a shared OpenAPI spec under specs/api/, a shared CSS theme at assets/theme/styles.css, a shared E2E test suite under specs/e2e/, and Bruno/Hurl API test collections — so any frontend (React, Angular, etc.) can be swapped against any backend (Node, Django, etc.) without modification. The repo is a monorepo-style spec hub: specs/api/ holds the canonical API spec and Bruno (.bru) + Hurl test collections, specs/e2e/ holds frontend E2E tests, assets/ holds shared CSS theme and media, and docs/ is an Astro 5 + Starlight + React + Tailwind 4 documentation site (configured in the package.json at root or docs/). GitHub Actions in .github/workflows/ automate Bruno spec validation, CodeQL analysis, and docs deployment.

Who it's for

Framework authors and developers who want to demonstrate their stack's capabilities beyond a 'todo app', and learners who want to see idiomatic full-stack patterns in a realistic app. It's also for maintainers of existing implementations who need to validate spec compliance via the API test suite.

Maturity & risk

The project is well-established with an active CI pipeline (.github/workflows/bruno-check.yml, codeql.yml, deploy-docs.yml), CodeQL security scanning, and a Dependabot config (.github/dependabot.yml). It has named active maintainers (c4ffein) and a live hosted demo at demo.realworld.show. Verdict: actively maintained reference project, production-ready as a spec and testing hub.

The core risk is single-maintainer concentration — c4ffein is explicitly called out as the primary active maintainer. The repo itself is not a deployable app but a spec/docs hub, so dependency risk is mostly in the docs site (Astro 5.x + Tailwind 4.x, both cutting-edge versions that may have breaking changes). The 67k lines of Bru (Bruno) and 40k lines of Hurl files represent large test collections that could become stale if the API spec drifts.

Active areas of work

Active work is visible in the GitHub Actions workflows: bruno-check.yml runs automated validation of the Bruno API spec files on every push, and deploy-docs.yml continuously deploys the Astro-based documentation site. The Dependabot config (.github/dependabot.yml) is actively bumping dependencies. The docs site is on cutting-edge Astro 5.16 and Tailwind 4.1, suggesting recent active upgrades.

Get running

git clone https://github.com/realworld-apps/realworld.git cd realworld

To run the documentation site:

npm install npm run dev

To run API spec tests against a backend (requires Bruno CLI):

npx @usebruno/cli run specs/api/

Or with Hurl:

hurl specs/api/*.hurl

Daily commands: cd into the repo root (or docs/ if that's where package.json lives), then: npm install && npm run dev starts the Astro docs site on localhost:4321. For API spec validation: use Bruno desktop app pointed at specs/api/ or run npx @usebruno/cli run specs/api/ against a running backend at api.realworld.show or locally.

Map of the codebase

• specs/api/: The canonical API test suite in Bruno and Hurl formats — this is what all compliant backends must pass
• specs/e2e/: Shared Cypress/Playwright E2E test suite that all frontend implementations should validate against
• assets/theme/styles.css: The single shared CSS file that gives all frontend implementations identical UI/UX
• .github/workflows/bruno-check.yml: CI workflow that automatically validates Bruno API spec files on every push
• .github/workflows/deploy-docs.yml: Deploys the Astro documentation site to docs.realworld.show
• CONTRIBUTING.md: Explains how to register a new implementation or contribute spec changes
• Makefile: Top-level developer convenience commands for running specs and other repo tasks
• .github/dependabot.yml: Tracks which dependency ecosystems are being auto-updated, revealing the tech surface of the repo

How to make changes

To update API spec: edit files in specs/api/ (Bruno .bru collections or Hurl files). To update documentation: edit Astro/MDX files under docs/. To update the shared CSS theme: edit assets/theme/styles.css. To add a new CI check: add a workflow in .github/workflows/. The CONTRIBUTING.md explains the contribution process for new implementation registrations.

Traps & gotchas

The Bruno spec tests in specs/api/ require a running backend — either the public api.realworld.show or a local instance; they won't run standalone. The docs site uses Astro 5 + Tailwind 4, both of which have breaking changes from v3/v4 predecessors, so don't assume older Astro/Tailwind knowledge applies. The .bru files use Bruno's proprietary format — you need Bruno CLI or desktop app, not Postman or Insomnia. Account isolation on api.realworld.show is enforced, so test data from one session won't bleed into another.

Concepts to learn

• API Contract Testing — The entire value proposition of this repo is that Bruno and Hurl test collections act as an executable contract — any backend claiming compliance must pass them, making this concept central to understanding the repo's purpose
• Bruno Collection Format (.bru) — 67k lines of the repo are .bru files — Bruno's git-friendly plain-text API collection format that replaces Postman JSON; understanding this format is essential to reading or modifying the spec tests
• Hurl HTTP Testing DSL — 40k lines of .hurl files provide an alternative spec test runner using a curl-like plain-text DSL — understanding its assertion syntax is needed to extend or debug API tests
• Astro Content Collections + Starlight — The docs site uses @astrojs/starlight on Astro 5 — Starlight's opinionated docs theme with MDX content collections is how all documentation pages are structured and deployed
• Island Architecture (Astro) — The docs site uses @astrojs/react for interactive React 19 components embedded in otherwise static Astro pages — understanding islands explains why React is a dependency in a mostly-static docs site
• OpenAPI Specification — The specs/api/ directory defines the API contract that all 100+ implementations must conform to — understanding OpenAPI is prerequisite to reading, writing, or extending the spec

Related repos

• realworld-apps/nitro-prisma-zod-realworld-example-app — Official spec-compliant TypeScript backend implementation that passes the full API test suite in this repo
• c4ffein/realworld-django-ninja — Official spec-compliant Python/Django Ninja backend listed as passing the full API spec in this repo's README
• gothinkster/realworld — The predecessor/original RealWorld repo from which this was forked or migrated, containing the historical implementation registry
• usebruno/bruno — The Bruno API client whose .bru file format makes up 67k lines of this repo's API test suite
• Orange-OpenSource/hurl — The Hurl HTTP testing tool whose .hurl format makes up 40k lines of this repo's alternative API test suite

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add a GitHub Actions workflow to validate the Bruno API collection on every PR

The repo already has a .github/workflows/bruno-check.yml workflow file, but based on the file listing there are no corresponding Bruno collection files (.bru files) visible in the repo root or an api/ directory. A contributor could audit what bruno-check.yml actually checks, ensure the Bruno collection files are committed alongside it, and harden the workflow to fail fast when any endpoint definition drifts from the OpenAPI spec. This is high value because the entire RealWorld promise is that every frontend/backend pair adheres to the same API spec — a broken or absent Bruno check silently undermines that guarantee.

• [ ] Open .github/workflows/bruno-check.yml and identify exactly which paths/files it expects to lint or run
• [ ] Verify whether the referenced Bruno collection files (.bru / bruno.json) are actually present in the repo; if missing, add them under an api/bruno/ directory
• [ ] Add a paths: trigger to the workflow so it runs on changes to any .bru file or the OpenAPI spec file
• [ ] Add a step that diffs the Bruno collection against the canonical OpenAPI spec (e.g. using @apideck-libraries/openapi-diff) and fails the build on drift
• [ ] Update CONTRIBUTING.md with a note explaining how to run Bruno checks locally before opening a PR

Automate SVG/image asset optimisation via a CI workflow targeting assets/media/

The assets/media/ directory contains a mix of SVGs (conduit-logo.svg, frameworks.svg, default-avatar.svg) and dozens of PNG icon variants across iOS, Android, and iMessage densities. There is no existing workflow that optimises or validates these assets. A contributor could add a GitHub Actions job that runs svgo on SVGs and sharp (already a declared dependency in package.json) on PNGs to enforce size budgets, then commit optimised outputs or fail the PR if unoptimised files are pushed. This directly improves page-load performance on the docs site built with Astro/Starlight.

• [ ] Create .github/workflows/optimise-assets.yml triggered on pull_request with paths: ['assets/media/**']
• [ ] Add a step that runs npx svgo --recursive assets/media/ and checks git diff --exit-code to fail if the SVGs weren't pre-optimised
• [ ] Add a step using Node + sharp (already in package.json dependencies) to verify that each PNG in assets/media/mobile_icons/ does not exceed a per-density size budget (e.g. xxxhdpi ≤ 50 KB)
• [ ] Add a Makefile target make optimise-assets that contributors can run locally, mirroring the CI steps
• [ ] Document the new target in CONTRIBUTING.md under a 'Working with assets' section

Add TypeScript type-checking and a build-validation workflow for the Astro/Starlight documentation site

The package.json shows the docs site uses Astro 5, @astrojs/starlight, React 19, and TypeScript 5.9, and the build script already runs astro check && astro build. However, there is no GitHub Actions workflow that actually executes this build on PRs — deploy-docs.yml likely only triggers on pushes to main, meaning a PR can merge broken docs undetected. A contributor could add a ci-docs.yml workflow that runs npm run build in the docs package on every PR touching documentation source files, catching type errors and MDX compilation failures before they land.

• [ ] Create .github/workflows/ci-docs.yml triggered on pull_request with paths scoped to the docs source directory and package.json
• [ ] Add a job that sets up Node

Good first issues

1. Add missing Hurl test coverage for edge cases in specs/api/ — compare the Hurl files against the Bruno .bru collection to find endpoints tested in Bruno but not in Hurl. 2. The assets/media/conduit-logo.svg.generate.ts script likely needs documentation — add a comment block or docs page explaining how to regenerate the SVG assets. 3. The .github/ISSUE_TEMPLATE/ only has BUG_REPORT.yml and FEATURE_REQUEST.yml — add a IMPLEMENTATION_SUBMISSION.yml template to standardize how new framework implementations are proposed.

Top contributors

• @c4ffein — 99 commits
• @dependabot[bot] — 1 commits

Recent commits

• e75fef3 — fix: broken regex conversion for dates when generating bruno tests (c4ffein)
• 8ad0a49 — specs: e2e tests for pagination create other users/articles through ui when in no-api mode (c4ffein)
• ad527b5 — specs: e2e tests for social feature creates other users through ui when in no-api mode (c4ffein)
• b649a89 — specs: e2e test for null-fields now manually register users/change profile picture when in no-api mode (c4ffein)
• 04b354e — specs: e2e test for article pagination now create articles through ui in no-api mode (c4ffein)
• 58d2ffa — specs: e2e test setup now correctly fills the tags even in fullstack mode (c4ffein)
• a86e4d7 — specs: e2e/settings.spec.ts now adapted for fullstack implementations when setting is checked (c4ffein)
• 7b2ff8a — specs: e2e tests in social.spec.ts now either rely on existing users for SPA + demo backend, or create users for fullsta (c4ffein)
• 55bda76 — specs: missing expect(page).toHaveURL instead of direct check in one of the tests as the page change is not always insta (c4ffein)
• 1a80a45 — specs: e2e test API_BASE param now set in config.ts (c4ffein)

Security observations

• Medium · Outdated or Potentially Vulnerable Transitive Dependencies — docs/package.json. The project uses several dependencies such as 'sharp' (^0.34.5), 'astro' (^5.16.16), and various React/Astro ecosystem packages. While the pinned major versions appear recent, the use of caret (^) version ranges means transitive dependencies may include packages with known CVEs that are not immediately visible without running a full dependency audit. 'sharp' in particular wraps native libvips binaries and has historically had CVEs related to image processing (e.g., buffer overflows in underlying C libraries). Fix: Run 'npm audit' regularly and consider pinning exact dependency versions or using a lockfile (package-lock.json or yarn.lock). Enable Dependabot alerts (already configured via .github/dependabot.yml) and review audit results before each release. Consider using tools like Snyk or Socket.dev for continuous dependency monitoring.
• Medium · Missing Security Headers Configuration — .github/workflows/deploy-docs.yml, astro.config (not visible but inferred). The project is a documentation/demo site built with Astro and deployed via GitHub Actions (.github/workflows/deploy-docs.yml). There is no visible configuration enforcing HTTP security headers such as Content-Security-Policy (CSP), X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security (HSTS), or Referrer-Policy. Without these headers, the deployed site is vulnerable to clickjacking, MIME-type sniffing attacks, and cross-site scripting escalation. Fix: Configure security headers either at the hosting/CDN layer or within the Astro configuration. For Astro static sites, add a _headers file (for Netlify/Cloudflare Pages) or configure the web server to serve appropriate headers. At minimum, set: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin.
• Medium · Potential XSS Risk via React Components with Unvalidated Content — docs/ (React components), @astrojs/react integration. The project uses React (^19.2.4) within an Astro framework for a documentation site. React components registered via @astrojs/react may render user-controlled or externally-sourced content. If any component uses 'dangerouslySetInnerHTML' or renders Markdown/HTML from untrusted sources without sanitization, XSS attacks are possible. While not directly confirmed in the visible file structure, the pattern of combining React with Astro/Starlight and rendering documentation content is a common vector. Fix: Audit all React components for use of 'dangerouslySetInnerHTML'. If HTML rendering from external content is required, use a sanitization library such as DOMPurify before rendering. Implement a strict Content-Security-Policy to limit script execution contexts.
• Low · No Visible Secret Scanning or Pre-commit Hooks — .github/, .gitignore. The repository does not appear to have any pre-commit hooks or secret scanning configuration (e.g., git-secrets, truffleHog, or GitHub's secret scanning enablement beyond default). While no hardcoded secrets are visible in the provided file structure, the absence of preventive controls means that contributors could accidentally commit API keys, tokens, or credentials in future changes. The presence of .github/CODEOWNERS and workflow files suggests an active contribution workflow that increases this risk surface. Fix: Enable GitHub Secret Scanning and Push Protection in the repository settings. Add a pre-commit hook using tools like 'detect-secrets' or 'git-secrets'. Include secret scanning steps in the CI pipeline (.github/workflows/). Ensure .gitignore properly excludes .env files and local configuration files containing secrets.
• Low · Dependabot Configuration May Not Cover All Ecosystems — .github/dependabot.yml. The .github/dependabot.yml is present, which is a positive indicator. However, given the repository description mentions multiple backend implementations (Node, Django, etc.), the Dependabot configuration may not cover all package ecosystems (npm, pip, etc.) if those backends are tracked in this repository or as submodules. Incomplete coverage leaves certain dependency trees unmonitored for security updates. Fix: Review the dependabot.yml to ensure all relevant package ecosystems (npm, pip, cargo, go, etc.) and directories are included. Verify that update schedules are set appropriately (e.g., weekly) and that

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.