Hey fellow nerds. I have been working as a web dev in the TypeScript / headless world for the past decade and over the years some practices and conventions have proven to be very effective and scalable in production environments.
I hacked together a small POC framework / boilerplate tonight which I’d like to share with you. But let’s first take a look at why and how this framework was born out of proven real world concepts and architecture.
Take for example Redux quite a while ago. Immutable states and centralized state management had such an impact that React added a useReducer hook to the core.
Ever since useReducer has been available I haven’t really found a need for Redux anymore. Pure reducers can be used in a similar fashion to Redux and Sagas can easily be implemented with useEffect . However; a few principles stuck with me that simply made life easier because it just works.
One thing is to use an action based state management system which allows you to decouple state and state logic from layout and other business logic. By keeping reducers as pure functions and serializable actions we get all the goodies from the Redux world, like time travel debugging. State history. Replay. Rollbacks. All for free.
I figured the same principles apply to effects as well. So let’s keep them declarative and serializable — The idea is simple. Actions can produce effects and effects can produce actions. They just produce JSON that describes the Action / Effect.
No messy function calls; Everything that has no side effects is pure and serializable. Side effects become revertable; deterministic and I’m no mathematician, but abstracting side effects into descriptive JSON objects may make the more computable.
The only code that contains side effects are now effects which becomes very managable and now; when there’s an API call, database update or even only setting a cookie. You know that’s a side effect and it has to sit somewhere within an effect.
What GraphQL taught me is that data loading is much less of a PITA if you extract all your data fetching logic into static DataSources.
It’s just a collection of async functions that you can invoke through a common namespace but it makes things much less cluttered and fetching data usually is only one call to a data source api method.
You probably figured that I started to code JS way before SSR was a thing. There haven’t even been IDEs, build tools or anything beyond simple JavaScript files you could include with a script tag.
TypeScript was a game changer for the JavaScript world and Visual Studio Code finally gave as a tool to leverage all that static typing shenanigans.
When React came out; I remember that this was the one framework that gave me back all my childish enthusiasm and joy for the JavScript and web dev world. I loved it. I still do. (Note: It’s much better than Vue IMHO).
It quickly became obvious that we’d need SSR to overcome CSR limitations and when Next.js was born we were given yet another powerful tool to utilize proven tools from the world wide web.
Things went wild when Vercel was available as a platform and suddenly we have SSG, SSR and ISR all running on Vercels CDNs Edge near the user; serving statically prerendered pages blazingly fast. All for free.
I hope you see how amazing this is. Well, now here we are and working fulltime as fullstack/frontend dev shows that there’s huge commercial potential in putting all these technologies together.
CMS; Headless; React and Next.js are being used by big companies alike and building future proof; scalable and robust applications is a need; now more than ever.
This is where Mosaik comes in. It’s just a prove of concept for now, but it wires all those fancy technologies together into one easy to use boilerplate.
🧩 Mosaik — Build Sites from Themeable Components. Ship Static-Fast. Scale Forever.
Mosaik is an edge-first, themeable framework built on Next.js 15 — designed for sites that blend static speed with dynamic content from any headless CMS.
✨ Why Mosaik?
- Compose Like Lego: Every page is built from themeable components. No locked-in page builder — connect any headless CMS you prefer.
- Deploy Static, Update Live: ISR and edge caching keep your site always fresh — and blazing fast.
- Theme Anything, Tree-Shake Everything: Swap layouts & components at build or runtime — with server-side theming that’s fully tree-shakable for minimal bundle size.
- Pure State, Clear Effects: Mosaik’s state system uses fully serializable reducers & effects — proven Redux/Saga ideas, modernized with React hooks.
- No Vendor Lock: It’s just Next.js, your content, and your edge. No hidden runtime, no extra backend, no rent to pay.
🛠️ Status: Mosaik is experimental — it’s powering its own docs today (via Strapi on Railway). It’s small, open-source, and ready for your ideas. PRs welcome!
If you’re interested you can take a look at the Github repo here at https://github.com/SynTessera/Mosaik
The projects (very wip) documentation can be found here: https://mosaik.javascript.moe
I will continue to work and refine this architectual concept, but for the meantime I’d just like to publish it early on in hopes to get a bit of visibility, reach and feedback as the project grows.
If you’re still reading, here’s a bit more about the project:
⚠️ Disclaimer Mosaik is 100% a work in progress — currently an early-stage proof of concept. It’s just a small Next.js app exploring flexible theming, composable state, and modern data-driven rendering. Anyone who wants to help is welcome to contribute! Please feel free to open issues, share ideas, or create PRs — all collaboration is very welcome.
🧩 About Mosaik
Mosaik is a modern, opinionated frontend framework designed for building highly composable, themeable, and data-driven user interfaces — without sacrificing developer control or performance.
At its core, Mosaik helps you think of your application as a living mosaic: a dynamic arrangement of reusable, self-contained pieces — slots, themes, actions, and data providers — that adapt fluidly to your users’ needs, your design system, and your content sources.
✨ Why Mosaik?
Today’s digital products demand more than static pages and brittle components. Mosaik is built for teams who want:
- Composability — break your UI into isolated, discoverable slots and actions.
- Dynamic theming — swap out slots and components at runtime or design time, without rewriting your logic.
- Data as a first-class citizen — inject, transform, and consume structured data from multiple sources using intuitive, declarative providers.
- Isomorphic rendering — render the same building blocks on the server for fast, SEO-friendly output, but hydrate them on the client for rich interactivity.
- Flexibility — use Mosaik’s minimal conventions to shape your own design system, your own CMS backend, and your own rendering logic — no lock-in.
🧩 Key Concepts
✅ Slots
Every piece of UI is a slot: an isolated, replaceable area you can render with a themed component. Want to restyle your Header, Sidebar, or ListItem? Just swap the slot renderer.
✅ Themes
Themes are structured maps of slots, components, and tailwind classes. Mosaik’s theme system lets you dynamically switch components or styles based on user preferences, brand context, or device mode.
✅ Actions
Actions describe the possible interactions in your app: they’re exposed by providers and consumed by views. This makes it trivial to conditionally render buttons, toggles, or menus based on your app’s state.
✅ State Providers
Manage local or global app state using React’s modern useReducer pattern, with clear boundaries for server vs. client responsibilities.
✅ Data Providers
Connect your views to any source: a headless CMS, an API, or static JSON. Providers abstract data fetching, shape-checking, and caching so your components stay clean and declarative.
🔗 Where Mosaik Fits
Mosaik is not a new rendering engine — it’s a compositional layer that lives on top of React (and frameworks like Next.js). It embraces React Server Components and modern React patterns for hybrid static + dynamic rendering.
Whether you’re:
- Building a marketing site with personalized sections,
- Crafting a dashboard with dynamic widgets,
- Or assembling a fully CMS-powered app that editors can reconfigure at runtime…
Mosaik gives you the primitives to scale it all elegantly — without rigid page builders or monolithic component trees.
🚀 Built for teams
Mosaik works best when designers, developers, and content editors collaborate:
- Designers define slots and themes.
- Developers wire up state, actions, and data providers.
- Editors feed structured content via your CMS of choice.
Everything stays decoupled — yet works seamlessly together.
🗂️ What’s next?
- Dive into Getting Started to create your first slots and themes.
- Learn how to wire up a headless CMS.
- Discover best practices for mixing server-side rendering with client-side interactivity.
- See advanced examples of how to override, merge, and reuse slots across different contexts.
🧩 Mosaik — your UI, piece by piece.
Thanks for bearing with me until here 🥰🙏
Have a potato on the way my fellow coding enthusiasts