Creating New Implementations

Relevant source files

• README.md
• apps/documentation/astro.config.mjs
• apps/documentation/src/assets/swagger.json
• apps/documentation/src/content/docs/community/resources.md
• apps/documentation/src/content/docs/implementation-creation/introduction.md
• apps/documentation/src/content/docs/introduction.mdx
• apps/documentation/src/content/docs/specifications/backend/introduction.md
• apps/documentation/src/content/docs/specifications/backend/postman.md
• apps/documentation/src/content/docs/specifications/frontend/api.md
• apps/documentation/src/content/docs/specifications/mobile-specs/introduction.md

Purpose and Scope

This document guides developers through the process of creating new RealWorld implementations (frontend or backend) that adhere to the RealWorld API specification. It covers checking for work-in-progress implementations, using starter kits, following specifications, testing implementations, and submitting them to CodebaseShow.

For details on the API specification itself, see API Specification. For testing infrastructure details, see Testing Infrastructure. For the reference backend implementation, see Reference Implementation.

---

Implementation Creation Overview

Creating a RealWorld implementation involves following a standardized process to ensure compatibility with the ecosystem's 150+ existing implementations. The fundamental principle is that any frontend can work with any backend because all implementations adhere to the same API specification defined in apps/documentation/src/assets/swagger.json1-1143

Implementation Workflow

Sources: README.md23-36 apps/documentation/src/content/docs/implementation-creation/introduction.md1-20

---

Step 1: Check for Work-in-Progress Implementations

Before starting a new implementation, check the GitHub Discussions to avoid duplicate efforts and potentially collaborate with others.

WIP Discovery Process

Action	Location	Purpose
Browse WIP Discussions	github.com/realworld-apps/realworld/discussions/categories/wip-implementations	Find existing implementations in progress
Search by Technology	Filter discussions by framework/language name	Identify if your chosen stack is already being worked on
Contact Author	Comment on existing WIP discussion	Explore collaboration opportunities

The RealWorld project discourages listing duplicate implementations to maintain quality and avoid fragmentation of community efforts.

Sources: README.md27 apps/documentation/src/content/docs/implementation-creation/introduction.md8-10

---

Step 2: Fork the Starter Kit

If no existing WIP matches your technology choice, fork the official starter kit repository.

Starter Kit Structure

The starter kit provides a basic project structure and documentation templates to help you get started quickly.

Sources: apps/documentation/src/content/docs/implementation-creation/introduction.md14 README.md36

---

Step 3: Understand the Specifications

Depending on whether you're creating a frontend or backend implementation, you must adhere to different specification documents.

Specification Mapping

Sources: apps/documentation/astro.config.mjs69-173 apps/documentation/src/content/docs/specifications/backend/introduction.md1-10

Key Specification Components

Backend Requirements

Backend implementations must implement 15 API endpoints organized into 6 categories as defined in apps/documentation/src/assets/swagger.json41-632:

Category	Endpoints	Authentication
User and Authentication	/users/login, /users, /user (GET, PUT)	Some required
Profile	/profiles/{username}, /profiles/{username}/follow	Optional/Required
Articles	/articles, /articles/feed, /articles/{slug}	Optional/Required
Comments	/articles/{slug}/comments, /articles/{slug}/comments/{id}	Some required
Favorites	/articles/{slug}/favorite	Required
Tags	/tags	Not required

Each endpoint must return responses conforming to the schemas defined in apps/documentation/src/assets/swagger.json634-1141

Frontend Requirements

Frontend implementations must:

• Use the Bootstrap 4 theme for consistent UI/UX
• Implement routing patterns for pages like Home, Sign In, Sign Up, Settings, Editor, Article, Profile
• Connect to a backend API (local, self-hosted, or api.realworld.show)
• Handle all API response formats correctly

Sources: apps/documentation/src/content/docs/specifications/backend/introduction.md5-9 apps/documentation/src/content/docs/introduction.mdx32-33

---

Step 4: Backend Implementation Testing

Backend implementations must pass the comprehensive Postman test suite to ensure specification compliance.

Backend Testing Architecture

Running Tests Against Your Backend

To test your backend implementation locally, use the provided test script:

The test script api/run-api-tests.sh executes the Newman CLI with the Postman collection api/Conduit.postman_collection.json which validates:

• Authentication: User registration, login, token validation, user updates
• Articles: CRUD operations, pagination, filtering by author/tag/favorited
• Comments: Create and delete operations
• Profiles: Retrieval and follow/unfollow functionality
• Favorites: Adding and removing article favorites
• Tags: Tag list retrieval

