GitHub - o2sdev/openselfservice: Open Self Service - The Open Source Composable Frontend for Customer Portals

Framework for building composable customer self-service portals.

Open Self Service is an open-source development kit that simplifies the creation of self-service frontend applications by integrating multiple headless APIs into a scalable frontend. Its flexibility allows for many customizations and lets you build various types of composable frontends.

🚀 Key Features

Composable – In short: API-agnostic. Compose customer experience by combining multiple "backend capabilities" into seamless, fully decoupled frontend.
Next.js Frontend Starter – Robust Next.js-based frontend including basic customer portal pages and content management capabilities.
API Harmonization Server – Integration layer for data aggregation, orchestration and normalization. Provides vendor lock-in safeness and better maintainability.
TypeScript SDK – Easily interact with the Harmonization Server in the frontend app or any web, mobile, other TS-based apps.
Pre-built Blocks – 25+ ready-to-use UI blocks with backend logic and SDK clients. Self-contained, reusable components for common features.
Pre-built Integrations – Ready integrations so that you can set up your solution faster.
Extensibility – Customize UI components, add new pages, add new API integrations, adapt to your needs.

📖 Documentation

Check out the full documentation to get started.

🛠️ Installation

To set up a new O2S project, use the create-o2s-app starter and follow the installation steps in the documentation.

npx create-o2s-app my-project
cd my-project
npm run watch:deps
npm run watch:apps

🔧 Running the Project

To start all services in development mode, it is recommended to run two separate commands (ideally in separate terminal windows):

Watch dependencies – Automatically rebuilds internal packages when they change:
Watch applications – Starts the main applications with hot-reloading:

Important

The npm run dev script is now deprecated and will be removed in future versions. Please use watch:deps and watch:apps instead to ensure a smoother development experience.

To run individual components (useful for debugging one app at a time), you can still use:

cd apps/api-harmonization && npm run dev  # Start API Harmonization Server
cd apps/frontend && npm run dev  # Start Next.js Frontend

Note

When running components individually, remember to run npm run watch:deps from the root if you are making changes to shared packages.

For more details, check the Running the project guide.

🏗️ Project Structure

O2S follows a monorepo structure using Turborepo for managing apps and internal packages.

/apps
  /frontend             # Next.js frontend application
  /api-harmonization    # API Harmonization Server (NestJS)
  /docs                 # Documentation site (Docusaurus)

/packages
  /blocks/*             # Reusable UI blocks (25+ blocks)
  /framework            # Core framework modules & SDK
  /integrations/*       # Integration adapters (Strapi, Contentful, Redis, Algolia, Medusa, Zendesk, mocked)
  /modules/*            # Feature modules (e.g., surveyjs)
  /ui                   # Base UI component library (shadcn/ui + Tailwind)
  /utils/*              # Utility packages
  /configs/*            # Shared configurations
  /cli/*                # CLI tools (create-o2s-app)
  /telemetry            # Telemetry package

For a detailed breakdown, visit Project structure.

🖥️ Demo app

🧩 Blocks

O2S includes 25+ pre-built blocks - self-contained, reusable UI components that represent specific features or page sections. Each block includes backend logic (NestJS), frontend component (React), and SDK client.

Examples: article, article-list, ticket-list, order-details, invoice-list, user-account, and more.

For details, visit Blocks documentation.

🔌 Available Integrations

O2S includes pre-built integrations and allows you to extend functionality as needed.

Integration type/area	Status
CMS	✅ StrapiCMS - available ✅ Contentful - available
IAM	✅ Auth.js - available ✅ Keycloak - available (not part of O2S, contact us for details)
Cache	✅ Redis - available
Search	✅ Algolia - available
CRM	✅ Zendesk - available (tickets) ✅ SurveyJS - ticket submission handling 🔄 other CRM solutions - planned
ERP	✅ Medusa - via Medusa plugin adding ERP-like features 🔄 SAP S/4HANA - In progress (not part of O2S, contact us for details)
Commerce	🔄 Medusa - in progress (basic product information, other areas TBD)
Development	✅ Mocked - available (for local development and testing)

🔥 Why Open Self Service?

Fully composable – Integrate multiple backend services and build your solution by combining their capabilities.
Headless & API-first – Integrate multiple services seamlessly.
Future-proof – Build backend-agnostic customer portals. Swap backends without breaking the frontend.
Modern stack – Built with Next.js, shadcn/ui, TypeScript, NestJS.

🤝 Contributing

We welcome contributions! If you’d like to contribute, please check the Contribution Guide.

Contact e-mail

contact@openselfservice.com

📩 Stay Updated

Website: openselfservice.com
LinkedIn: /company/open-self-service/
Twitter/X: @openselfservice
Discord: Join our community
GitHub Discussions: Join the conversation

📜 License

Open Self Service is open-source software licensed under the MIT License.

Built by Hycom

O2S is maintained as an open-source project by hycom.digital - a Polish tech company that delivers enterprise digital self-service and e-commerce solutions.