Blogpost detailing our journey from a simple showcase to a comprehensive custom element gallery at Kontent.ai, sharing insights on how my team and I evolved the project to empower developers and enhance our headless CMS capabilities.
Introduction
When we first envisioned custom elements at Kontent.ai, our goal was to extend our headless CMS with tailored functionality through small HTML apps running in sandboxed iframes. These apps interact with Kontent.ai using a defined set of JavaScript post messages, essentially loading web pages within the CMS. This integration, facilitated by the Custom Elements API, enabled us to build tools that went far beyond standard content type elements.
What Is a Custom Element?
Custom elements are self-contained web applications embedded directly in the Kontent.ai CMS. They communicate with the system through a set of post messages defined in JavaScript, allowing for seamless integration and extended functionality. In simple terms, they are web pages loaded within the CMS that interact via the Custom Elements API, giving developers the power to create interactive and context-aware content experiences.
The Early Days: Prototypes and Simple Samples
Our journey began with a modest project aimed at showcasing how to build custom elements and interact with them. We started with two simple sample elements—a color picker and a Markdown editor. These initial prototypes came bundled with basic CSS styles and fonts, ensuring they adhered to the headless CMS's look and feel. This phase was crucial as it provided a clear, hands-on example of how the Custom Elements API could be leveraged to enhance content creation.
Community Growth and the Expanding Catalog
As more developers began building their own custom elements, our project quickly evolved. We transformed our initial repository into a comprehensive catalog using Gatsby.js, inviting community submissions and sharing custom elements that were both innovative and practical. This catalog not only served as a code repository but also functioned as a deployment center (via GitHub Pages) for these elements. The repository became a valuable resource for consulting and professional services, showcasing the creativity and potential of custom elements within the Kontent.ai ecosystem.
The Need for Re-architecture
With the expansion of our custom elements catalog, public confusion began to emerge. Many users mistakenly believed that the elements hosted on our repository were fully maintained by us for production use. To address this, we re-architected the project by rewriting the library in Vue.js. This new client-side web app was designed to serve purely as a guidepost—providing best practices, consistent styling, and enhanced search functionality—without being a production hosting platform. This clear delineation helped us reposition our role as providers of developer resources rather than as maintainers of every custom element.
Splitting the Project: Embracing the Single Responsibility Principle
As our repository grew, it became increasingly challenging to curate a mix of well-maintained custom elements alongside one-off projects that quickly became outdated. Coordinating updates—especially when new versions of the Custom Elements API were released or when style updates were necessary—was time-consuming. In line with the Single Responsibility Principle, we decided to split our initiative into three distinct parts:
- Developer Resources and Documentation: We consolidated our best practices and documentation into a dedicated space, available at Kontent.ai Integrations. This ensures developers have a clear and comprehensive guide for creating custom elements.
- Guidepost Using GitHub Tags: To streamline the discovery of community-built elements, we transitioned our guidepost to leverage GitHub tags. Contributors can now mark their custom elements as searchable using the tagging conventions detailed in our Naming Conventions guide.
- Dedicated React.js Template Repository: We also established a standalone React.js template repository (custom-element-starter-react) that serves as a robust starting point for developers looking to build their own custom elements. This repository is actively maintained, allowing community members to pull in updates and enhancements as needed.
- List of Curated Integrations: Curated and maintained integrations that ensure a higher level of maintenance from Kontent.ai DevRel team.
Conclusion
This evolution has provided a more coherent and maintainable environment for custom element development at Kontent.ai. Creators now have access to robust resources and templates that simplify the process of building custom elements, while consumers benefit from a clear, searchable catalog of community innovations. Reflecting on our journey, I’m proud of how our collective efforts have empowered developers and enriched the Kontent.ai ecosystem, setting the stage for future innovation.