The collection uses stateful testing, storing JWT tokens and article slugs across requests to test complete user workflows.

Sources: apps/documentation/src/content/docs/specifications/backend/postman.md1-10 apps/documentation/src/content/docs/specifications/backend/introduction.md5-9

---

Step 5: Frontend Implementation Testing

Frontend implementations can be tested against multiple backend options, allowing flexibility during development.

Frontend API Integration Options

API Deployment Considerations

The reference backend implementation provides two branches with different use cases:

Branch	Use Case	Features	Location
main	Local development	Full RealWorld spec, no restrictions	Recommended for testing
limited	Public hosting	Content visibility restrictions, account isolation	Use for deployed demos

The limited branch implements content isolation where:

• Logged-out users see only demo account content
• Logged-in users see only their content plus demo account content

This prevents free-form user content exposure on public APIs.

Sources: apps/documentation/src/content/docs/specifications/frontend/api.md1-55

Testing Your Frontend

1. Point API Requests: Configure your frontend to point to https://api.realworld.show/api or your local backend
2. Manual Testing: Navigate through all pages and verify functionality:
   • User authentication (sign up, sign in, sign out)
   • Article operations (create, read, update, delete)
   • Comments (add, view, delete)
   • Profiles (view, follow/unfollow)
   • Favorites (add, remove)
3. Verify UI/UX: Ensure styling matches the Bootstrap 4 theme specifications

Sources: apps/documentation/src/content/docs/specifications/frontend/api.md36-43

---

Step 6: Submit to CodebaseShow

Once your implementation is complete and tested, submit it to CodebaseShow for inclusion in the RealWorld ecosystem.

Submission Process

To submit your implementation:

1. Ensure your repository includes:

   • Complete source code
   • README with setup instructions
   • License information
   • Link to live demo (if applicable)

2. Visit https://codebase.show/projects/realworld and follow the submission process

3. Your implementation will be categorized as:

   • Frontend (category=frontend) - Client-side implementations
   • Backend (category=backend) - Server-side implementations
   • Mobile - Mobile application implementations

Once listed, your implementation becomes part of the ecosystem and can be used by developers learning your chosen technology stack.

Sources: README.md17-25 apps/documentation/src/content/docs/implementation-creation/introduction.md17 apps/documentation/src/content/docs/introduction.mdx17-26

---

Implementation Type Reference

Frontend Implementation Checklist

• Fork starter kit
• Read frontend specifications in specifications/frontend/
• Implement all required pages (Home, Sign In, Sign Up, Settings, Editor, Article, Profile)
• Use Bootstrap 4 theme from conduit-bootstrap-template
• Implement routing according to specifications/frontend/routing.md
• Connect to API (demo, local, or self-hosted)
• Manual testing of all features
• Document setup instructions
• Submit to CodebaseShow

Backend Implementation Checklist

• Fork starter kit
• Read backend specifications in specifications/backend/
• Implement all 15 endpoints defined in swagger.json
• Implement JWT authentication with Token security scheme
• Follow response formats in api-response-format.md
• Implement error handling per error-handling.md
• Configure CORS per cors.md
• Run and pass Postman collection tests
  • ./api/run-api-tests.sh
• Document setup and deployment instructions
• Submit to CodebaseShow

Sources: apps/documentation/astro.config.mjs89-153 apps/documentation/src/assets/swagger.json1-1143

---

Additional Resources

Community Support

Resource	Purpose	Location
GitHub Discussions	Ask questions, share progress	github.com/realworld-apps/realworld/discussions
WIP Implementations	Check existing projects, collaborate	discussions/categories/wip-implementations
CodebaseShow	Browse existing implementations	codebase.show/projects/realworld

Reference Implementations

The repository includes a reference Node.js backend implementation in apps/api/ that demonstrates best practices for:

• Nitro framework setup
• Prisma ORM usage
• JWT authentication
• Route handler implementation
• Database schema design

Study the reference implementation for guidance on implementing the specification correctly. See Reference Implementation for detailed documentation.

Sources: README.md15 apps/documentation/src/content/docs/introduction.mdx15

---

Mobile Implementations

For mobile implementations (iOS/Android), the process is similar but with platform-specific considerations:

• Use Medium.com mobile apps as UI/UX reference
• Icons provided at spec/mobile_icons/ in the repository
• No shared styles/templates due to platform differences
• Follow KISS principle - don't over-complicate to match Medium exactly
• Still adhere to the same API specification in swagger.json

Sources: apps/documentation/src/content/docs/specifications/mobile-specs/introduction.md1-12