Back to Blog

Best practices and design guidelines of the Maui framework

Best practices and design guidelines of the Maui framework

The Maui framework is a lightweight, full-stack framework that provides developers with a powerful toolset to build rich web applications. It is a lightweight, modular and flexible platform that can be used to develop web applications as well as mobile apps. It's designed to be simple, flexible, and scalable. There are no dependencies, so you can just download it and start using it right away.

Maui uses MVC architecture as its core design pattern. The model represents the data in your application; the view displays the model on screen; and then there is a controller which controls how the view looks like. The Maui framework is designed to be used with a React-based front-end, but it can also be used with other UI frameworks or even without one.

The framework is divided into three major parts:

  1. Maui Core - The core library which provides basic functionality for every application.
  2. Maui Router - The router library provides components for creating a powerful navigation system for your application.
  3.  Maui CLI - A command-line interface (CLI) tool which allows you to create, develop, build and run your Maui project locally or on cloud servers like Digital Ocean or AWS EC2.

Maui comprises of different components such as:

  1. The core- It provides the foundation for the rest of the framework, including its routing system, middleware support, and more.
  2. The component library-It provides common user interface components that you can use in your application(such as modals, tooltips, etc.).
  3. The third-party library- This provides integration with other libraries such as jQuery UI or Bootstrap.

MAUI’s Main Features

Maui's main goal is to improve developer productivity by making it easier to build and maintain large applications with React. It does this by providing features like:

  1. An application inspector tool (Maui-inspector) - that lets you troubleshoot problems in production without having to rely on expensive developer tools like Chrome Dev Tools or console.log()statements everywhere in your codebase.
  2. A server-side rendering library (Maui-server) - that's compatible with all major browsers.
  3. A universal bundle analyzer (Maui-analyzers) -  that helps you keep track of your app's size and performance over time.
  4. React-style APIs(actions and reducers) - Actions are pure functions that describe the change you want to make to your application's state. Reducers are also pure functions that take two arguments: previous state and current action. The reducer returns new state for your application based on the action provided as input.
  5. Immutability - Maui usesImmutable.js data structures for its state, which means all updates happen in place instead of changing references to data items. This makes it easier for developers to reason about their code because it doesn't rely on mutation.
  6. Modularity — Maui has been built from the ground up as a collection of small components that can be used individually or together to build larger apps. This makes it easy to pickup where you left off in another project, or just to share small pieces of functionality between projects.
  7. Performance — Maui has been optimized for performance so your users don’t have to wait long after clicking “Save”.
  8. Configuration — Maui uses sane defaults so that you don’t have to configure anything unless you want to change something specific.
  9. An opinionated component structure – that reduces boilerplate, makes code more consistent, and simplifies debugging and testing.
  10. A declarative data-fetching API – that eliminates the need for imperative code, meaning you can focus on what your app looks like instead of how it works under the hood.
  11. An optional store-agnostic state management layer that lets you use Redux or MobX without sacrificing the benefits of Maui’s component model.
  12. Maui uses Redux as its state management library; this helps you save and manage data in one place called “store”. You can use reducers to read and change values in your store; they are pure functions that accept an action object as input and return a new state object based on that action object’s type and payload.
  13. The Maui framework uses the Observable Data Services (ODS) pattern, which allows developers to manage data changes in an observable and testable manner.
  14. The Maui framework uses the Flux architecture, which enables you to separate concerns and create reusable modules that can be easily tested

