Structure your Application

Learn how to structure your application with additional entities and business logic

In the previous section we learned the fundamentals of how Makerkit's architecture works, and the layers of the application.

In this section, we learn how to structure your application in practical terms with an example. For example, your application has an entity "events": how do we add this entity to a Makerkit application?

NB: entities rarely (or never) get added to "core". Business domain is added to "components" and "lib".

In short, this is how we add a new entity to the application:

  1. First, we add a new folder to lib. If the entity is "event", we add lib/events.
  2. Then, we add the components of the event domain to components/events
  3. Finally, we add the pages of the event domain to pages/events
- src
  - components
    - events
      - EventsContainerComponent.tsx
      - ...

  - lib
    - events
      - types
        - event-model.ts
        - ...
      - hooks
        - use-fetch-events.ts
        - use-create-event.ts
        - ...
      - utils
        - create-event-model.ts

  - pages
    - events
      - index.tsx
      - [event].tsx

1) Adding the entity's business domain

In the lib/events folder, we will add various business logic units, such as types, custom hooks, API calls, factories, functions, utilities, and so on.

Types

First, we define a type EventModel at lib/events/types/event-model.ts:

export interface EventModel {
  name: string;
  description: string;
}

Custom Hooks

For example, let's write a custom hook that retrieves a list of "events" from a Firestore collection.

We create a file at lib/events/hooks/use-fetch-events.ts with the following content:

import EventModel from '~/lib/events/types/event-model.ts'

export function useFetchEvents() {
  const firestore = useFirestore();
  const eventsCollection = 'events';

  const collectionRef = collection(
    firestore,
    eventsCollection,
  ) as CollectionReference<EventModel>;

  return useFirestoreCollectionData(collectionRef, {
    idField: 'id',
  });
}

Good! We have a way to fetch our events, but we have to use it somewhere: to do so, let's create a component EventsListContainer.

NB: remember to update the Firestore rules to be able to read the collection.

2) Components

As said before, we add React components that belong to the "events" domain to components/events.

In the component below, we will fetch a list of events with useFetchEvents:

import { useFetchEvents } from '~/lib/events/hooks/use-fetch-events';
import { Alert } from `~/core/ui/Alert`;

const EventsListContainer: React.FC = () => {
  const { data: events, status } = useFetchEvents();

  if (status === `loading`) {
    return <p>Loading Events...</p>
  }

  if (status === `error`) {
    return (
      <Alert type='error'>
        Ops, we encountered an error!
      </Alert>
    );
  }

  return (
    <div>
      {events.map(event => {
        return (
          <div key={event.name}>
            <p>{event.name}</p>
            <p>{event.description}</p>;
          </div>
        );
      })}
    </div>
  )
};

export default EventsListContainer;

3) Pages

Finally, we can add the events component EventsListContainer to a page. To do so, let's create a page component at pages/events/index.ts:

import { GetServerSidePropsContext } from 'next';

import RouteShell from '~/components/RouteShell';
import EventsListContainer from '~/components/EventsListContainer';

import { withAppProps } from '~/lib/props/with-app-props';

const EventsPage: React.FC = () => {
  return (
    <>
      <Head>
        <title key="title">Events</title>
      </Head>
      
      <RouteShell title="Events">
        <EventsListContainer />
      </RouteShell>
    </>
  );
};

export default EventsPage;

// guard the page!
export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return withAppProps(ctx);
}

šŸŽ‰ That's it! We have now built a nicely structured "events" domain.


Stay informed with our latest resources for building a SaaS

Subscribe to our newsletter to receive updatesor