Here are some of the best practices and design guidelines of the Maui framework:

  1. It’s recommended to stick with the standard layouts provided by Maui. If you have some special needs like creating an unusual layout or customizing an existing one, then feel free to create your own layouts but don’t try to change them often since it may cause unexpected issues when something goes wrong in future releases.
  2. Avoid using tabs as much as you can because they’re not very user-friendly, especially on mobile devices. If you need tabs, use them as part of your navigation bar instead of creating separate views for each tab. Tabs should also be used only when you have more than three screens!
  3. Use non-breaking spaces (nbsp) for padding instead of hard spaces ( ). Maui uses hard spaces for padding which might cause issues if you’re using other frameworks that also use them as separators between elements (for example Foundation). So its better to avoid using them altogether and use nbsp instead – they’re less common anyway so there’s less chance of conflicts with other frameworks’ CSS stylesheet.
  4. Use a preprocessor to generate CSS from your stylesheet – Use a preprocessor to generate CSS from your stylesheet. This way you’ll be able to use variables, functions, imports, etc. in your Sass files. It’s also easier to configure your project by setting up variables and importing other files. In addition, the compiled CSS will be much more efficient than it would have been if you had written all of it yourself.
  5. Use a Sass linter to enforce consistent syntax and avoid bugs. – A linter can help you enforce consistent syntax and avoid bugs — both are very important aspects of writing good code! With a linter installed you can also add new properties as they become available without having to worry about forgetting them while maintaining compatibility with older browsers using CSS-Packs or feature queries. If you want to write cleaner code there are tools like Scout or Stylelint that can help you do so by detecting errors in your CSS or SCSS files before deploying them to production servers (which is where most of these errors occur).
  6. Use inheritance when appropriate, but avoid using it just for convenience. When deciding between two classes, use the one that has more specific responsibilities or is more cohesive with other code in your project.
  7. Wherever possible, use private methods instead of public ones. Private methods are easier to test and easier to change in the future if you change your mind about their implementation details.
  8. Try to avoid overusing singletons or static methods, especially if they have side effects like database accesses or logging. They can be useful at times, but they should be used sparingly because they can lead to code that’s difficult to read and test.
  9. Keep things simple by writing short functions that do one thing well rather than long functions that do many things poorly. If a function becomes too long, consider breaking it up into smaller functions — this will make it easier for other developers (and yourself!) to understand what’s going on in each function without having to look at all its
  10. Use the MVC pattern – The MVC pattern is a popular software design pattern that separates an application into three components: model, view and controller. The model contains the business logic of your application, while views display information to users in a way they can see and understand. Controllers handle user requests and communicate with models and views to process them. In Maui, these components are represented as classes, so it’s easy to follow this pattern.
  11. Use dependency injection – Dependency injection is an important part of any modern application because it allows you to write code that doesn’t need to know about the services it depends on. Instead, those dependencies are provided by other classes or modules at runtime. This makes your code more flexible because you can change dependencies without having to rewrite code everywhere in your application. It also makes it easier for developers to test their applications because they don’t have to create mock objects manually every time they want to write tests — they just inject mocked dependencies into their class or module with dependency injection frameworks like Dagger 2 or Koin/Kodein (both available as plugins for Maui).
  12. Use case-driven structuring – Separate each use case into its own module, so that you can focus on one feature at a time. This allows you to easily refactor and maintain your code base. It also allows for easier testing because each use case has its own set of tests that can be run independently from each other.
  13. Use contexts for state management – Maui uses contexts for managing state, which makes it easy to reason about how your application will behave. Contexts allow you to store values locally while keeping them separate from external dependencies like databases or external APIs. Contexts are often used in frontend code as well as backend code where they can be passed around between controllers and other modules that require it.
  14. Model-based views: The Maui documentation suggests that you should use model-based views instead of page-based views. This means that your view functions return data from your models instead of rendering HTML directly. This makes it easier to test your views because they depend on your models only. Additionally, you can reuse these view functions throughout your application without having to duplicate code unnecessarily.
  15. Keep your components small. Maui is designed to be used for building large, complex applications. The larger your application is, the more difficult it will be to refactor it later on. Thus, it’s important that you keep your components as small as possible. This will make them easier to understand, easier to test and easier to maintain in the future.
  16. Don’t use static methods unless they’re absolutely necessary. Static methods don’t have any type safety because they aren’t bound by any class instance; thus, they can be used by any object in a program regardless of their type or where they’re located within memory. This lack of type safety can lead to runtime errors if your program attempts.
  17. Keep it simple: Don’t overuse classes or add too much markup into your HTML files because it will make them less readable, especially when working as part of a team where everyone can make edits to them at any time.
  18. Don’t ever use tags – The template tag is a new HTML5 feature that allows you to create templates for your application components. You can render any component inside a template tag and then inject it into other parts of your application.
  19. Use a singleton for Hibernate SessionFactory or JPA EntityManagerFactory – This is another best practice that you should follow while building your application with an IoC container. You can use this singleton to create an instance of Hibernate SessionFactory or JPA EntityManagerFactory in your application, which will give you access to transaction management and other features offered by these frameworks.
  20. Use a singleton for JDBC DataSource – You can use this approach to create an instance of JDBC DataSource in your application, which will help you manage transactions and other features offered by this framework.
  21. Don’t use static methods in your business classes – This is one of the most common mistakes made by developers while building their applications using any IoC container like Spring or Guice . If you want to use dependency injection in your business classes, then you should avoid using static methods on them because it makes it difficult for other developers working on the project to test them independently from one another.
  22. Use segues instead of push or present methods whenever possible. Segues are much easier to manage and update in case something goes wrong later on down the road.
  23. Use reactive streams to define your data model, so that your application can respond to changes in real-time.
  24. Use a single window per view controller for each screen in your app. The navigation bar should contain only actions related to that screen and should always be visible at all times.
  25. Use RxJava2 to compose asynchronous sequences of events into a single sequence using operators like map, filter and flatMap.
  26. Use Subjects to broadcast events to multiple subscribers and create independent streams of events without requiring any external entity to coordinate them.
  27. Use Data Flow Operators (e.g., merge) when you need more control over how your data is processed than what’s provided by RxJava2 (e.g., if you want to run multiple transformations on an input stream).


We hope this was a helpful walkthrough of some core features, functionality, best practices and design guidelines of the Maui framework. Integrating a new framework into an app can be a challenging and daunting task, especially as a beginner.

The Maui framework is a pretty ambitious approach to application development, and it’s something you should take seriously if you’re looking forward to building your own cross-platform apps. It’s important to understand what these guidelines mean, both in terms of the specific programming rules, and the reasoning behind them. Together with this knowledge, you can make informed decisions about how to approach your development goals for reliability and future scalability. Moreover, if you want to develop a web app or mobile app yourself, this blueprint is an excellent guide for developing Maui applications.

Atul Koshta

Sign up Now

Do you have a project in mind? Subscribe to the newsletter and get info, tips and suggestions on how your idea can succeed

Thanks for joining our newsletter.
Oops! Something went wrong.