Tutorials


This tutorial is a comprehensive guide to getting started with the Remix and Firebase SaaS template to build a basic tasks application, from fetching the repository to deploying the application.

By the end, you'll have a fully working application with the minimum basics a SaaS needs:

1. Landing Page and Marketing pages (blog, documentation)
2. Authentication (sign in, sign up)
3. Payments (Stripe)
4. Profile and Organization management

## Prerequisites

To get started, you're going to need some things installed:

1. Git
2. Node.js version (>=16.0.0)
3. npm 7 or greater
4. A code editor (VSCode, WebStorm)
5. If you'd like to deploy your application, you'll also want an account on Vercel.

Experience with React, TypeScript/JavaScript, and Firebase would be advantageous but not strictly required. The codebase can also serve as a way to learn these topics more in-depth.

If you have all the above installed, I guess we can get started!

Get a head start on your app development with our Makerkit SaaS boilerplate, built with Remix and Firebase. Follow our step-by-step guide for an easy setup!

Building a SaaS tasks application with Makerkit


## Initializing the Project

You have two ways to initialize the project:

1. Forking it from GitHub, or
2. Cloning it using Git

### 1. Forking the Repository

Fork this repository by clicking on the "Fork" button on the top right
corner in GitHub for the repository you want to use.

Once you have forked the repository, clone it locally. Then, set the
upstream repository to the original repository, so you can pull updates
when needed:

```
git remote add upstream git@github.com:makerkit/remix-firebase-saas-kit.git
```

### 2. Cloning the Repository

Alternatively, assuming you have accepted the invites and have access to the repository, open your terminal and run this command (replace `tasks-app` with your name of choice):

```
git clone --depth=1 git@github.com:makerkit/remix-firebase-saas-kit.git tasks-app
```

Once completed, we'll change into the `tasks-app` directory, and then we will install the Node modules:

```
cd tasks-app
npm i
```

### Reinitialize Git

As the Git repository's remote points to Makerkit's original repository, you can re-initialize (optionally!) it and set the Makerkit repository as `upstream`:

```
rm -rf .git
git init
```

Then, we set the Makerkit repository as `upstream`:

```
git remote add upstream git@github.com:makerkit/remix-firebase-saas-kit.git
git add .
git commit -a -m "Initial Commit"
```

By adding the Makerkit's repository as `upstream` remote, you can fetch updates (after committing your files) by running the following command:

```
git pull upstream main --allow-unrelated-histories
```

Perfect! Now you can fire up your IDE and open the `tasks-app` project we just created.

This section describes how to set up your development environment to use the Remix Firebase SaaS template, from forking the repository to installing the Node modules

Initial Setup


When inspecting the project structure, you will find something similar to the below:

```
tasks-app
├── README.md
├── @types
├── src
│   ├── components
│   ├── core
│   ├── lib
│   └── routes
        └── __app
        └── __site
        └── auth
        └── invite
        └── onboarding
│       └── root.tsx
├── package-lock.json
├── package.json
├── public
│   └── favicon.ico
└── tsconfig.json
```

NB: we omitted a lot of the files for simplicity.

Let's take a deeper look at the structure we see above:

- `src/core`: this folder contains reusable building blocks of the template that **are not related to any domain**. This includes components, React hooks, functions, and so on.
- `src/components`: this folder contains the application's components, including those that belong to your application's domain. For example, we can add the `tasks` components to `src/components/tasks`.
- `src/lib`: this folder contains the business logic of your application's domain. For example, we can add the `tasks` hooks to write and fetch data from Firestore in `src/lib/tasks`.
- `src/routed`: this is Remix folder where we add our application
routes.

Don't worry if this isn't clear yet! We'll explain where we place our files in the sections ahead.

A quick overview of the project structure and how to navigate it.

Project Structure


When we run the stack of a Makerkit application, we will need to run a few commands before:
1. **Remixs**: First, we need to run the Remix development server
2. **Firebase**: We need to run the Firebase Emulators. The emulators allow us to run a fully-local Firebase environment.
3. **Stripe CLI** (optional): If you plan on interacting with Stripe, you are also required to run the Stripe CLI, which allows us to test the webhooks from Stripe against our local server.

### Running the Remix development server

Run the following command from your IDE or from your terminal:

```
npm run dev
```

This command will start the Remix server at [localhost:3000](http://localhost:3000). If you navigate to this page, you should be able to see the landing page of your application:

<Image src='/assets/images/posts/tutorial-landing-page.webp' width="2856" height="1972" />

### Running the Firebase Emulators

To interact with Firebase's services, such as Auth, Firestore, and Storage, we need to run the Firebase emulators. To do so, open a new terminal (or, better, from your IDE) and run the following command:

```
npm run firebase:emulators:start
```

If everything is working correctly, you will see the output below:

```
┌────────────────┬────────────────┬─────────────────────────────────┐
│ Emulator       │ Host:Port      │ View in Emulator UI             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Authentication │ localhost:9099 │ http://localhost:4000/auth      │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Firestore      │ localhost:8080 │ http://localhost:4000/firestore │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Pub/Sub        │ localhost:8085 │ n/a                             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Storage        │ localhost:9199 │ http://localhost:4000/storage   │
└────────────────┴────────────────┴─────────────────────────────────┘
  Emulator Hub running at localhost:4400
  Other reserved ports: 4500, 9150
```

By default, we run the emulator for the following services: Authentication, Firestore, and Storage. However, you can easily add Firebase Functions and PubSub.

#### Firebase Emulator UI

As you can see from the `View in Emulator UI` column, you have access to the Emulator UI, which helps you see and edit your Firebase Emulator data using a nifty UI that resembles the Firebase Console.

For example, to display the list of users that have signed up, navigate to the [Authentication Emulator](http://localhost:4000/auth).

<Alert type='info'>
  Makerkit's template adds some data to your project by default for testing reasons. In fact, the data you see is used to run the Cypress E2E tests. This is why you'll see some pre-populated data in your Firestore and Authentication tabs.
</Alert>

### Running the Stripe CLI (optional)

Optionally, if you want to run Stripe locally (e.g., sending webhooks to your local server), you will also need to run the following command:

```
npm run stripe:listen
```

This command requires Docker, but you can alternatively install Stripe on your OS and change the command to use `stripe` directly.

The above command runs the Stripe CLI and will route webhooks coming from Stripe to your local endpoint. For example, in the Makerkit starter, this endpoint is `/resources/stripe/webhook`.

When running the command, it will print a webhook key used to sign the messages from Stripe. You will need to add this key to your local environment variables file as below:

```
STRIPE_WEBHOOK_SECRET=<KEY>
```

The webhook printed should not change, so you may only need to do this the first time.

Learn how to run the app locally for development and testing.

Running the App


Makerkit can be configured from a single place: the `src/configuration.ts` object. This file exports a constant we use throughout the project to read our application's settings.

<Alert type='info'>
  <Alert.Heading>
    Use this file to configure your project
  </Alert.Heading>

  We recommend adding additional configuration to this file rather than reading it directly from the environment variables. For example, assuming you rename one of your environment variables, you will only need to update it in one place. Additionally, it helps maintain your codebase more explicit and understandable.
</Alert>

We retrieve some of this file's configuration using **environment variables**: these help us swap and tweak our settings based on which environment we're using, such as the Firebase configuration.

For example, in your Vercel console, you could run multiple projects:
- one for `production`
- and one for `staging`

Here is what the configuration file looks like:

```tsx title="src/configuration.ts"
const configuration = {
  site: {
    name: 'Awesomely - Your SaaS Title',
    description: 'Your SaaS Description',
    themeColor: '#ffffff',
    themeColorDark: '#0a0a0a',
    siteUrl: process.env.SITE_URL as string,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
  },
  firebase: {
    apiKey: process.env.FIREBASE_API_KEY,
    authDomain: process.env.FIREBASE_AUTH_DOMAIN,
    projectId: process.env.FIREBASE_PROJECT_ID,
    storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.FIREBASE_APP_ID,
    measurementId: process.env.FIREBASE_MEASUREMENT_ID,
  },
  auth: {
    // Enable MFA. You must upgrade to GCP Identity Platform to use it.
    // see: https://cloud.google.com/identity-platform/docs/product-comparison
    enableMultiFactorAuth: false,
    // NB: Enable the providers below in the Firebase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: [GoogleAuthProvider],
    },
  },
  emulatorHost: process.env.EMULATOR_HOST,
  emulator: process.env.EMULATOR === 'true',
  production: process.env.NODE_ENV === 'production',
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    onboarding: `/onboarding`,
    appHome: '/dashboard',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/resources/stripe/checkout`,
      billingPortal: `/resources/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  navigation: {
    style: LayoutStyle.Sidebar,
  },
  appCheckSiteKey: process.env.APPCHECK_KEY,
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
    senderAddress: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  sentry: {
    dsn: process.env.SENTRY_DSN,
  },
  stripe: {
    plans: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        price: '$249/year',
        stripePriceId: 'basic-plan',
        features: [
          'Feature 1',
          'Feature 2',
          'common:plans.features.feature1'
        ],
      },
    ],
  }
};
```

Feel free to extend this configuration to your needs. For example, you could new properties to the `site` object to store your social media handles, or add new properties to the `paths` object to store the paths to your pages.


Learn how to set up up your project's configuration

Project Configuration


The starter project comes with two different environment variables files:
1. **.env**: the main environment file
2. **.env.test**: this environment file is loaded when running the Cypress
E2E tests. You would rarely need to use this.

NB: the `.env` file is never committed to the repository. This is because it
contains sensitive information, such as API keys. Instead, we use a `.env.
template` file to show what the `.env` file should look like.

The environment variables in your project will look like the below:

```bash
DEFAULT_LOCALE=en
EMULATOR=true
SITE_URL=http://localhost:3000
REQUIRE_EMAIL_VERIFICATION=false

# FIREBASE
GCLOUD_PROJECT=demo-makerkit
FIREBASE_PROJECT_ID=demo-makerkit
FIREBASE_STORAGE_BUCKET=demo-makerkit.appspot.com
FIREBASE_AUTH_DOMAIN=localhost
FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=

# Change this with your project's APP ID
FIREBASE_APP_ID=1:981813564016:web:f13148231721fcd0ee5ab5
# Change this with your project's API KEY
FIREBASE_API_KEY=AIzaSyAAqU_euGAMtJoXp0sECblAIndifCp0pmE

# FIREBASE EMULATOR
FIRESTORE_EMULATOR_HOST=localhost:8080
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIREBASE_STORAGE_EMULATOR_HOST=localhost:9199
FIREBASE_PUBSUB_EMULATOR_HOST=localhost:8085
FIREBASE_EMULATOR_HOST=localhost
FIRESTORE_EMULATOR_PORT=8080
FIREBASE_AUTH_EMULATOR_PORT=9099
FIREBASE_STORAGE_EMULATOR_PORT=9199

# TESTING EMAILS. MAKE AN ACCOUNT ON ETHEREAL AND ADD THE CREDENTIALS BELOW
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=

# SERCET KEY TO SIGN SECRETS. REPLACE THE BELOW WITH A RANDOM AND COMPLEX STRING. KEEPT IT SAFE.
SECRET_KEY=123456789

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=

# APPCHECK
APPCHECK_KEY=
APPCHECK_DEBUG_TOKEN=
```

### Define your environment variables in your hosting provider

**NB**: Remix will not bundle environment variables when building your app, but only during development mode.

Instead, you will need to define them in your hosting provider (such as your Vercel project settings).

Learn how to use environment variables in your Remix project.

Environment Variables


This SaaS template uses Tailwind CSS for styling the application.

You will likely want to tweak the brand color of your application: to do so, open the file `tailwind.config.js` and replace the `primary` color (which it's `indigo` by default):

```js title="tailwind.config.js"
extend: {
  colors: {
    primary: {
      ...colors.indigo,
      contrast: '#fff',
    },
    black: {
      50: '#525252',
      100: '#363636',
      200: '#282828',
      300: '#222',
      400: '#121212',
      500: '#0a0a0a',
      600: '#040404',
      700: '#000',
    },
  },
},
```

### Updating the Primary color of your app

To update the `primary` color, you can either:

1. choose another color from the Tailwind CSS Color palette (for example, try `colors.blue`)
2. define your own colors, from `50` to `900`

The `contrast` color will be helpful to define the text color of some components, so tweaking it may be required.

Once updated, the Makerkit's theme will automatically adapt to your new color palette! For example, below, we set the primary color to `colors.blue`:

<Image src='/assets/images/posts/blue-dark-theme.webp' width="2842" height="1966" />

### Dark Mode

Makerkit also ships with a dark theme.

The light theme is the default, but users can switch to the other, thanks to the component `DarkModeToggle`.

If you wish to only use one theme, you can tweak the configuration using the following flag in the configuration file `~/configuration.ts`:

```ts title="~/configuration.ts"
{
  ...
  enableThemeSwitcher: false,
  ...
}
```

## Caveats

1. Setting the dark theme by default is currently not supported without some minor tweaks. It is being developed.
2. The default Tailwind media switcher is not supported since Makerkit uses its own system that allows users to choose the System theme (light or dark) or the theme defined by the application.

Learn how to configure Tailwind CSS and tweak the Makerkit's theme.

Tailwind CSS and Styling


The Remix/Firebase template uses Firebase Auth to manage authentication into the internal application.

The kit supports the following strategies:

1. Email/Password
2. oAuth Providers such as Google, Twitter, Facebook, Microsoft, Apple, etc.
3. Phone Number
4. Email Link

You can choose one, more, or all of them together, and you can easily tweak this using the global configuration.

By default, our SaaS Starter uses Email/Password and Google Auth.

### How does Authentication work?

First, let's just take a high-level overview of how Makerkit's authentication works.

MakerKit **uses SSR throughout the application**, except for the marketing pages. Using SSR, we can persist the user's authentication on every page and access the user's object on the server **before rendering the page**.

This can help you both in terms of UX and DX. In fact, persisting the user's session server-side can help you in various scenarios:

- Simplifying the business logic: for example, checking server-side if a user can access a specific page before rendering that page
- Rendering the user's data server-side by fetching some data from Firestore in the `getServerSideProps` function

#### How does SSR work?

To enable SSR with Firebase Auth, we use [Session Cookies](https://firebase.google.com/docs/auth/admin/manage-cookies).

1. First, we use the Firebase Auth Client SDK to sign users in, as described in every tutorial. Furthermore, when a user signs in or signs up, we retrieve the ID Token and make a request to our API to create a session cookie. The session cookie remains valid for 14 days, after which it will expire.
2. The cookie `sessionId` gets stored as an HTTP-only cookie: we can use this server-side for fetching the current user.
3. When the token expires, we sign users out of the application

So... how do they work?

1. The client SDK uses the Firebase Auth credentials stored in the IndexedDB Storage. This includes interacting with Firebase Storage and Firebase Firestore on the client side.
2. The server-side API uses the `sessionId` cookie to retrieve and authenticate the current user. We can then use the Firebase Admin API and interact with the various Firebase services.

### Authentication Strategies

To add or tweak the authentication strategies of our application, we can update the configuration:

```tsx title="src/configuration.ts"
auth: {
  // Enable MFA. You must upgrade to GCP Identity Platform to use it.
  // see: https://cloud.google.com/identity-platform/docs/product-comparison
  enableMultiFactorAuth: false,
  // NB: Enable the providers below in the Firebase Console
  // in your production project
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: [GoogleAuthProvider],
  },
},
```

Above, you can see the **default configuration**. It should look like the following:

<Image src='/assets/images/posts/tutorial-sign-in.webp' width="2834" height="1972" />

Ok, cool. But what if we wanted to swap `emailPassword` with `emailLink` and add `Twitter oAuth`?

We will do the following:

```tsx title="src/configuration.ts"
import { GoogleAuthProvider, TwitterAuthProvider } from 'firebase/auth';

auth: {
  // Enable MFA. You must upgrade to GCP Identity Platform to use it.
  // see: https://cloud.google.com/identity-platform/docs/product-comparison
  enableMultiFactorAuth: false,
  // NB: Enable the providers below in the Firebase Console
  // in your production project
  providers: {
    emailPassword: false, // set this to false
    phoneNumber: false,
    emailLink: true, // set this to true
    oAuth: [GoogleAuthProvider, TwitterAuthProvider],
  },
},
```

And the result will be similar to the image below:

<Image src='/assets/images/posts/tutorial-sign-in-email-link.webp' width="2834" height="1972" />

#### Custom oAuth providers

Additionally, we can add custom oAuth providers, such as `Microsoft` and `Apple`:

```tsx
class MicrosoftAuthProvider extends OAuthProvider {
  constructor() {
    super('microsoft.com');
  }
}

class AppleAuthProvider extends OAuthProvider {
  constructor() {
    super('apple.com');
  }
}
```

Then, you will add these classes to the `auth.providers.oAuth` object of the configuration.

<Alert type='warn'>
  Remember that you will always need to enable the authentication methods you want to use from the Firebase Console once you deploy your application to production
</Alert>

### Creating Accounts

Users can be redirected to the [Sign Up page](http://localhost:3000/auth/sign-up) to create an account.

### Requiring Email Verification

By default, Firebase does not require users to verify their email address before being able to access the application. It is a flag on the user account, but the user is not prevented from accessing the application.

We solve this server-side by checking if the user has verified their email address before rendering the page.

To enable this feature, you can set the `requireEmailVerification` flag to `true` using the following environment variable:

```bash title=".env"
NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION=true
```

Learn about the authentication strategies supported by Makerkit and how to configure them.

Authentication


After sign-up, users are redirected to the onboarding flow.

Here, you can ask users questions, configure their accounts or simply show them around.

By default, Makerkit adds one single step, where it asks users to **create an organization**.

<Image src="/assets/images/posts/onboarding-flow-tutorial.webp" width="2940" height="1972" />

Of course, you can extend it and add as many steps as you wish. I would recommend replacing the image on the right-hand side with a screenshot of your application, a video, or something that can help users understand what they are signing up for.

### What happens when the user submits the form?

After the user submits the form, the API will receive the request and:

1. create the user Firestore record at `/users`
2. create the organization Firestore record at `/organizations` and assign the user as its owner

I encourage you to visit the [Firestore Emulator UI](http://localhost:4000/firestore/) and see the data created.

### What is an "Organization"?

Organizations are groups of users.

You can call them projects, teams, classrooms, or whatever feels suitable for your domain. But, generally speaking, organizations are the backbone of the data model because it's where we store most of the data shared among users.

Users can:

1. create new Organizations
2. be invited to other Organizations
3. switch between organizations using a dropdown

### Can I remove this step?

No, **but you can skip it** by automatically submitting the form.

Yes, you can follow this guide for [removing the onboarding flow and organizations](/recipes/removing-organizations).

Learn how to onboard your users to your app using the Onboarding Flow.

Onboarding Flow


It's time to work on our application's value proposition: adding and tracking tasks! This is likely the most exciting part for you because **it's where you get to change things and add your SaaS features to the template**.

### Folder Structure

Before getting started, let's take a look at the default page structure of the boilerplate is the following.

```txt
├── routes
  └── root.tsx
  └── auth.tsx
  └── invite.tsx

  └── __app.tsx
  └── __site.tsx

  └── onboarding
      └── index.tsx

  __site
    └── auth.tsx
      └── faq.tsx
      └── pricing.tsx

  └── __auth
    └── link.tsx
    └── password-reset.tsx
    └── sign-in.tsx
    └── sign-up.tsx

  └── invite
    └── $code.tsx

  └── __app
    └── dashboard
      └── index.tsx

    └── settings
      └── organization
        └── members
          └── index.tsx
          └── invite.tsx

      └── profile
        └── index.tsx
        └── email.tsx
        └── password.tsx
        └── authentication.tsx

      └── subscription

  └── index.tsx
```

The routes are split in the following way:

1. The website's pages are placed under `__site`
2. The auth pages are placed under `__auth`
3. The internal pages (behind auth) pages are placed under `__app`

Some pages in the "middle" are placed outside `__app`, such as the Invites page and the Onboarding flow. These require custom handling.

### Setting the application's Home Page

By default, the application's home page is `/dashboard`; every time the user
logs in, they're redirected to the page `src/routes/__app/dashboard/index.tsx`.

You can update the above by setting the application's home page path at `configuration.paths.appHome`.

Unless you want to change the application's home page, **you can skip this section**, but it's good to know.

### Demo: Tasks Application

Our demo application will be a simple tasks management application. We will be able to create tasks, list them, mark them as completed, and delete them.

Here is a quick demo of what we will build:

<Video src="/assets/images/posts/tasks-demo.mp4" />

### Routing: Adding the Tasks Pages

Ok, so we want to add three pages to our application:

1. **List**: A page to list all our tasks
2. **New Task**: Another page to create a new task
3. **Task**: A page specific to the selected task

To create these two pages, we will create a folder named `tasks` at `src/routes/__app/tasks.`

In the folder `src/routes/__app/tasks` we will create three `Page Components`:

1. **List Page**: we create a page `index.tsx`, which is accessible at the path `/tasks`
2. **New Task Page**: we create a page `new.tsx`, which is accessible at the path `/tasks/new`
3. **Task Page**: we create a page `$id.tsx`, which is accessible at the path
`/tasks/<taskID>` where `taskID` is a dynamic variable that refers to the actual ID of the task

```txt
├── routes
  └──__app
    └── tasks
    └── index.tsx
    └── new.tsx
    └── $id.tsx
```

### Adding Functionalities to your application

To add new functionalities to your application (in our case, tasks management), usually, you'd need the following things:

1. Add a new page, and the links to it
2. Add the components of the domain and import them into the pages
3. Add data-fetching and writing to this domain's entities

The above are the things we will do in the following few sections. To clarify further the conventions of this boilerplate, here is what you should know:

1. First, we want to define our data model
2. Once we're happy with the data model, we can create our Firestore hooks to write new tasks and then fetch the ones we created
3. Then, we import and use our hooks within the components
4. Finally, we add the components to the pages

### Adding page links to the Navigation Menu

To update the navigation menu, we need to update the `NAVIGATION_CONFIG`
object in `src/navigation-config.tsx`.

```ts
const NAVIGATION_CONFIG = {
  items: [
    {
      label: 'common:dashboardTabLabel',
      path: configuration.paths.appHome,
      Icon: ({ className }: { className: string }) => {
        return <Squares2X2Icon className={className} />;
      },
    },
    {
      label: 'common:settingsTabLabel',
      path: '/settings',
      Icon: ({ className }: { className: string }) => {
        return <Cog8ToothIcon className={className} />;
      },
    },
  ],
};
```

To add a new link to the header menu, we can add the following item in the `NAVIGATION_CONFIG` object:

```tsx
{
  label: 'common:tasksTabLabel',
  path: '/tasks',
  Icon: ({ className }: { className: string }) => {
    return <Squares2X2Icon className={className} />;
  },
},
```

The result will be similar to the images below:

<Image src="/assets/images/posts/sidebar-layout-link.webp" width="1280" height="984" />

Learn how to get started developing new features in your app

Development: adding custom features


Before writing the Components, we want to tackle the task of fetching data from Firestore.

This involves a couple of steps:

1. We need to define, on paper, what the data model of the Firestore collections looks like
2. We need to update the Firestore rules so we can read and write data to the collection
3. We need to write the hooks to fetch data from Firebase Firestore

#### Firestore Data Model

First, let's write the data model. But... what does it mean?

When thinking about the Firestore data model, we need to answer the following questions:

1. Where does the data live?
2. How is the data structured?
3. How do we protect the data with security rules?

Ok, let's reply to these questions.

##### Where does the data live?

We can place `tasks` as a Firestore top-level collection. Because tasks belong to an organization, we can ensure that only users of that organization can read and write those tasks by adding a foreign key to each `task` named `organizationId`.

##### How is the data structured?

We can define a `Task` model at `src/lib/tasks/types/task.ts`:

```tsx title="src/lib/tasks/types/task.ts"
export interface Task {
  name: string;
  description: string;
  organizationId: string;
  dueDate: string;
  done: boolean;
}
```

##### How do we protect the data with security rules?

To write our Security Rules, we will update the file `firestore.rules`:

```
match /tasks/{taskId} {
  allow create: if userIsMemberByOrganizationId(incomingData().organizationId);
  allow read, update, delete: if userIsMemberByOrganizationId(existingData().organizationId);
}
```

The function `userIsMemberByOrganizationId` is pre-defined in the Makerkit's template: basically, it will verify that the current user is a member of the organization with ID `organizationId`.

If you use VSCode, take a look at the extension `toba.vsfire`.

### Data Fetching: React Hooks to read data from Firestore

Now that our security rules are updated, we can write Hooks to read data from Firestore.

I recommend writing your entities' hooks at `src/lib/tasks/hooks`. Let's start with a `React Hook` to fetch all the organization's tasks:

```tsx title="src/lib/tasks/hooks/use-fetch-tasks.ts"
import { useFirestore, useFirestoreCollectionData } from 'reactfire';

import {
  collection,
  CollectionReference,
  query,
  where,
} from 'firebase/firestore';

import { Task } from '~/lib/tasks/types/task';

function useFetchTasks(organizationId: string) {
  const firestore = useFirestore();
  const tasksCollection = 'tasks';

  const collectionRef = collection(
    firestore,
    tasksCollection
  ) as CollectionReference<WithId<Task>>;

  const path = `organizationId`;
  const operator = '==';
  const constraint = where(path, operator, organizationId);
  const organizationsQuery = query(collectionRef, constraint);

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

export default useFetchTasks;
```

Let's take a deep breath and slowly go through the above hook.

1. The hook above uses `useFirestoreCollectionData`, a `React hook` from the library `reactfire` to fetch real-time collection data from Firestore
2. We build a query that checks that the `organizationId` parameter matches the `organizationId` property of each task
3. Finally, we add `{ idField: 'id' }`. This special parameter decorates the data with the ID of the document. Thanks to the interface `WithId`, we add an `id` property to the `Task` interface returned from Firestore

### Displaying Firestore data in Components

Now that we can fetch our data using the hook `useFetchTasks,` we can build a component that lists each `Task.`

To do so, let's create a new component named `TasksListContainer`:

```tsx title="components/tasks/TasksListContainer.tsx"
import PageLoadingIndicator from '~/core/ui/PageLoadingIndicator';
import Alert from '~/core/ui/Alert';
import Heading from '~/core/ui/Heading';
import Button from '~/core/ui/Button';

import useFetchTasks from '~/lib/tasks/hooks/use-fetch-tasks';
import TasksList from '~/components/tasks/TasksList';
import { Task } from '~/lib/tasks/types/task';

const TasksContainer: React.FC<{
  organizationId: string;
}> = ({ organizationId }) => {
  const { status, data: tasks } = useFetchTasks(organizationId);

  if (status === `loading`) {
    return <PageLoadingIndicator>Loading Tasks...</PageLoadingIndicator>;
  }

  if (status === `error`) {
    return (
      <Alert type={'error'}>
        Sorry, we encountered an error while fetching your tasks.
      </Alert>
    );
  }

  if (tasks.length === 0) {
    return <TasksEmptyState />;
  }

  return (
    <div className={'flex flex-col space-y-4'}>
      <div className={'mt-2 flex justify-end'}>
        <CreateTaskButton>New Task</CreateTaskButton>
      </div>

      <div className={'flex flex-col space-y-4'}>
        {tasks.map((task) => {
          return <TaskListItem task={task} key={task.id} />;
        })}
      </div>
    </div>
  );
};

function TasksEmptyState() {
  return (
    <div
      className={
        'flex flex-col items-center justify-center space-y-4 h-full p-24'
      }
    >
      <div>
        <Heading type={5}>No tasks found</Heading>
      </div>

      <CreateTaskButton>Create your first Task</CreateTaskButton>
    </div>
  );
}

function TasksList({ tasks }: React.PropsWithChildren<{
  tasks: Task[]
}>) {
  return (
    <div className={'flex flex-col space-y-4'}>
      {tasks.map((task) => {
        return <TaskListItem task={task} key={task.id} />;
      })}
    </div>
  );
}

export default TasksList;


function CreateTaskButton(props: React.PropsWithChildren) {
  return <Button href={'/tasks/new'}>{props.children}</Button>;
}

export default TasksContainer;
```

The data above will automatically update when the `tasks` collection changes!

<Alert type="warn">
  Since the component "TaskListItem" is pretty complex and requires more files, we will define it separately. You will find it below after we explain the mutation hooks that the component will use.
</Alert>


Learn how to fetch data from Firestore in your React applications.

Firestore: Data Fetching


While `reactfire` does not provide hooks for writing data to Firestore, we can still make our own.

In fact, **I encourage you to make a custom hook for each mutation**.

## Mutations

#### Creating a Task

In the example below, we write a custom hook to add a document to the `tasks` collection:

```tsx title="src/lib/tasks/hooks/use-create-task.ts"
import { useFirestore } from 'reactfire';
import { useCallback } from 'react';
import { addDoc, collection } from 'firebase/firestore';
import { Task } from '~/lib/tasks/types/task';

function useCreateTask() {
  const firestore = useFirestore();
  const tasksCollection = collection(firestore, `/tasks`);

  return useCallback(
    (task: Task) => {
      return addDoc(tasksCollection, task);
    },
    [tasksCollection]
  );
}

export default useCreateTask;
```

The hook above returns a callback. Let's take a quick look at its usage:

```tsx
import useCreateTask from '~/lib/tasks/hooks/use-create-task';

function Component() {
  const createTask = useCreateTask();

  return <Form onCreate={task => createTask(task)} />
}
```

#### Updating a Task

Now, let's write a hook to update an existing task.

To update Firestore documents, we will import the function `updateDoc` from Firestore.

```tsx title="src/lib/tasks/hooks/use-update-task.ts"
import { useCallback } from 'react';
import { useFirestore } from 'reactfire';
import { doc, updateDoc } from 'firebase/firestore';
import { Task } from '~/lib/tasks/types/task';

function useUpdateTask(taskId: string) {
  const firestore = useFirestore();
  const tasksCollection = 'tasks';

  const docRef = doc(firestore, tasksCollection, taskId);

  return useCallback(
    (task: Partial<Task>) => {
      return updateDoc(docRef, task);
    },
    [docRef]
  );
}

export default useUpdateTask;
```

#### Deleting a Task

Finally, we write a mutation to delete a task:

```tsx title="src/lib/tasks/hooks/use-delete-task.ts"
import { useFirestore } from 'reactfire';
import { deleteDoc, doc } from 'firebase/firestore';
import { useCallback } from 'react';

function useDeleteTask(taskId: string) {
  const firestore = useFirestore();
  const collection = `tasks`;
  const task = doc(firestore, collection, taskId);

  return useCallback(() => {
    return deleteDoc(task);
  }, [task]);
}

export default useDeleteTask;
```

### Using the Modal component for confirming actions

The `Modal` component is excellent for asking for confirmation before performing a destructive action. In our case, we want the users to confirm before deleting a task.

The `ConfirmDeleteTaskModal` is defined below using the core `Modal` component:

```tsx title="src/components/tasks/ConfirmDeleteTaskModal.tsx"
import Modal from '~/core/ui/Modal';
import Button from '~/core/ui/Button';

const ConfirmDeleteTaskModal: React.FC<{
  isOpen: boolean;
  setIsOpen: (isOpen: boolean) => void;
  task: string;
  onConfirm: () => void;
}> = ({ isOpen, setIsOpen, onConfirm, task }) => {
  return (
    <Modal heading={`Deleting Task`} isOpen={isOpen} setIsOpen={setIsOpen}>
      <div className={'flex flex-col space-y-4'}>
        <p>
          You are about to delete the task <b>{task}</b>
        </p>

        <p>Do you want to continue?</p>

        <Button block color={'danger'} onClick={onConfirm}>
          Yep, delete task
        </Button>
      </div>
    </Modal>
  );
};

export default ConfirmDeleteTaskModal;
```

### Wrapping all up: listing each Task Item

Now that we have defined the mutations we can perform on each task item, we can wrap it up.

The component below represents a `task` item and allows users to mark it as `done` or `not done` - or delete them.

```tsx title="src/components/tasks/TasksListItem.tsx"
import { useCallback, useState } from 'react';
import Link from 'next/link';
import { TrashIcon } from '@heroicons/react/24/outline';
import toaster from 'react-hot-toast';
import { formatDistance } from 'date-fns';

import { Task } from '~/lib/tasks/types/task';
import Heading from '~/core/ui/Heading';
import IconButton from '~/core/ui/IconButton';
import Tooltip from '~/core/ui/Tooltip';
import useDeleteTask from '~/lib/tasks/hooks/use-delete-task';
import ConfirmDeleteTaskModal from '~/components/tasks/ConfirmDeleteTaskModal';
import useUpdateTask from '~/lib/tasks/hooks/use-update-task';

const TasksListItem: React.FC<{
  task: WithId<Task>;
}> = ({ task }) => {
  const getTimeAgo = useTimeAgo();
  const deleteTask = useDeleteTask(task.id);
  const updateTask = useUpdateTask(task.id);

  const [isDeleting, setIsDeleting] = useState(false);

  const onDelete = useCallback(() => {
    const deleteTaskPromise = deleteTask();

    return toaster.promise(deleteTaskPromise, {
      success: `Task deleted!`,
      loading: `Deleting task...`,
      error: `Ops, error! We could not delete task`,
    });
  }, [deleteTask]);

  const onDoneChange = useCallback(
    (done: boolean) => {
      const promise = updateTask({ done });

      return toaster.promise(promise, {
        success: `Task updated!`,
        loading: `Updating task...`,
        error: `Ops, error! We could not update task`,
      });
    },
    [updateTask]
  );

  return (
    <>
      <div
        className={'rounded border p-4 transition-colors dark:border-black-400'}
      >
        <div className={'flex items-center space-x-4'}>
          <div>
            <Tooltip content={task.done ? `Mark as not done` : `Mark as done`}>
              <input
                className={'Toggle cursor-pointer'}
                type="checkbox"
                defaultChecked={task.done}
                onChange={(e) => {
                  return onDoneChange(e.currentTarget.checked);
                }}
              />
            </Tooltip>
          </div>

          <div className={'flex flex-1 flex-col space-y-0.5'}>
            <Heading type={5}>
              <Link
                className={'hover:underline'}
                href={`/tasks/[id]`}
                as={`/tasks/${task.id}`}
                passHref
              >
                {task.name}
              </Link>
            </Heading>

            <div>
              <p className={'text-xs text-gray-400 dark:text-gray-500'}>
                Due {getTimeAgo(new Date(task.dueDate))}
              </p>
            </div>
          </div>

          <div className={'flex justify-end'}>
            <Tooltip content={`Delete Task`}>
              <IconButton
                onClick={(e) => {
                  e.stopPropagation();
                  setIsDeleting(true);
                }}
              >
                <TrashIcon className={'h-5 text-red-500'} />
              </IconButton>
            </Tooltip>
          </div>
        </div>
      </div>

      <ConfirmDeleteTaskModal
        isOpen={isDeleting}
        setIsOpen={setIsDeleting}
        task={task.name}
        onConfirm={onDelete}
      />
    </>
  );
};

export default TasksListItem;

function useTimeAgo() {
  return useCallback((date: Date) => {
    return formatDistance(date, new Date(), {
      addSuffix: true,
    });
  }, []);
}
```

Learn how to write data to Firestore in your React applications.

Firestore: Data Writing


Now that we have created a custom hook to write data to Firestore, we need to build a form to create a new `task`.

The example below is straightforward:
1. We have a form with two input fields
2. When the form is submitted, we read the data using `FormData`
3. Finally, we add the document using the callback returned by the hook `useCreateTask`

```tsx title="components/tasks/CreateTaskForm.tsx"
import { useNavigate } from '@remix-run/react';
import { FormEventHandler, useCallback } from 'react';

import TextField from '~/core/ui/TextField';
import Button from '~/core/ui/Button';
import useCreateTask from '~/lib/tasks/hooks/use-create-task';

import { useCurrentOrganization } from '~/lib/organizations/hooks/use-current-organization';

const CreateTaskForm = () => {
  const createTask = useCreateTask();
  const navigate = useNavigate();
  const organization = useCurrentOrganization();
  const organizationId = organization?.id as string;

  const onCreateTask: FormEventHandler<HTMLFormElement> = useCallback(
    async (event) => {
      event.preventDefault();

      const target = event.currentTarget;
      const data = new FormData(target);
      const name = data.get('name') as string;
      const dueDate = data.get('dueDate') as string;

      const task = {
        organizationId,
        name,
        dueDate,
        done: false,
      };

      // create task
      await createTask(task);

      // redirect to /tasks
      await navigate(`/tasks`);
    },
    [navigate, createTask, organizationId]
  );

  return (
    <form onSubmit={onCreateTask}>
      <div>
        <TextField.Label>
          Name
          <TextField.Input
            required
            name={'name'}
            placeholder={'ex. Launch on IndieHackers'}
          />

          <TextField.Hint>Hint: whatever you do, ship!</TextField.Hint>
        </TextField.Label>

        <TextField.Label>
          Due date
          <TextField.Input required name={'dueDate'} type={'date'} />
        </TextField.Label>

        <div>
          <Button>
            Create Task
          </Button>
        </div>
      </div>
    </form>
  );
};

export default CreateTaskForm;
```


Learn how to build forms in the Remix Firebase kit

Forms


Now that we have some components to display, we need to add them to the actual Remix pages.

If you have not created the files in the `Routing` section above, it's time to do it.

#### Using the components AppHeader and AppContainer

These components are used to wrap the content of the pages. They are responsible for displaying the header and the container of the page.
```tsx
function DashboardPage() {
  return (
    <>
      <AppHeader>
        <span className={'flex space-x-2'}>
          <Squares2X2Icon className="w-6" />

          <span>
            <Trans i18nKey={'common:dashboardTabLabel'} />
          </span>
        </span>
      </AppHeader>

      <AppContainer>
        Your content goes here
      </AppContainer>
    </>
  );
}
```


Learn how to create and manage application pages in your Makerkit app

Application Pages


Makerkit provides some utilities to reduce the boilerplate needed to write Remix API functions. This section will teach you everything you need to know to write your API functions.

### Calling API functions from the client

To make requests to the API functions in the `api` folder, we provide a
custom hook `useApiRequest`, a wrapper around `fetch`.

It has the following functionality:

1. Uses an internal `state` to keep track of the state of the request, like
`loading`, `error` and `success`. This helps you write fetch requests the
"hooks way"
2. Automatically adds a `Firebase AppCheck Token` to the request headers if you
enabled Firebase AppCheck
3. Automatically adds a `CSRF token` to the request headers

Similarly to making Firestore Requests, it's a convention to create a custom
hook for each request for readability/reusability reasons.

```tsx title="src/core/hooks/use-create-session.ts"
import useApiRequest from '~/core/hooks/use-api';

interface Body {
  idToken: string;
}

export function useCreateSession() {
  return useApiRequest<void, Body>('/api/session/sign-in');
}
```

The hook returns an array:

1. **Callback**: the first element is the **callback** to make the request
2. **State**: the second element is the **state object** of the request

```tsx
const [createSession, createSessionState] = useCreateSession();
```

The state object internally uses `useApiRequest`, and has the following
interface:

```tsx
{
  success: boolean;
  loading: boolean;
  error: string;
  data: T | undefined;
}
```

When `success` is `true`, the property `data` is inferred with its correct type.

You can use this hook in your components:

```tsx
import { useCreateSession } from '~/core/hooks/use-create-session';

function Component() {
  const [createSession, createSessionState] = useCreateSession();

  return (
    <>
      { createSessionState.loading ? `Loading...` : null }
      { createSessionState.error ? `Error :(` : null }
      { createSessionState.success ? `Yay, success!` : null }

      <SignInForm onSignIn={(idToken) => createSession({ idToken })} />
    </>
  );
}
```

Similarly, you can also use it to fetch data:

```tsx
import { useCreateSession } from '~/core/hooks/use-create-session';

function Component() {
  const [fetchMembers, { loading, error, data }]
    = useFetchMembers();

  // fetch data when the component mounts
  useEffect(() => {
    fetchMembers();
  }, [fetchMembers]);

  if (loading) {
    return <div>Fetching members...</div>;
  }

  if (error) {
    return <div>{error}</div>;
  }

  return (
    <div>
      {data.map(member => <MemberItem member={member} />)}
    </div>
  );
}
```

#### Writing your own Fetch Hook

You are free to use your own implementation for sending HTTP requests to your API or use a powerful third-party library.

With that said, you need to ensure that you're sending the required headers:
1. The AppCheck token (if you use Firebase AppCheck)
2. The CSRF Token (for POST requests)

##### Generating an App Check Token

To generate an App Check token, you can use the `useGetAppCheckToken` hook:

```tsx
const getAppCheckToken = useGetAppCheckToken();
const appCheckToken = await getAppCheckToken();

console.log(appCheckToken) // token
```

You will need to send a header `X-Firebase-AppCheck` with the resolved value returned by the promise `getAppCheckToken()`.

##### Sending the CSRF Token

To retrieve the page's CSRF token, you can use the `useGetCsrfToken` hook:

```tsx
const getCsrfToken = useGetCsrfToken();
const csrfToken = getCsrfToken();

console.log(csrfToken) // token
```

You will need to send a header `x-csrf-token` with the value returned by `getCsrfToken()`.

### CSRF Token check

We must pass a `CSRF token` when using POST requests to prevent malicious attacks. To do so, we use the pipe `withCsrfToken`.

1. The CSRF token is generated when the page is server-rendered
2. The CSRF token is stored in a `meta` tag
3. The CSRF token is sent to an HTTP POST request automatically when using the `useApiRequest` hook
4. This function will throw an error when the token is invalid

By using this function, **we ensure all the following functions will not be executed unless the token is valid**.

```tsx
export const action: ActionFunction = async ({ request }) => {
  await withCsrf(request);
}
```

### Firebase App Check

App Check is a Firebase service that helps you to protect your web app from
bots, spammy users, and general abuse detected by Google's Recaptcha.

[Check out the documentation to setup Firebase App Check](/docs/app-check).

Using the `withAppCheck` pipe, **we ensure all the following functions will not be executed unless the App Check token is valid**.

```tsx
export const action: ActionFunction = async ({ request }) => {
  await withAppCheck(request);
}
```



### Catching and Handling Exceptions

To catch and gracefully handle API exceptions, we use the function `withExceptionFilter`.

As seen from its usage above, we wrap the API function within the utility. When errors are caught, this function will:

1. Log and debug the error to the console
2. Report the error to Sentry (if configured)
3. Return an object stripping the error's data to avoid leaking information

### API Logging

The boilerplate uses `Pino` for API logging, a lightweight logging utility for Node.js.

Logging is necessary to debug your applications and understand what happens when things don't behave as expected. You will find various instances of logging throughout the API, but we encourage you to log more if necessary.

We import the logging utility from `~/core/logger`. Typically, you can log every time you perform an action, both before and after. For example:

```tsx
async function myFunction(params: {
  organizationId: string;
  userId: string;
}) {
  logger.info(
    {
      organizationId: params.organizationId,
      userId: params.userId,
    },
    `Performing action...`
  );

  await performAction();

  logger.info(
    {
      organizationId: params.organizationId,
      userId: params.userId,
    },
    `Action successful`
  );
}
```

It's always important to add context to your logs: as you can see, we use the first parameter to add important information.


Learn how to create and manage API routes in your Remix Firebase application.

API Routes


Validating payloads is necessary to ensure your API endpoints receive the expected data. To validate the API, we use Zod.

[Zod](https://github.com/colinhacks/zod) is a Typescript library that helps us
secure our API endpoints by validating the payloads sent
from the client and also facilitating the typing of the payload with
Typescript.

Using Zod is the first line of defense to validate the data sent against our
API: as a result, it's something we recommend you keep doing. It ensures we
write safe, resilient, and valid code.

When we write an API endpoint, we first define the schema of the payload:

```tsx
function getBodySchema() {
  return z.object({
    displayName: z.string(),
    email: z.string().email(),
  });
}
```

This function represents the schema, which will validate the following
interface:

```tsx
interface Body {
  displayName: string;
  email: Email;
}
```

Now, let's write the body of the API handler that validates the body of the
function, which we expect to be equal to the `Body` interface.

```tsx
import { throwBadRequestException } from `~/core/http-exceptions`;

export const action: ActionFunction = async ({ request }) => {
  try {
     // we can safely use data with the interface Body
    const schema = getBodySchema();
    const body = await request.json();
    const { displayName, email } = schema.parse(body);

    return sendInvite({ displayName, email });
  } catch(e) {
    return throwBadRequestException();
  }
}
```

I encourage you to never skip the validation step when writing your API endpoints.

The best practices to validate your API routes payloads using Zod in your Remix Firebase application.

API Routes Validation


By default, Makerkit uses English for translating the website's text. All the files are stored in the files at `/public/locales/en`.

Adding a new language is very simple:

1. **Translation Files**: First, we need to create a new folder, such as `/public/locales/es`, and then copy over the files from the English version and start translating files.
2. **Remix i18n config**: We need to also add a new language to the Remix
configuration at `app/i18n/i18next.config.ts`. Simply add your new
language's code to the `supportedLanguages` array.

The configuration will look like the below:

```js title="app/i18n/i18next.config.ts"
const i18Config = {
  fallbackLanguage: DEFAULT_LOCALE,
  supportedLanguages: [DEFAULT_LOCALE, 'es'],
  defaultNS: ['common', 'auth', 'organization', 'profile', 'subscription'],
  react: { useSuspense: false },
};
```

#### Setting the default Locale

To set the default locale, simply update the environment variable `DEFAULT_LOCALE` stored in `.env`.

So, open the `.env` file, and update the variable:

```txt title=".env"
DEFAULT_LOCALE=de
```


Learn how to easily translate your Remix Firebase Makerkit SaaS into multiple languages with our guide. Optimize your app and reach a wider audience.

Translations


To update the site's navigation menu, you can visit the `SiteNavigation.tsx` component and add a new entry to the menu.

By default, you will see the following object `links`:

```tsx title="components/SiteNavigation.tsx"
const links: Record<string, Link> = {
  Blog: {
    label: 'Blog',
    path: '/blog',
  },
  Docs: {
    label: 'Docs',
    path: '/docs',
  },
  Pricing: {
    label: 'Pricing',
    path: '/pricing',
  },
  FAQ: {
    label: 'FAQ',
    path: '/faq',
  },
};
```

The menu is defined in the render function:

```tsx
<NavigationMenu>
  <NavigationMenuItem link={links.Blog} />
  <NavigationMenuItem link={links.Docs} />
  <NavigationMenuItem link={links.Pricing} />
  <NavigationMenuItem link={links.FAQ} />
</NavigationMenu>
```

Assuming we want to add a new menu entry, say `About`, we would first add the link object:

```tsx
About: {
  label: 'About',
  path: '/about',
},
```

And then we update the menu:

```tsx
<NavigationMenu>
  <NavigationMenuItem link={links.About} />
  ...
</NavigationMenu>
```


Learn how to add pages to the Marketing Site.

Adding pages to the Marketing Site


Before deploying to production or any remote server, you need to [follow all the steps outlined in the documentation](/docs/remix-fire/going-to-production-overview).

**Much of this work needs to be done in Firebase**, not in the Makerkit codebase.

Generally, you will need to:

1. **Firebase**: Create a new Firebase project (database, storage bucket, getting the private keys)
2. **Security Rules**: Update the remote security rules (both Firestore and Storage)
3. **Environment Variables**: Ensure that your environment variables are set correctly, and that you've added the relevant environment variables to your hosting provider
4. **Auth**: Enable the authentication providers you want to use from the Firebase Console
5. **Indexes**: Update all the Firestore indexes required by your application in the Firebase Console
6. **SMTP**: Set up an SMTP server to send emails by adding the required configuration to `src/configuration.ts`
7. **Payments**: Set up your Stripe or Lemon Squeezy accounts and add the relevant environment variables
8. **Deployment**: Finally, deploy your application to your hosting provider (Vercel, Firebase, Netlify, etc.): please follow the instructions provided by your hosting provider to deploy a Remix application.

Learn how to deploy your Remix Firebase app to your hosting provider.

Deploying to Production


If you have followed the steps to set up Git at the beginning of this tutorial, you've already set the original Makerkit repository as `upstream`.

As the repository is constantly updated, it's recommended to fetch updates regularly. You can do so by running the following Git command:

```
git pull upstream main --allow-unrelated-histories
```

Unfortunately, you may need to resolve eventual conflicts.

### Any questions?

If you have questions, please join our [Discord Community](https://discord.gg/BeJSyQJ6jP), even if you have not purchased any kit. We chat and help each other build products.


Learn how to update your Makerkit repository to the latest version.

Updating to the latest version

Let's get started. Configure MakerKit and Firebase, and run the application for the first time!

Getting Started


MakerKit is **the Remix.js boilerplate project for SaaS** built to get you
started on the right foot.

MakerKit is a fully SSR-rendered Remix application that uses Firebase for
authentication, database (with Firestore), and storage.

MakerKit is ideal for any SaaS application or dynamic websites such as walled Online Publications.

It particularly shines when you wish to provide uniform navigation between your marketing site, documentation, and application.

## What does the boilerplate provide?

### Tech Stack

We built MakerKit with some of the best technologies available today, such as
Remix, Tailwind CSS, and Firebase:

- **Scalable Remix** structure template, perfect for the most ambitious
projects
- Beautiful **Tailwind 3** CSS theme - with dark mode!
- **Full Firebase** setup with local emulators
- **Reusable UI components** as building blocks (which you can easily swap
with your own or your favorite library) based on [Radix UI](https://radix-ui.com)
- **SSR-compatible Authentication flow**, including 3rd-party providers (Google,
Facebook, Twitter, GitHub, etc.)

### Template Features

MakerKit is fully functioning from the beginning and comes with the
following features:

- **Payments** with Stripe, and support for **subscriptions** (or, alternatively, using Lemon Squeezy)
- **Onboarding flow**, which allows your users to set up their accounts and
create their organization
- **Organizations**: users can create and edit organizations. An organization is a group of users. You can rename the `Organization` entity according to your domain (for example, teams, projects, etc.)
- **Team Members**: users can invite other users to join their organization and assign them a role
- **MDX-powered Blog and Documentation** generators - already
**SEO-optimized** for you [Coming Soon]

### Marketing

Marketing matters! But don't get hung up on the technicalities. MakerKit provides:

- **Newsletter Sign-up form** for *ConvertKit*, but easy to adapt to more
providers
- **Google Analytics** script baked-in
- **Email Templates** you can write with React using [React.email]
(https://react.email)

### Debugging and Testing

Never waste time chasing bugs again.

Assuming you have created a Sentry account, MakerKit can catch exceptions (and possible bugs) and  report them to Sentry whenever they happen in both client and server-side code:

- **Error Tracking** set up with Sentry
- Comprehensive **E2E Tests** suite with Cypress, which you can use and learn
from

### After you buy

You're not going to be left alone. We offer help and support:

- Access to the team for feedback, requests, and general support. **We're here to support you build your SaaS**.

This documentation introduces each of the points above and guides you through
so that you can easily adjust MakerKit to your application's domain.

MakerKit has plenty of resources for using both Remix and Firebase - and if you're stuck, you can always reach out to me for help.


Introduction to MakerKit: a SaaS starter built with Remix and Firebase

Introduction to MakerKit: a SaaS boilerplate for Remix and Firebase


MakerKit is built primarily with Remix, Firebase, and Tailwind CSS.

Under the hood, there are many more libraries and architectural
decisions you should know.

### 1) A Scalable Remix Application
The codebase is entirely built with [Remix](https://remix.run).

The front end is fully built with React, leveraging React Hooks
and the best practices available today.

### 2) Built on top of Firebase

[Firebase](https://firebase.com) is one of the most popular *PaaS* out there,
with a very generous free tier and fairly affordable pricing for growing
applications.

MakerKit uses Firebase for Authentication, Firestore for storing your data,
Storage for storing files, and AppCheck to protect your endpoints against
possible attacks.

### 3) Theme built with Tailwind 3

The bulk of the application's theme, built with [Tailwind 3](https://tailwindcss.com/), is
stored in three CSS files rather than HTML.

It may sound like a bad practice, but we approached this way to help you find and edit
the theme's CSS in one single place.

We designed the theme in light and dark, so you can choose to use both according to your user's OS settings or manage it using a local cookie.

### 4) Radix UI Components

All the kits use [Radix UI](https://radix-ui.com), arguably the best headless UI library for React.

The components are styled using Tailwind CSS. Many components are inspired by the template made by [Shad CN](https://ui.shadcn.com/). We recommend taking a look if you want to build your own components.

Some components are still using Headless UI, but will be phased out in the future.

### 5) Fully and Strictly Typed with Typescript

We wrote every single line of code with *strictly-typed
Typescript* both on the client and server side.

### 6) Payload validation with Zod

The API endpoints are **validated and protected with [Zod](https://github.com/colinhacks/zod)**, which also helps with strong-typing.

### 7) E2E testing with Cypress

We ship MakerKit with [Cypress](https://www.cypress.io/), likely the most
popular E2E testing framework.

We made lots of examples and utilities to change the tests as you develop
your application.

### 8) Linted with EsLint and formatted with Prettier

We lint the codebase with **a very strict EsLint configuration**, but
we distribute it with less strict params so that it won't be in your way
as you're experimenting with the starter.

We will show you how to add stricter parameters if that's your thing, but we do not recommend jumping head-in with it. It's much better to activate the stricter configuration once you have already shipped the product and are looking to stabilize it.

Furthermore, the codebase is **formatted with Prettier** automatically.

### 9) Multi-language by default with remix-i18n

We configured the application to be translated by default thanks to the
`remix-i18n` package.

All the application's strings are translated by default, so you can easily
extend it to other languages if necessary.

Using translation files can help you if you want to **translate your apps in multiple
languages**, but it also allows you to find the text strings you
want to replace.

In this way, you do not need to change strings in the codebase, but they're
**neatly organized in JSON files**.

### 10) Logging with Pino

MakerKit uses [Pino](https://github.com/pinojs/pino), a lightweight logging library.

API errors are logged with just enough information to help you debug
your API routes.


MakerKit uses Remix, Firebase, Firestore, Tailwind CSS, Zod, Pino, Headless UI, Typescript and Cypress to build wonderful SaaS applications

The technologies that make up a MakerKit application


If you have bought a license for MakerKit, you have access to all the
repositories built by the MakerKit team. In this document, we will learn how
to fetch and install the codebase.

### Requirements

To get started with the Remix and Firebase SaaS template, we need to ensure
you install the required software.

- Node.js (LTS recommended)
- Git
- Docker (optional but recommended)

### Cloning the repository

To get the codebase on your local machine, clone the repository with the
following command:

```
git clone --depth=1 git@github.com:makerkit/remix-firebase-saas-kit.git my-saas
```

The command above clones the repository in the folder `my-saas` which
you can rename it with the name of your project.

### Initializing Git

Now, run the following commands for:

1. Moving into the folder
2. Reinitialize your git repository
3. Adding the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

```
cd my-saas
rm -rf .git
git init
git remote add upstream git@github.com:makerkit/remix-firebase-saas-kit.git
git add .
git commit -a -m "Initial Commit"
```

In this way, to fetch updates (after committing your files), simply run:

```
git pull upstream main --allow-unrelated-histories
```

You'll likely run into conflicts when running this command, so carefully choose the changes (sorry!).

### Installing the Node dependencies

Finally, we can install the NodeJS dependencies with `npm`:

```
npm i
```

While the application code is fully working, we now need to set up your Firebase
project.

So let's jump on to the next step!


Learn how to clone the MakerKit repository

Clone the MakerKit SaaS boilerplate repository


After installing the modules and the emulators, we can finally run the
application in development mode.

We need to execute two commands (and an optional one for Stripe):

1. **Remix Server**: the first command is for running the Remix server
2. **Firebase Emulators**: the second command is for running the Firebase
emulators
3. **Stripe CLI**: finally, the Stripe CLI is needed to dispatch webhooks to
our local server (optional, only needed when interacting with Stripe)

### Running the Firebase Emulators

First, let's run the emulators. The command below runs the emulators for
the following products: Authentication, Firestore, and Storage.

```bash
npm run firebase:emulators:start
```

Additionally, it imports the default emulator's data from the folder `.
/firebase-seed`, which we set up upfront to run the Cypress tests.

After running the command above, you will be able to access the [Firebase
Emulators UI](https://firebase.google.com/docs/emulator-suite) at
[http://localhost:4000](http://localhost:4000).

### Running the Remix Server

And now, the Remix server:

```bash
next run dev
```

If everything goes well, your server should be running at
[http://localhost:3000](http://localhost:3000).

### Running the Stripe CLI

Run the Stripe CLI with the following command:

```bash
next run stripe:listen
```

#### Add the Stripe Webhooks Key to your environment file

If this is the first time you run this command, you will need to copy the Webhooks key printed on the console and add it to your development environment variables file:

```bash title=".env.development"
STRIPE_WEBHOOKS_KEY=<PASTE_KEY_HERE>
```

## Saving the Firebase Emulator's data

After shutting the emulators down, the Firebase emulator clears all the records
and the users added during the session while the emulators are running.

Fortunately, we can save and restore as many dumps as we want. For example, this can be useful for saving and loading particular scenarios for testing.

To save the current snapshot, run the following command while the emulators are up and running:

```bash
npm run firebase:emulators:export
```

By default, MakerKit imports and exports to `./firebase-seed`, but you can change this to any other path.

### Always Save on exit

We don't particularly recommend this, but if you want to keep persisting data as you exit the emulators,
you can decorate the `firebase:emulators:start` with the following options:

```bash
firebase emulators:start --export-on-exit=./your-directory
```

Saving your emulators' state can be handy, but keep in mind that for testing reasons,
it's always best to create a snapshot of your data and use the same one so that your tests won't break if the data changes.

Of course, change `./your-directory` to your preferred path.


How to run a Remix and Firebase MakerKit application


## React.FC vs React.FCC

Since React 18, `React.FC` no longer implies that components can accept a `children` prop. The alternative to that is using the interface `React.FC<React.PropsWithChildren<{}>>`, which is a bit long.

`React.FCC` is a shorthand that includes `children` as a possible property that works similarly to how it used to work. When a component needs `children`, `React.FCC` is preferred since it's faster to type.

## Exporting functions vs constants

We use both conventions in the boilerplate, i.e., exporting functions as components and constants.

My general rule is the following:

- if it's the exported component, use `const` typed with `React.FC` or `React.FCC`
- if it's not exported, use `function` since my personal preference is to define functions below the exported component

NB: sometimes, that may not be the case, and that's not necessarily intentional. The two constructs are essentially the same in most cases.

## Why is useCallback used in most components?

Most functions defined within a render function use `useCallback`. In my experience, this is the better default to avoid re-renders that I can't immediately explain.

Whether you want to adhere to this convention is totally up to you; just be aware of the potential issues.

## Interfaces, Types, and Inline 

I've gone through phases, so you may find some types defined as `type` and others as `interface`. I've since realized that I prefer `interface`, but you will find some instance that uses `type`.

Inline types are typically only defined when the type isn't reused anywhere. For example, when defining a function that accepts parameters as objects.

## Function parameters

I adhere to the principle that if a function accepts multiple parameters of the same type, then use an object. Unfortunately, Typescript can't save us if the types match.

Consider the example below:

```tsx
function makeDiv(width: number, height: number) {}

const height = 10;
const width = 40;

// correct according to TS, not in practice!
const div = makeDiv(height, width);
```

Now we rewrite it using an object:

```tsx
function makeDiv(params: { width: number, height: number}) {}

const height = 10;
const width = 40;

// Okay, now it looks better!
const div = makeDiv({ height, width });
```

## Custom React Hooks

The boilerplate uses Custom React Hooks when:

- fetching/writing using an API function
- fetching/writing using Firestore
- fetching/writing using Storage

It makes the code more understandable and reusable.

An explanation of the coding conventions used in the boilerplate

SaaS template Coding Conventions

Configuration


We store the global configuration of a MakerKit application in `/configuration.ts`.

Within any application file, we can use the path `~/configuration` to
import it from any other file.

<Alert type='info'>
You do not need any changes to start developing your application. Feel free
to complete the configuration once you want to deploy the app for the first
time.
</Alert>

The configuration has the following structure:

```ts title="configuration.ts"
export default {
  site: {
    title: '',
    description: '',
    themeColor: '',
    siteUrl: '',
    siteName: '',
    twitterHandle: '',
    language: 'en',
  },
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    onboarding: `/onboarding`,
    appHome: '/tasks',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/resources/stripe/checkout`,
      billingPortal: `/resources/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  firebase: {
    apiKey: process.env.FIREBASE_API_KEY,
    authDomain: process.env.FIREBASE_AUTH_DOMAIN,
    projectId: process.env.FIREBASE_PROJECT_ID,
    storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.FIREBASE_APP_ID,
    measurementId: process.env.FIREBASE_MEASUREMENT_ID,
  },
  auth: {
    // Enable MFA. You must upgrade to GCP Identity Platform to use it.
    // see: https://cloud.google.com/identity-platform/docs/product-comparison
    enableMultiFactorAuth: true,
    // NB: Enable the providers below in the Firebase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: [GoogleAuthProvider],
    },
  },
  appCheckSiteKey: process.env.APPCHECK_KEY,
  navigation: {
    style: NavigationStyle.TopHeader,
  },
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  environment: process.env.VERCEL_ENV ?? 'development',
  emulatorHost: process.env.EMULATOR_HOST,
  emulator: process.env.EMULATOR === 'true',
  production: process.env.NODE_ENV === 'production',
  stripe: {
    products: [
      {
        name: 'Basic',
        description: 'Describe your basic plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
      {
        name: 'Pro',
        description: 'Describe your pro plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
    ],
  },
};
```

These values are used throughout the application instead of being hardcoded into the codebase.

This file will not be committed (at least not
the "secret" variable). So instead, you should define those variables within your
favorite CI/CD.

## Environment Variables

Makerkit provides templates for configuring your environment variables correctly and the **minimum** environment variables to run your local environment.

To push your project to production, **you must fill these variables by creating your Firebase project** and adding the required values.

<Alert type='warn'>
  When you first run your project build, ensure to fill the required environment variables using the ".env.production" environment file.
</Alert>

### Development Environment Variables

The development environment variables set your application up for the Firebase Emulators:

```
EMULATOR=true

GCLOUD_PROJECT=demo-makerkit
FIREBASE_PROJECT_ID=demo-makerkit
FIREBASE_STORAGE_BUCKET=demo-makerkit.appspot.com
SITE_URL=http://localhost:3000
FIREBASE_AUTH_DOMAIN=localhost
FIREBASE_EMULATOR_HOST=localhost
FIRESTORE_EMULATOR_PORT=8080
FIREBASE_AUTH_EMULATOR_PORT=9099
FIREBASE_STORAGE_EMULATOR_PORT=9199

# Change this with your project's APP ID
FIREBASE_APP_ID=<MAKERKIT_DEV_APP_ID>
# Change this with your project's API KEY
FIREBASE_API_KEY=<MAKERKIT_DEV_API_KEY>

FIRESTORE_EMULATOR_HOST=localhost:8080
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIREBASE_STORAGE_EMULATOR_HOST=localhost:9199
FIREBASE_PUBSUB_EMULATOR_HOST=localhost:8085

FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=
```

Please remember to update the `FIREBASE_APP_ID` and `FIREBASE_API_KEY` with the ones from your Firebase project ID. The only reason they're predefined is to allow you to quickly start the application.

### Production Environment Variables

When you go to production, create the `.env.production` by copying the content of `.env.production.template`:

```
FIREBASE_API_KEY=
FIREBASE_PROJECT_ID=
FIREBASE_STORAGE_BUCKET=
FIREBASE_MESSAGING_SENDER_ID=
FIREBASE_APP_ID=
FIREBASE_MEASUREMENT_ID=
SITE_URL=

FIREBASE_CLIENT_EMAIL=

## SECRET KEYS ARE BEST ADDED TO YOUR CI
FIREBASE_PRIVATE_KEY=
SECRET_KEY=
SECRET_APPCHECK_KEY=

STRIPE_PUBLISHABLE_KEY=

# Add these in Vercel or .env.local
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```

All the secret variables should be added from your Vercel or CI console; if you need them locally, you should add them to your `.env.local` file, an environment file that is ignored by Git, and, therefore, suitable for storing sensitive data that is local and isolated to your machine.

When pushing your project to Vercel, the build will pick up the values added to `.env.production`.

### Configuring the Firebase Secret Key environment variable

If you are adding the Firebase secret key as an environment variable (as you
should) from your Vercel console (or other providers), you should make sure to
 enter the key in a valid format. But, again, this can differ between providers.

If using Vercel, add the line breaks to the pasted code.
 To do so, you can use the following regexp to replace `\\n` with `\n`. You
 should be seeing the private key with the correct line breaks (instead of
 `\n`).

Next, you can paste the secret key in the correct format into your Vercel
console.

### MakerKit configuration details

Let's see the configuration in detail:

## Site

In this section, we define some overall details about the website. We use most of these configuration properties in public pages, blog posts, and documentation.

#### Title

This property is the default title of the website. We use it in conjunction with the page's name. For example, the blog's title will be `Blog - { site.name }`.

#### Description

This title is the default description of the website. For blog posts, we override it with each entry's excerpt.

#### Theme Color

We use the property `themeColor` to define the primary color browsers display. For example, in a PWA, it is the background color of the window's header.

#### Site URL

This `siteUrl` property should be your website's URL, including the protocol, such as https://yourwonderfulwebsite.com

#### Twitter Handle

You can use this or your company's Twitter handle to link your blog posts.

## Paths

Some of the paths are repeated many times throughout the codebase. For example: where should the user be redirected to after login?

These paths help you set up the default behavior when the user signs in, out, etc.

Of course, while we could store these in the codebase, it's the quickest way to get started with the boilerplate without changing any line of code.

## Firebase

The `firebase` object is Firebase's configuration which you can retrieve from the Firebase console. You could copy and paste it in, as it's all required.

If you use multiple environments (for example, `staging` and `production`), I recommend creating two `.env` files and starting your application using the correct one.

We will show later how to do set-up multiple environments effectively.

## Email

This setting allows you to define your email provider's SMTP authentication details to send emails in your application.

While in development, you can leave this as-is: MakerKit uses the `nodemailer` test account.

## Plans

Here you can store the plans that your application offers. They should match
the plans that you are going to create in the Stripe Dashboard.


Learn how to define the global configuration of a MakerKit application with Remix and Firebase

Define the global configuration of your MakerKit SaaS application with Remix and Firebase


You should be all set if you have already installed NodeJS on your machine. If not, please install [NodeJS](https://nodejs.org) before continuing.

If any of the following commands do not work, please install the Firebase tools package globally:

```
npm i firebase-tools -g
```

Now, run this command to set up your Firebase project:

```
firebase init
```

Now, select all the products you would like to set up. If you're not sure yet, I recommend the following ones:
- Emulators
- Cloud Firestore
- Cloud Storage
- Remote Config

<Alert type='info'>
You do not need any changes to start developing your application. Feel free
to complete the configuration once you want to deploy the app for the first
time.
</Alert>

By default, Makerkit starts the application with a demo project
`demo-makerkit`.

You can rename the demo name however you want, as long as you keep the
prefix "demo", which tells Firebase not to use any production service and
not to require additional configuration for developing the application. In
fact, you do not need to create a Firebase project to get started!

Additionally, remember to change the project in the environment variables.

**If you also want to create a real Firebase project, please read on.**

#### Create or select a Project

If you have already created a project using the Firebase Console, continue by
using "Use an existing project"; otherwise, you can create one right away by
selecting "Create a new project".

If you're more comfortable creating a new project using the Firebase Console,
 [create a new project from here](https://console.firebase.google.com/).

#### Emulators

The CLI should prompt you to choose the emulators to download and the ports for each. Next, select the emulators you need based on the products selected during the first step.

Otherwise, you don't need to make any changes because this starter already uses the Firebase default ports.

Once completed, you should have the following new files in your project:
- `.firebaserc`
- `firebase.json`
- `firestore.rules`
- `firestore.indexes.json`

## Firebase Project Set-up

If you have created a Firebase project, you should be able to access this
project using the [Firebase Console](https://console.firebase.google.com/).

We assume you're building a web app: let's create a new web project.

<Video src='/assets/images/docs/create-web-app-firebase.mp4' />

### Copying the Firebase configuration in the environment file

After the previous step, you should be seeing the Firebase configuration
object.

We need to add this to your `.env` file, which will automatically
populate the project configuration file `~/.configuration`.

```
FIREBASE_API_KEY=
FIREBASE_AUTH_DOMAIN=
FIREBASE_PROJECT_ID=
FIREBASE_STORAGE_BUCKET=
FIREBASE_MESSAGING_SENDER_ID=
FIREBASE_APP_ID=
FIREBASE_MEASUREMENT_ID=
```

### Getting the service account

You can find the service account by clicking on `Settings->Service Accounts`.
You should copy the text highlighted in the video below:

<Video src='/assets/images/docs/find-service-account.mp4' />

Afterward, you need to populate the relative environment variable:

```
FIREBASE_CLIENT_EMAIL=
```

You could safely add it using the file of your staging account. If it's
 your production environment, please add it using the Vercel console instead (or any other service you use to
 deploy the project).

### Generating the Private Key

The private key is fundamental to running your app with Admin permissions on the
server side. From the same page, click on "Generate Private key".

You should see the modal below:

<Image
  width={'1368'}
  height={'1018'}
  src={'/assets/images/docs/generate-private-key.webp'}
  alt={'Generate Firebase Private Key'}
/>

Once you open the generated JSON file, copy the `private_key` property and place it in your CI or your environment file as long as you do not commit the environment file.

The environment variable to populate is `FIREBASE_PRIVATE_KEY`:

```
FIREBASE_PRIVATE_KEY=
```

The key looks like this:

```
-----BEGIN PRIVATE KEY-----
***************************
-----END PRIVATE KEY-------
```

If you enter the wrong key, you will not be able to sign in server-side. In short, it won't work.

<Alert type='warn'>
Do not commit the file if you add the private key to your local environment file
</Alert>

## Firestore

Now it's time to set up Firestore DB. From the main panel on the left-hand side of the Firebase Console, click on `Firestore Database`.

Once you click on the `Create Database` CTA, you will se a modal like in the
image below:

<Image
  width={'1810'}
  height={'1132'}
  src={'/assets/images/docs/create-firestore-db.webp'}
  alt={'Create Firestore DB'}
/>

Don't overthink what to choose: we use the default MakerKit Firestore
rules which use the production configuration by default.

### Location
The next step is to choose the Firestore Database's location.

Which option to choose here depends entirely on **where you think most of
your users come from**.

<Image
  width={'1724'}
  height={'1034'}
  src={'/assets/images/docs/firestore-location.webp'}
  alt={'Choose Firestore Location'}
/>

Be careful to the Firebase notice:

<Alert type='warn'>
After you've set this location, you cannot change it later. Also, this location setting will be the location for your default Cloud Storage bucket.
</Alert>

If you're not sure, think it through. You do not need this step to start
working on your app with the Emulators, so feel free to come back to this
later when you have made a decision.

### Firestore Indexes

If you are setting up Makerkit for the first time, remember to set up an
index for querying an invitation without knowing its organization.

You can do so using the following link (replace
"\[\[YOUR_PROJECT_ID\]\]" with your real project ID):

https://console.firebase.google.com/u/0/project/\[\[YOUR_PROJECT_ID\]\]/firestore/indexes/single-field?create_exemption=ClBwcm9qZWN0cy9zdG9yeWpveS00NmVlMy9kYXRhYmFzZXMvKGRlZ
mF1bHQpL2NvbGxlY3Rpb25Hcm91cHMvaW52aXRlcy9maWVsZHMvY29kZRACGggKBGNvZGUQAQ

## Firestore and Storage Security Rules

Finally, you are required to publish the security rules to the production project. 

You can do so by logging in to the Firebase Console and pasting the rules from the `firestore.rules` and `storage.rules` files in their respective sections.

You don't need to do this right away, but you will need to do it before you deploy your application to production.

Learn how to set up your Firebase project with a MakerKit application

Setting up a Firebase project for your MakerKit application


<Alert type="info">
  Setting Firebase Functions is optional. You only need to set up Firebase Functions if you need certain features, such as Firestore Triggers, Storage Triggers, Authentication Blocking Functions, etc.
</Alert>


While you may want to use Remix's own API functions for your application's API,
there are many scenarios where you may be required to use Firebase Functions, for example:

1. You want to implement [Authentication Blocking Functions](/blog/tutorials/blocking-authentication-firebase-auth)
2. You need to use Firebase Storage Triggers
3. You need to use Firebase Firestore Triggers

Therefore, it's essential to know how to set up Firebase Functions in a Remix environment, such as the Makerkit SaaS template.

## Initializing Firebase Functions

Assuming you have a working Makerkit project installed, let's type the following command in your terminal:

```
firebase init functions
```

When prompted about creating a new project, choose not to create a default project, as you may have already done it.

After completing the CLI prompts, you should have a few more files in your project:

```
✔  Wrote functions/package.json
✔  Wrote functions/tsconfig.json
✔  Wrote functions/src/index.ts
✔  Wrote functions/.gitignore
```

#### Adjust or delete the eslint configuration file

You may need to delete (or adjust) the `eslint` file generated by the CLI, as it may conflict with the one in the root of your project. We recommend using the one in the root of your project shipped with Makerkit.

If you leave it as is, you may see linting errors in your functions code, that can also prevent you from deploying your functions.

### Firebase Functions setup

I usually proceed to copy some of the scripts to the root `package.json`, such as the below:

```
"build:functions": "tsc -P functions/tsconfig.json",
"build:functions:watch": "tsc -P functions/tsconfig.json --watch",
"deploy:functions": "firebase deploy --only functions"
```

1. `build:functions` builds the functions bundle and then exits
2. `build:functions:watch` builds the functions in development mode, so it will re-bundle your code on changes
3. `deploy:functions` deploys your Functions to the Firebase cloud

### Writing your First Function

Let's write our first, very simple Firebase Function:

```tsx
import { https } from 'firebase-functions';

export const helloWorld = https.onRequest((req, res) => {
  res.send({ Hello: `World` })
});
```

### Running the Firebase Functions emulators

When using Makerkit, simply run the emulators:

```
npm run firebase:emulators:start
```

If working correctly you'll see the following output:

```
✔  functions: Loaded functions definitions from source: helloWorld.
```

🎉 And now you can finally use the full power of Firebase's Functions!

### Ignore the Firebase Functions folder when deploying to Vercel

Since Firebase Functions are to be deployed to Firebase, you can ignore the `functions` folder when deploying to Vercel.

To do so, create a file named `.vercelignore` in the root of your project and add the following line:

```
functions
```

Learn how to set up Firebase Functions in your Makerkit SaaS project

Setting up Firebase Functions for your MakerKit application

A high-level overview of Makerkit's Design and Architecture

Architecture


MakerKit's primary goals are:

- **Solid Foundations** - providing you with the necessary code to get up and
running
with a Saas with minimal configuration
- **Extendable and Adaptable** - the ability to change and extend the codebase as efficiently as possible

While it's relatively simple to provide a functioning codebase, it's not always easy to make it:
- **Simple** - a clean codebase quickly understandable by anyone
- **Easy to change** - a codebase that can be easily changed to a
particular domain

Once you start your project, you can begin unpicking and replacing the existing code to adapt it to your application's domain. At the same time, MakerKit may have pushed an update that fixed a bug or added a new cool feature.

The two projects will diverge and inevitably end up in a conflicting state.

Thankfully, Git makes it easy to merge conflicts. But it's still a hassle.

### Framework Architecture

To reduce the number of possible conflicts, MakerKit ships with a particular folder structure:

```
- app
  - routes
    - __site
    - __app
    - __auth
  - lib
  - components
```

These folders represent four separate layers. MakerKit is an Onion:

<Image
  width={'2103'}
  height={'1221'}
  src={'/assets/images/docs/architecture.png'}
  alt={"MakerKit's Remix Architecture"}
/>

### Core

Let's talk about the lower level: the `core`. This layer is a collection of building blocks, utilities, and APIs that make up MakerKit.

This part of the boilerplate is configurable and makes no assumptions about your domain.

You are still welcome to change this code to suit your needs, but you can expect most updates from upstream to change the code in this directory.

### Lib and Components

The mid-level is in two separate folders (to avoid excessive nesting):

- `lib`: here is where we write most domain-related business logic (hooks, contexts, queries, mutations, etc.)
- `components`: here is where we write the domain-related components (ex. Profile Page, Create Project form, etc.)

MakerKit comes with some business logic (it would be nearly impossible otherwise to build a genuinely functioning SaaS). You should customize the existing business logic for your application, and it is likely where you will add most of your code.

This layer can still be updated by the `upstream` repository, but you should not expect too many changes unless it's additions for new features or bug fixes.

### Routes

Finally, the `routes` layer is the outer layer of the application.

It's entirely dependent on your application, and you should not expect updates from upstream unless for fixing blatantly buggy code.

The kit splits the routes into three separate layouts:
- `__site`: the routes that are accessible to everyone, even if they are not logged in
- `__app`: the routes that are accessible only to logged-in users
- `__auth`: the routes that are accessible only to logged-in users, but only if they are not already logged in

## Import Flow

<Image width="1433" height="218" src="/assets/images/docs/nodejs-structure-imports-wrong.png" />

We use `eslint` to check that imports are flowing correctly through your application: if this feds you up, you can remove them from the `eslint` configuration at `/.eslintrc.json`;



Learn how MakerKit allows you to build a Remix application with a scalable and production-grade architecture and folder structure

Architecture and Folder Structure for your Remix SaaS application


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

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?

<Alert type='info'>
NB: entities rarely (or never) get added to "core". Business domain is added to "components" and "lib".
</Alert>

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`

```txt title="Structure"
- app
  - components
    - events
      - EventsContainerComponent.tsx
      - ...

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

  - routes
    - __app
      - events
        - index.tsx
        - $event.tsx
```

### 1) Adding the entity's business domain

We will add various business logic units in the `lib/events` folder, such as types, custom hooks, API calls, factories, functions, utilities, etc.

#### Types

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

```tsx title="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:

```tsx title="lib/events/hooks/use-fetch-events.ts"
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`. 

<Alert type='warn'>
  NB: remember to update the Firestore rules to be able to read the collection.
</Alert>

### 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`:

```tsx title="components/events/EventsListContainer.tsx"
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) Routes

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

```tsx title="routes/__app/events/index.tsx"
import EventsListContainer from '~/components/EventsListContainer';

const EventsPage: React.FC = () => {
  return (
     <EventsListContainer />
  );
};

export default EventsPage;
```

🎉 That's it! We have now built a nicely structured "events" domain.

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

Structure your Makerkit Application


MakerKit's data model is voluntarily as simple as possible, with a limited
set of assumptions.

MakerKit is not supposed to be a finite product but a solid foundation on which it is quick to get started and build your SaaS product.

To summarize, the Firestore model contains three main entities: `users`, `organizations`, and `invites`.

1. **Users**: a Firestore representation of the authentication database. In fact, to store data about users, we need to create a user record within our `/users` collection in Firestore
2. **Organizations**: Organizations are groups of users. Here, we store the list of members that belong to the organizations and everything that needs to be shared between the users: for example, templates, settings, integrations, and so on.
3. **Invites**: invites are a sub-collection of organizations used to store invitations that users can accept.

<Image src="/assets/images/docs/data-model.webp" width="1775" height="2436" />

## Users

Users are, of course, foundational to any application.

If a user signed in using Firebase Authentication, it merely means we have verified their credentials, not that they have an account.

We have to create an additional collection to store a user's data, such as:
- settings
- the memberships they belong to
- any other information which is not possible to update using their Authentication record (profile photo, name, email, and sign-in providers)

We only store the user's organizations as an object on the `users` collections by default.

The Firestore model looks like something similar:

```
- users
  - [userId]:
    - ... user data
```

We store the relationships between users and organizations within the
`Organizations` collection.

## Organizations

`Organizations` are groups of users.

If the name doesn't suit your domain, don't worry: you can always change the terminology using the localization files.

A user can belong to one or many organizations: each organization lists its members in an object, similar to what we do with `users`.

Below is what the `Organizations` schema looks like:

```
- organizations
  - [organizationId]
      - name
      - timezone
      - members
        - [memberId]
          - role
          - user // this is a Firestore reference
  }
```

Of course, we can assign a `name` to every organization and a `timezone` property (before you realize you're going to need it).

We define each membership by the user ID. Each membership contains the following information:

- the user role
- the user reference to `/users/[userId]`

Thus, we store the role in both collections to reduce the number of reads when we query the project members: we need to keep them in sync.

### User Roles

By default, MakerKit defines three roles: Owner (can be only one), Admin, and Member.

This enum is hierarchical and associated with a number:

```tsx
enum MembershipRole {
  Member,    // 0
  Admin,     // 1
  Owner      // 2
}
```

An Admin can do anything a member can do, and an Owner can do anything an Admin can.

### Invites

To create an invite to join an organization, we use a new collection
`invites` placed below an `organization` document: for example,
`/organizations/1/invites/1`.

The invite's interface is also straightforward:

```tsx
interface MembershipInvite {
  code: string;
  email: string;
  role: MembershipRole;
  expiresAt: number;

  organization: {
    id: string;
    name: string;
  };
}
```

- the `email` property represents the email of the user invited. The application supports users signing up with a different email: you have to change this if you wish to disallow it
- the `role` is the assigned role, which cannot be `Owner`
- the `code` property is the unique identifier from which the user can access
the invite through a link
- the `expiresAt` property is the Unix timestamp when the invite will
expire. By default, it's going to be one week
- the `organization` object duplicates some valuable data from its
parent (which saves us from rereading the document)


Learn how MakerKit defines the model of your SaaS application with Remix and Firebase

The MakerKit Data Model for your SaaS project built with Remix and Firebase

Learn how MakerKit authenticates your users, and how to set-up Firebase Auth


MakerKit uses Firebase to manage authentication within your application.

By default, every kit comes with the following built-in authentication methods:
- **Email/Password** - we added, by default, the traditional way of signing in
- **Third Party Providers** - we also added by default Google Auth sign-in
- **Email Links**
- **Phone Number**

You're free to add (or remove) any of the methods supported by Firebase's
Authentication: we will see how.

This documentation will help you with the following:
 - **Setup** - setting up your Firebase project
 - **SSR** - use SSR to persist your users' authentication, adding new
providers
 - **Customization** - an overview of how MakerKit works so that you can adapt
it to your own application's needs

## Configuration

The way you want your users to authenticate can be driven via configuration.

If you open the global configuration at `src/configuration.ts`, you'll find
the `auth` object:

```tsx title="configuration.ts"
auth: {
  enableMultiFactorAuth: true,
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: [GoogleAuthProvider],
  },
},
```

As you can see, the `providers` object can be configured to only display the
auth methods we want to use.

1. For example, by setting both `phoneNumber` and `emailLink` to `true`, the
authentication pages will display the `Email Link` authentication
 and the `Phone Number` authentication forms.
2. Instead, by setting `emailPassword` to `false`, we will remove the
`email/password` form from the authentication and user profile pages.

Additionally, we can choose to add one or multiple oAuth providers by adding
the Firebase provider to the `oAuth` array. For example, we could also add
Facebook, Twitter, and GitHub:

```tsx
import { FacebookAuthProvider, TwitterAuthProvider, GitHubAuthProvider } from
'firebase/auth';

oAuth: [
  GoogleAuthProvider,
  FacebookAuthProvider,
  TwitterAuthProvider,
  GitHubAuthProvider
],
```

Additionally, we can add custom oAuth providers. First, we define them by
extending the `OAuthProvider` class:

```tsx
class MicrosoftAuthProvider extends OAuthProvider {
  constructor() {
    super('microsoft.com');
  }
}

class AppleAuthProvider extends OAuthProvider {
  constructor() {
    super('apple.com');
  }
}
```

And then, we simply add them to the `oAuth` array:

```tsx
oAuth: [
  GoogleAuthProvider,
  MicrosoftAuthProvider,
  AppleAuthProvider
],
```

<Alert type={'warn'}>
  Remember that you will always need to enable the authentication methods
  you want to use from the Firebase Console once you deploy your application
  to production
</Alert>

## SSR

Using SSR, we set up MakerKit to persist the user's session on all the website's pages.

SSR allows for seamless integration between the pages of your website. For example, your pricing page could prompt users to upgrade to the new plan rather than what it shows to non-subscribers of your service.

Many websites use persistent sessions in different ways:

- personalized content
- pre-filled forms
- and a lot more

MakerKit uses Firebase Authentication to allow access to your Remix application using oAuth providers and email/password.

Setting up Firebase and Remix authentication with MakerKit


If you have completed the previous steps, you should have already created a Firebase Project and initialized the repository.

At this point, we can start setting up the authentication providers from the Firebase admin console.

While using the emulator, this step is not needed; feel free to skip this part in the beginning.

## Getting Started with Firebase Auth

From the Firebase console, navigate to the `Authentication` menu item using
the left-hand side panel.

<Image
  width={'1838'}
  height={'798'}
  src={'/assets/images/docs/auth-setup.webp'}
  alt={'Firebase Auth Getting Started'}
/>

After clicking on "Getting Started" you should see all the available providers that you can choose:

<Video src='/assets/images/docs/activate-sign-up.mp4' />

Please activate all the ones you're planning on using.

We have already configured MakerKit to work with:

 - Email/Password authentication
 - Google oAuth
 - Facebook oAuth (remember to create a FB app before going to production)
 - Email Links
 - Phone Number


Learn how to set up Firebase Auth in your Remix application

Setting up Firebase Auth with Remix


If you use SSR, the flow is slightly different from what you may be
used.

Typically, Firebase allows signing users in on the client-side. If you use SSR,
we need a way to authenticate the user on the server-side.

To do so, we use Firebase Auth's session cookies: we create the cookie when
the user signs in and then destroy it when the user signs out.

### Step 1: User signs in using the client SDK

The user can sign in (or up) using the Firebase Auth client SDK from the client side.

### Step 2: Creating a Session Cookie using an API endpoint

After being authenticated (signing in or up), the application requests to create and store a session cookie using an API endpoint.

The cookie is stored as an HTTP-only cookie and will be sent to the server,
so we can authenticate users right when we render the page.

When needed, we can perform the necessary redirects and security checks server-side.

### Step 3: User gets redirected to Application Home Page

The application renders a session-aware page if you have opted to use SSR on every page. Otherwise, the Firebase SDK should reflect the current session once the page has been rendered.

When the user is redirected to a protected page, the user's session authentication state is checked in the `loader` function of the `__app` layout.

### Step 4: User signs out

The client SDK starts a sign-out request when the user decides to sign out.

When Firestore Auth destroys the current user session, the event is intercepted by a listener and then calls the API endpoint to destroy the session cookie.

Here is an illustration of the flows:

<Image src="/assets/images/docs/auth-flow.png" width="2344" height="1166" />

## Keeping the client and server sessions in sync

Because the Firebase Session cookies expire after 14 days, we need to keep the client SDK session in sync when the session cookie expires.

To do so, when the user signs in, we also store a cookie with the expiration date. When the client SDK detects that the server-side session cookie expired, the user gets automatically signed out.


Learn how MakerKit handles the authentication flow with Firebase Auth and Remix

Firebase and Remix authentication flow


By default, the kit uses Google as the third-party provider to allow users
to access the application.

With that said, you could decide to add other providers that Firebase provides or even custom ones.

## Customizing the Third Party providers

To add one or multiple oAuth providers, we will need to customize the global
configuration by adding the Firebase provider to the `oAuth` array.

For example, we could also add Facebook, Twitter, and GitHub:

```tsx title="configuration.ts"
import { FacebookAuthProvider, TwitterAuthProvider, GitHubAuthProvider } from
'firebase/auth';

{
  auth: {
    providers: {
      oAuth: [
        GoogleAuthProvider,
        FacebookAuthProvider,
        TwitterAuthProvider,
        GitHubAuthProvider
      ],
    }
  }
}
```

Additionally, we can add custom oAuth providers. First, we define them by
extending the `OAuthProvider` class:

```tsx
class MicrosoftAuthProvider extends OAuthProvider {
  constructor() {
    super('microsoft.com');
  }
}

class AppleAuthProvider extends OAuthProvider {
  constructor() {
    super('apple.com');
  }
}
```

And then, we simply add them to the `oAuth` array:

```tsx
oAuth: [
  GoogleAuthProvider,
  MicrosoftAuthProvider,
  AppleAuthProvider
],
```

<Alert type={'warn'}>
  <p>
    Remember that you will always need to enable the authentication methods
    you want to use from the Firebase Console once you deploy your application
    to production.
  </p>

  <p>
    Often, these need an additional configuration you need to
    enable on the provider's end.
  </p>
</Alert>

## Adding Additional Scopes

To add additional scopes to the oAuth provider, we can tweak the
`OAuthProviders.tsx` component and assign the scopes based on the instance type:

```tsx title="OAuthProviders.tsx"
import {
  GoogleAuthProvider,
  FacebookAuthProvider,
} from 'firebase/auth';

{OAUTH_PROVIDERS.map((OAuthProviderClass) => {
  const providerInstance = new OAuthProviderClass();
  const providerId = providerInstance.providerId;

  if (providerInstance instanceof GoogleAuthProvider) {
    providerInstance.addScope('scope');
  }

  if (providerInstance instanceof FacebookAuthProvider) {
    providerInstance.addScope('scope');
  }

   return (
     // render <AuthProviderButton />
   );
});
```

For example, if you are adding the scopes for Facebook Login, [you can check
out the Firebase documentation](https://firebase.google.com/docs/auth/web/facebook-login). Then, add them to the `addScope` method
as described above.


Learn how to setup Third-Party oAuth providers with Firebase Auth in your Remix MakerKit application

Set up Third party authentication providers with Remix and Firebase


Makerkit provides a component and a route to sign your users in using an Email Link.

Thanks to Email Links Authentication, users can enter their email and then sign in by clicking on the link they received to their email.

<Alert type='warn'>
  Remember, when using this authentication method in production, ensure you manually activate it from the Firebase Console first.
</Alert>

Navigate to the `configuration.ts` file, and let's switch the
`email/password` method with `email link`:

```tsx title="configuration.ts"
{
  auth: {
    providers: {
      emailPassword: false, // we switch this to false
      phoneNumber: false,
      emailLink: true, // we switch this to true
      oAuth: [GoogleAuthProvider, FacebookAuthProvider],
    },
  }
}
```

That's it! The result should be similar to the image below:

<Image src="/assets/images/posts/email-link-authentication.webp" width="1128" height="1206" />

Ok, cool, **but can you use both?**

Yes, of course! With that said, you may need to tweak the
UI so that the result will look nice.


Learn how to setup Email Link Authentication with Firebase Auth in your MakerKit application

Set up Email Link Authentication with Remix and Firebase


Multi-Factor Authentication allows users to add an additional layer of protection when logging in to a website, which is ideal for services that tend to be more sensitive or where privacy is paramount. 

At the time of writing, Firebase Auth supports only SMS MFA.

## Enabling Multi-Factor Authentication

Enabling MFA in your Makerkit application requires two steps:

1. You need to upgrade to [Google Cloud Identity Platform](https://cloud.google.com/identity-platform/docs/product-comparison) from the Firebase Console, as it is needed to support MFA
2. Flipping the variable `auth.enableMultiFactorAuth` to `true` in the configuration file, as it is disabled by default

```tsx title="configuration.ts"
auth: {
  // flip this to "true"
  enableMultiFactorAuth: true,
}
```

After enabling MFA, users can set it up from the `Authentication` page at `/settings/authentication`.

<Video src="/assets/images/posts/enabling-multi-factor-authentication.mp4" />

Learn how to setup Multi Factor Authentication with Firebase Auth in your MakerKit application

Set up Multi-Factor Authentication


By default, Firebase does not enforce email verification. This means that users can sign up with an email address and password, and then immediately start using your app. However, you may want to require that users verify their email address before they can use your app.

To do so, Makerkit can check that the user has verified their email address before allowing them to use your app from the server side. How? When loading the server side session, we check that the user's property `emailVerified` is `true`. If not, the user is redirected to the sign in page, and signed out.

By default, **this feature is disabled**. To enable it, you need to set the environment variable `REQUIRE_EMAIL_VERIFICATION` to `true`.

## Enabling requiring email verification

Simply set the following environment variable to `true`:

```bash
REQUIRE_EMAIL_VERIFICATION=true
```

That's pretty much it!

NB: invited users are not required to verify their email address, since they are already verified by having received the invitation by email.

Learn how to enforce email verification for your users with Firebase.

Requiring Email verification


App Check is a Firebase service that helps you to protect your web app from
bots, spammy users, and general abuse detected by Google's Recaptcha.

The Makerkit SaaS starter is already configured to secure your application with Firebase AppCheck, but you will need to set it up in the Firebase Console first.

### Registering your website for Recaptcha v3

[To register your website for Recaptcha v3, you need to complete the linked form](https://www.google.com/recaptcha/admin/create). After entering the details, you'll be provided with a `Site Key`, which we use to initialize the Firebase AppCheck service.

<Image src="/assets/images/posts/create-recaptchha-key.webp" width="1494" height="878" />

NB: when registering the website, create a **Recaptcha v3** key, not v2.

After submitting the form, you will receive two keys:

1. a public key (on the client side)
2. a private key (to be used on the server side)

Save the public key and add it to your Remix `.env` file:

```
APPCHECK_KEY=<YOUR_KEY>
```

### Enabling Firebase App Check from the console

First, we need to enable Firebase App Check from the Firebase Console to register our application using the keys we have generated in the previous step.

<Image src="/assets/images/posts/register-app-check.webp" width="2850" height="902" />

Above, you should have added the secret key that we have generated. If it all went well, you have successfully enabled app-check for your application 🎉!

#### Enforcing Firestore to use App Check

To enforce Firestore to always validate requests using AppCheck, you must enable it from the Console. From where you are, click on the `API` tab, then click on `Firebase Firestore`. You will then be presented with the popup as in the image below:

<Image src="/assets/images/posts/enforce-appcheck-firestore.webp" width="1752" height="1340" />

Continue and enforce Firestore to use AppCheck.

### Testing AppCheck

AppCheck will not work in emulator mode, so you have two options to ensure it's working as intended:

- run a production build locally
- or simply deploy your applications


Learn how to set up Firebase AppCheck in your MakerKit application to protect your application from abuse

Protect your Remix application from abuse using Firebase AppCheck


Makerkit provides a set of React hooks to help you manage authentication in your React application. These hooks are an addition to the ones provided by `reactfire`.

## useUserSession

This hook returns the current user session. It contains the user's auth data from Firebase, and its data record from Firestore. Basically, it wraps the `UserSessionContext` value.

```tsx
import { useUserSession } from "~/core/hooks/use-user-session";

const userSession = useUserSession();
```

## useUserId

This hook returns the current user's ID.

```tsx
import { useUserId } from "~/core/hooks/use-user-id";

const userId = useUserId();
```

## useCreateServerSideSession

This hook returns a function that can be used to create a server-side session. It is useful for creating a session when a user logs in, or when a user is created.

You shouldn't be needing this unless you're customizing the authentication flow.

```tsx
import { useCreateServerSideSession } from "~/core/hooks/use-create-server-side-session";

const [sessionRequest, { loading, error }] = useCreateServerSideSession();
```

Reference for the authentication React hooks

Authentication React Hooks


Here are some common issues with authentication and how to fix them.

## I keep getting signed out after signing in

**Possible cause**: You are using the wrong Firebase private key.

This issue is usually caused by a misconfigured Firebase private key. Make sure you are using the correct private key and that it is not expired.

The Firebase private key is downloaded from the JSON Service Account file after you create a new service account in the Firebase console

The key looks like this:

```
-----BEGIN PRIVATE KEY-----
***************************
-----END PRIVATE KEY-------
```

It's much longer than the above, but you get the idea.

The key needs to be added to your environment variables settings. Please use your CI to add this key since it's a secret key:

```
FIREBASE_PRIVATE_KEY=
```

Authentication Troubleshooting

Learn the MakerKit best practices for building and shipping your app

Data Fetching


Similarly to reading data from Firestore, we may want to create a `custom
hook`` also when we write, update or delete data.

Assuming we have an entity called `tasks`, and we want to create a hook to
create a new `Task`, we can do the following.

1. First, we create a new hook at `lib/tasks/hooks/use-create-task.ts`
2. We add the `tasks` collection name to `lib/firestore-collections`
3. Wrap the `addDoc` function from Firestore within a `useCallback` hook

```tsx title="lib/tasks/hooks/use-create-task.ts"
import { TASKS_COLLECTION } from '~/lib/firestore-collections';

function useCreateTask() {
  const firestore = useFirestore();
  const tasksCollection = collection(firestore, TASKS_COLLECTION);

  return useCallback(
    (task: Task) => {
      return addDoc(tasksCollection, task);
    },
    [tasksCollection]
  );
}
```

And now, we could use this hook within a component:

```tsx
function Component() {
  const createTask = useCreateTask();

  return <MyForm onSubmit={task => createTask(task)} />
}
```

Let's take a look at a complete example of a form that makes a request using
the hook above:

```tsx title="components/tasks/NewTaskForm.tsx"
const CreateTaskForm = () => {
  const createTask = useCreateTask();
  const { setLoading, state } = useRequestState();
  const router = useRouter();
  const organization = useCurrentOrganization();
  const organizationId = organization?.id as string;

  const onCreateTask: FormEventHandler<HTMLFormElement> = useCallback(
    async (event) => {
      event.preventDefault();

      const target = event.currentTarget;
      const data = new FormData(target);
      const name = data.get('name') as string;
      const dueDate = data.get('dueDate') as string;

      setLoading(true);

      const task = {
        organizationId,
        name,
        dueDate,
        description: ``,
        done: false,
      };

      await toaster.promise(createTask(task), {
        success: `Task created!`,
        error: `Ops, error!`,
        loading: `Creating task...`,
      });

      await router.push(`/tasks`);
    },
    [router, createTask, organizationId, setLoading]
  );

  return (
    <div>
      <form onSubmit={onCreateTask}>
        <div className={'flex flex-col space-y-3'}>
          <TextField.Label>
            Name
            <TextField.Input
              required
              name={'name'}
              placeholder={'ex. Launch on IndieHackers'}
            />
            <TextField.Hint>Hint: whatever you do, ship!</TextField.Hint>
          </TextField.Label>

          <TextField.Label>
            Due date
            <TextField.Input
              required
              defaultValue={getDefaultDueDate()}
              name={'dueDate'}
              type={'date'}
            />
          </TextField.Label>

          <div
            className={
              'flex flex-col space-y-2 md:space-y-0 md:space-x-2' +
              ' md:flex-row'
            }
          >
            <Button loading={state.loading}>
              <If condition={state.loading} fallback={<>Create Task</>}>
                Creating Task...
              </If>
            </Button>

            <Button color={'transparent'} href={'/tasks'}>
              Go back
            </Button>
          </div>
        </div>
      </form>
    </div>
  );
};

function getDefaultDueDate() {
  const date = new Date();
  const year = date.getFullYear();
  const month = pad(date.getMonth() + 1);
  const day = pad(date.getDate() + 1);

  return `${year}-${month}-${day}`;
}

function pad(n: number) {
  return n < 10 ? `0${n}` : n.toString();
}

export default CreateTaskForm;
```


Learn how to write, update and delete data using Firestore in Makerkit

Writing data to Firestore


When fetching data from Firestore, we use the hooks provided by `reactfire`,
although you could also use plain functions from the Firebase SDK if you
preferred.

To make data-fetching from Firestore more reusable, our convention is to
create a custom React hook for each query we make.

For example, let's take a look at the hook to fetch an organization from
Firestore:

```tsx title="use-fetch-organization.ts"
import { useFirestore, useFirestoreDocData } from 'reactfire';
import { doc, DocumentReference } from 'firebase/firestore';
import { Organization } from '~/lib/organizations/types/organization';
import { ORGANIZATIONS_COLLECTION } from '~/lib/firestore-collections';

type Response = WithId<Organization>;

export function useFetchOrganization(
  organizationId: string
) {
  const firestore = useFirestore();

  const ref = doc(
    firestore,
    ORGANIZATIONS_COLLECTION,
    organizationId
  ) as DocumentReference<Response>;

  return useFirestoreDocData(ref, { idField: 'id' });
}

export default useFetchOrganization;
```

Let's explain the above:

1. First, we get the Firestore instance using `useFirestore`
2. We create a Firestore reference to the path of the organization collection
3. Strong-type the document reference `as DocumentReference<Response>` so
that Typescript will correctly infer the following usages of the reference
4. Finally, we request the data using the hook `useFirestoreDocData,` which will
 return the record's data.

NB: Additionally, we tell Firestore to
add the `id` of the field to the object's dat using `{ idField: 'id' }`.
This is why the interface returned is `WithId<Organization>`. We're
basically telling Typescript that the data returned is the combination of
the following interfaces:

```tsx
interface WithId {
  id: string;
}

interface Organization {
  // ...
}
```

This is very useful, as often times you will need the IDs of your Firestore
documents on the client-side.

When you create a new Firestore collection, remember to:
1. Add the required Firestore rules
2. Store and read the name of the collection from
`~/lib/firestore-collections`:
this helps you avoid magic strings when typing your collection names
3. Create hooks to fetch data. Usually, we store these in `lib/<entity>/hooks`

### Consuming data from the Firestore hooks

Reactfire's custom hooks help us fetch data from Firestore effortlessly, but
we need to pay attention when using them due to their asynchronous nature.

For example, let's see how we can use the hook above correctly by displaying
a different UI based on the status of the hook:

```tsx
import { useFetchOrganization } from './use-fetch-organization';

function OrganizationCard({ organizationId }) {
  const {
    data: organization,
    status,
  } = useFetchOrganization(organizationId);

  /* data is loading */
  if (status === `loading`) {
    return <div>Loading...</div>
  }

  /* request errored */
  if (status === `error`) {
    return <div>Error!</div>
  }

  /* request successful, we can access "organization" */
  return <div>{organization.name}</div>;
}
```

### Fetching data from a collection using a Firestore query

Fetching data from a collection using a query is a common scenario.

For example, we assume you have a collection named `tasks`, with a foreign key
`organizationId` represents the ID of the organization to which it belongs.

Of course, you will want to write a query to fetch a list of tasks for your
organization.

When we define our entity, we will need to add a key `organizationId` so we
can match it against the ID of the organization it belongs to. For example,
take a look at the `Task` interface below:

```tsx
export interface Task {
  name: string;
  description: string;
  dueDate: string;
  done: boolean;

  // here we use organizationId as a foreign key
  organizationId: string;
}
```

Now, we can write a hook that gets a list of `tasks` that have
`organizationId` equal to the one we pass:

```tsx
import { useFirestore, useFirestoreCollectionData } from 'reactfire';

import {
  collection,
  CollectionReference,
  query,
  where,
} from 'firebase/firestore';

import { Task } from '~/lib/tasks/types/task';

function useFetchTasks(organizationId: string) {
  const firestore = useFirestore();
  const tasksCollection = 'tasks';

  const collectionRef = collection(
    firestore,
    tasksCollection
  ) as CollectionReference<WithId<Task>>;

  const path = `organizationId`;
  const operator = '==';
  const constraint = where(path, operator, organizationId);
  const organizationsQuery = query(collectionRef, constraint);

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

export default useFetchTasks;
```

### Security Rules

What about securing our Firestore database? We will use Firestore's security
rules. During development, you can update the `firestore.rules` file in your
root folder, but remember that you need to propagate these to your Firebase
instance using the console.

The functions `userIsMemberByOrganizationId` and `isSignedIn` are added by
default to the Makerkit's starter:

```js title="firestore.rules"
match /tasks/{taskId} {
  allow create: if isSignedIn();
  allow read, update, delete: if userIsMemberByOrganizationId(existingData().organizationId);
}
```

## Strong Typing

When reading data, it's necessary to strong-type your queries. While the
Firebase SDK isn't exactly type-friendly in some situations; we can make it
work by casting references to the correct type.

### Casting Documents References

When casting Firestore documents, you can use `as DocumentReference<T>`:

```tsx
const organizationRef = doc(
  firestore,
  ORGANIZATIONS_COLLECTION,
  organizationId
) as DocumentReference<WithId<Organization>>;
```

When getting the response from Firestore, the type will be correctly
inferred as `WithId<Organization>`.

### Casting Collections References

When casting Firestore collections, you can use `as CollectionReference<T>`:

```tsx
const collectionRef = collection(
  firestore,
  tasksCollection
) as CollectionReference<WithId<Task>>;
```


Learn how fetch data from your Firestore database in Makerkit

Fetching data from Firestore


To make requests to the API functions in the `api` folder, we provide a
custom hook `useApiRequest`, a wrapper around `fetch`.

It has the following functionality:

1. Uses an internal `state` to keep track of the state of the request, like
`loading`, `error` and `success`. This helps you write fetch requests the
"hooks way"
2. Automatically adds a `Firebase AppCheck Token` to the request headers if you
enabled Firebase AppCheck
3. Automatically adds a `CSRF token` to the request headers

Similarly to making Firestore Requests, it's a convention to create a custom
hook for each request for readability/reusability reasons.

```tsx title="src/core/hooks/use-create-session.ts"
import useApiRequest from '~/core/hooks/use-api';

interface Body {
  idToken: string;
}

export function useCreateSession() {
  return useApiRequest<void, Body>('/api/session/sign-in');
}
```

The hook returns an array with:
1. the callback to make the request
2. the state object of the request

```tsx
const [createSession, createSessionState] = useCreateSession();
```

The state object internally uses `useApiRequest`, and has the following
interface:

```tsx
{
  success: boolean;
  loading: boolean;
  error: string;
  data: T | undefined;
}
```

When `success` is `true`, the property `data` is inferred with its correct type.

You can use this hook in your components:

```tsx
import { useCreateSession } from '~/core/hooks/use-create-session';

function Component() {
  const [createSession, createSessionState] = useCreateSession();

  return (
    <>
      { createSessionState.loading ? `Loading...` : null }
      { createSessionState.error ? `Error :(` : null }
      { createSessionState.success ? `Yay, success!` : null }

      <SignInForm onSignIn={(idToken) => createSession({ idToken })} />
    </>
  );
}
```

Similarly, you can also use it to fetch data:

```tsx
import { useCreateSession } from '~/core/hooks/use-create-session';

function Component() {
  const [fetchMembers, { loading, error, data }]
    = useFetchMembers();

  // fetch data when the component mounts
  useEffect(() => {
    fetchMembers();
  }, [fetchMembers]);

  if (loading) {
    return <div>Fetching members...</div>;
  }

  if (error) {
    return <div>{error}</div>;
  }

  return (
    <div>
      {data.map(member => <MemberItem member={member} />)}
    </div>
  );
}
```


Learn how to make requests to your Remix API in Makerkit

API requests


## 1) Add the Storage Provider

First, we need to wrap the component using Firebase Storage with the
`FirebaseStorageProvider`, which is responsible for initializing the
Firebase Storage SDK.

```tsx
import FirebaseStorageProvider from '~/core/firebase/components/FirebaseStorageProvider';

<FirebaseStorageProvider>
  <ComponentThatUsesStorage />
</FirebaseStorageProvider>
```

## 2) Create a Hook to fetch data from Storage

Let's assume we want to fetch a list of files from storage by getting their
`url`. This is a common scenario for retrieving images stored in Firebase
Storage.

```tsx
function useOrganizationAssets() {
  const storage = useStorage();

  const { setData, setError, setLoading, state } =
    useRequestState<MediaItem[]>();

  const path = `/${organizationId}/uploads`;
  const reference = ref(storage, path);

  useEffect(() => {
    void (async () => {
      try {
        const result = await list(reference);

        const items = await Promise.all(
          result.items.map(async (item) => {
            const url = await getDownloadURL(item);

            return url;
          })
        );

        setData(items);
      } catch (e) {
        setError(e);
      }
    })();
  }, [reference, setData, setError]);

  return state;
}
```

## 3) Use the custom hook in your components

And then we can use the hook in our components:

```tsx
function MyImages() {
  const { data, loading, error } = useOrganizationAssets();

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>We could not fetch your images :(</p>;
  }

  return (
    <div className={'flex flex-col space-y-2'}>
      {data.map(image => {
        return <img src={image} key={image} />
      })}
    </div>
  );
}
```


Reading data from Storage


When uploading data to storage, the data needs to be secured so that it
can only be accessed by the organization that created it; we need to add the
organization ID to the file's custom data.

By doing so, we will be able to
compare the custom data ID with the user's organization ID, and verify they
match.

## 1) Add the Storage Provider

First, we need to wrap the component using Firebase Storage with the
`FirebaseStorageProvider`, which is responsible for initializing the
Firebase Storage SDK.

```tsx
import FirebaseStorageProvider from '~/core/firebase/components/FirebaseStorageProvider';

<FirebaseStorageProvider>
  <ComponentThatUsesStorage />
</FirebaseStorageProvider>
```

## 2) Using the Firebase Storage SDK

Now we can use the Firebase Storage SDK by using the `useStorage` hook. From
Here, we can simply use the SDK described by the Firebase documentation.

```tsx
const storage = useStorage();
```

Let's assume we have a function `uploadFile` that receives a `File`
parameter, and that we need to upload to Firebase Storage:

```tsx
import { ref, uploadBytes } from 'firebase/storage';
import toaster from 'react-hot-toast';
import { useStorage } from 'reactfire';
import { useCurrentOrganization } from './use-current-organization';

function Component() {
  const storage = useStorage();
  const organization = useCurrentOrganization();

  async function uploadFile(file: File) {
    if (!organization) return;

    const organizationId = organization.id;
    const path = `/${organizationId}/uploads/${file.name}`;
    const reference = ref(storage, path);

    const promise = uploadBytes(reference, file, {
      cacheControl: 'max-age=31536000',
      customMetadata: {
        organizationId,
      },
    });

    await toaster.promise(promise, {
      success: `Yay, uploaded!`,
      loading: `Uploading...`,
      error: `Error :(`
    });
  }

  return <UploadForm onFileChosen={uploadFile} />
}
```

## 3) Security Rules for Storage

As you can see from the code above, we are setting some custom metadata when we
upload the file:

```ts
customMetadata: {
  organizationId,
},
```
By doing this, we're effectively telling the file to store `organizationId`
as metadata on the file.

This will help us with the Storage security rules
for disallowing users in other organizations from reading the file:

```js
match /organizations/{organizationId}/{fileName=**} {
  allow read: if resource.metadata.organizationId == request.auth.token.organizationId;
  allow write: if request.auth.token.organizationId == organizationId;
}
```


Uploading data to Storage


By default, MakerKit uses a custom hook that wraps the browser's `fetch` to make it easier to use with React's components named `useApiRequest`. 

Additionally, this custom hook automatically adds two headers for security reasons: 
- `X-Firebase-AppCheck` - which is the token generated when using **Firebase AppCheck**
- `x-csrf-token` - the page's CSRF token generated when the page is server-rendered. It's needed to protect the page from CSRF attacks.

Since the `useApiRequest` hook is pretty basic, if you make complex queries to your API, you may want to use a more complete implementation such as `react-query` or `swc`. However, If you don't make complex queries, it can be unnecessary since most of your queries will be to Firestore, which uses its own client-side data-fetching method.

To make these libraries seamlessly work with the API, you only need to consider the headers above if the API uses them to protect your application's endpoints.

### Generating an App Check Token

To generate an App Check token, you can use the `useGetAppCheckToken` hook:

```tsx
const getAppCheckToken = useGetAppCheckToken();
const appCheckToken = await getAppCheckToken();

console.log(appCheckToken) // token
```

You will need to send a header `X-Firebase-AppCheck` with the resolved value returned by the promise `getAppCheckToken()`.

### Sending the CSRF Token

To retrieve the page's CSRF token, you can use the `useGetCsrfToken` hook:

```tsx
const getCsrfToken = useGetCsrfToken();
const csrfToken = getCsrfToken();

console.log(csrfToken) // token
```

You will need to send a header `x-csrf-token` with the value returned by `getCsrfToken()`.

Guide to writing your own fetch implementation

Writing your own Fetch

Development


Here are all the commands defined in the MakerKit's template:

### Run the development server

Run the command:

```
npm run dev
```

### Build a production bundle

Run the command:

```
npm build
```

### Start a production server

Run the command after building the application with the `build` command:

```
npm start
```

This is optional as it is automatically called after the `build` command.

### Format all the files

Run the command:

```
npm run format
```

### Start the Firebase Emulator

Run the command:

```
npm run firebase:emulators:start
```

This is needed during development.

### Export data from the Firebase Emulator

Run the command:

```
npm run firebase:emulators:export
```

### Run Cypress for E2E Tests (with UI)

Run the command:

```
npm run cypress
```

### Run Cypress for E2E Tests (Headless)

Run the command:

```
npm run cypress:headless
```

### Run E2E Tests and Exit

Run the command:

```
npm test:e2e
```

### Run the Local Stripe Webhooks Server

This is needed if you are testing Stripe. This command requires Docker, but you can alternatively install Stripe on your OS and change the command to use `stripe` directly.

Run the command:

```
npm run stripe:listen
```

### Run the Mock Stripe Server

Run the command:

```
npm run stripe:mock-server
```

### Kill Ports

The following commands kills all the ports that need to be free to run the Makerkit stack. This can be necessary after running the tests, for example when the emulators don't free up the ports after shutting down.

Run the command:

```
npm run killports
```


All the commands to use for your Makerkit app


The Makerkit's boilerplate codebase is formatted with *Prettier*. You can configure it as you wish by updating the file Prettier configuration in the `package.json` file:

The default settings look like the below:

```json
{
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "arrowParens": "always",
  "parser": "typescript",
  "printWidth": 80,
  "singleQuote": true
}
```

For example, to remove semicolons, update the `semi` and set it to `false`.

After adjusting the Prettier configuration, you can reformat the whole project by running the following command:

```
npm run format
```


Adjust the codebase style according to your preferences


When running the Firebase Emulator, you can update your Firebase Firestore and Storage security rules by simply changing the files `firestore.rules` and `storage.rules`.

### Firestore Security Rules

By default, Makerkit comes with pre-configured Security Rules that work with the original boilerplate's data structure. However, you will likely be updating your structure to fit your SaaS data model, and therefore you will probably be updating the Firestore Security Rules.

To change your Firestore security rules, simply edit the `firestore.rules` file in the root directory of your Makerkit repository; the Firebase Emulator will automatically pick the new changes up.

### Storage Security Rules

At the moment, Makerkit does not add any security rule for your Storage buckets; this will be added very soon.

### Publish your rules

Publishing your security rules is a critical pre-production step you should never forget; otherwise, your users will encounter runtime exceptions, ultimately leading to bugs in your app.

<Alert type='warn'>
  Remember: updating your repository's rules does not automatically publish them!
</Alert>

To publish your Security rules, open your Firebase Admin Console and copy-paste the content of your security rules. It can take some time before they fully propagate.


Setting up your Firebase Security Rules during development


Much of the MakerKit's codebase uses translations using the package `next-i18next':

- this package allows you to create multi-language apps effortlessly
- it also helps easily renaming the Makerkit's entities according to your preferences: for example, renaming "organizations" to another entity such as "team" or "workspace"
- in a way, it helps write cleaner HTML

To add or update the default strings, you must use the locale files at `public/locales/{lang}.json`. For example, all the locale files for the English language are placed under `public/locales/en`.

<Alert type='warn'>
  When adding new keys, you'll need to restart the MakerKit server (npm run
  dev) to see the changes.
</Alert>

The locales are split by functionality, page, or entity: as your application grows, you may not want to load every JSON file to reduce your bundle size.

For example, the translations for the authentication are placed in `auth.json,` while the ones used across every page are placed under `common.json.`

If you are unsure where to add some translations, simply add them to `common.json`.

<Alert type='info'>
  To simplify things, the MakerKit's starter uses all the available JSON files, and we recommend doing so until you have too many files.
</Alert>

### Adding new languages

By default, Makerkit uses English for translating the website's text. All the files are stored in the files at `/public/locales/en`.

Adding a new language is very simple:
1. **Translation Files**: First, we need to create a new folder, such as `/public/locales/es`, and then copy over the files from the English version and start translating files.
2. **Remix i18n config**: We need to also add a new language to the Remix configuration at `app/i18n/i18next.config.ts`. Simply add your new language's code to the `locales` array.

The configuration will look like the below:

```js title="app/i18n/i18next.config.ts"
const i18Config = {
  fallbackLanguage: DEFAULT_LOCALE,
  supportedLanguages: [DEFAULT_LOCALE, 'es'],
  defaultNS: ['common', 'auth', 'organization', 'profile', 'subscription'],
  react: { useSuspense: false },
};
```

To add new locale files by default, add them to the `defaultNS` array.

#### Setting the default Locale

To set the default locale, simply update the environment variable `DEFAULT_LOCALE` stored in `.env`.

So, open the `.env` file, and update the variable:

```txt title=".env"
DEFAULT_LOCALE=de
```

## Using the Language Switcher

The MakerKit kits come with a language switcher that allows users to switch between the available languages. This is not enabled by default, but you can easily add it anywhere in your application by importing the `LanguageSwitcherDropdown` component from `~/components/LanguageSwitcherDropdown`. 

It does not require any props, and it will automatically detect the available languages and display them in a dropdown.

If you want to customize the language switcher or use a different component, you can leverage the `useChangeLanguage` hook to change the language and store the selection as a cookie, which will then be used to set the default language.

Adding and updating locales in your Makerkit application


MakerKit uses the popular package `nodemailer` to allow you to send emails.

Normally, you would use a service for sending transactional emails such as SendGrid, Mailjet, MailGun, Postmark, and so on.

These are all valid, and it doesn't really matter what you use. In
fact, as long as you provide the SMTP credentials for your service, you shouldn't be needing any other change.

## Email Configuration

To add your service's configuration, fill the `email` object in your configuration file at `src/configuration.ts`:

```tsx
email: {
  host: '',
  port: 0,
  user: '',
  password: '',
  senderAddress: 'MakerKit Team <test@makerkit.dev>',
}
```

The details above are provided by the service you're using.

<Alert type='warn'>
  When running the emulators, by default, Makerkit uses Ethereal for sending emails, and not your production service. Read below for more info.
</Alert>

## Sending Emails

To send emails, import and use the `sendEmail` function, such as below:

```tsx
interface SendEmailParams {
  from: string;
  to: string;
  subject: string;
  text?: string;
  html?: string;
}

import { sendEmail } from '~/core/email/send-email';

function sendTransactionalEmail() {
  const sender = configuration.email.senderAddress;

  return sendEmail({
    to: `youruser@email.com`,
    from: sender,
    subject: `Achievement Unlocked!`,
    html: `Yay, you unlocked an achievement!`,
  });
}
```

## Using react.email to render emails

Makerkit's newest versions use [react-email](https://react.email) to render emails: this is a great library that allows us to write emails using React components.

By default, Makerkit's only email is the one sent when inviting members to a Makerkit application - but you can leverage this library to write your own emails for your application.

For example, here's the code for the email sent when inviting members:

```tsx title="src/lib/emails/invite.ts"
interface Props {
  organizationName: string;
  organizationLogo?: string;
  inviter: Maybe<string>;
  invitedUserEmail: string;
  link: string;
  productName: string;
}

export default function renderInviteEmail(props: Props) {
  const title = `You have been invited to join ${props.organizationName}`;

  return render(
    <Html>
      <Head>
        <title>{title}</title>
      </Head>
      <Preview>{title}</Preview>
      <Body style={{ width: '500px', margin: '0 auto', font: 'helvetica' }}>
        <EmailNavbar />
        <Section style={{ width: '100%' }}>
          <Column>
            <Text>Hi,</Text>

            <Text>
              {props.inviter} with {props.organizationName} has invited you to
              use {props.productName} to collaborate with them.
            </Text>

            <Text>
              Use the button below to set up your account and get started:
            </Text>
          </Column>
        </Section>

        <Section>
          <Column align="center">
            <CallToActionButton href={props.link}>
              Join {props.organizationName}
            </CallToActionButton>
          </Column>
        </Section>

        <Section>
          <Column>
            <Text>Welcome aboard,</Text>
            <Text>The {props.productName} Team</Text>
          </Column>
        </Section>
      </Body>
    </Html>
  );
}
```

## Using MJML to render emails (deprecated)

**If you're using a newer version of Makerkit, this section is deprecated.**.

Thanks to MJML, we can write emails using handy web components (or HTML tags).

In addition, using `react-mjml`, [we can use React components to compose our emails](https://github.com/wix-incubator/mjml-react). Wonderful, right?

Makerkit provides two MJML emails:

1. The email sent when inviting members
2. The email sent when an asynchronous payment

You can find these emails at `src/lib/emails`.

#### Using MJML with React

Let's assume we want to write a Welcome email using React and the `sendEmail` utility above.

```tsx title="src/lib/emails/welcome.ts"
function renderWelcomeEmail(props: {
  name: string;
  link: string;
}) {
  const title = `Hey, ${props.name}, Welcome!`;

  return render(
    <Mjml>
      <MjmlHead>
        <MjmlTitle>{title}</MjmlTitle>
        <MjmlPreview>{title}</MjmlPreview>
      </MjmlHead>

      <MjmlBody width={500}>
        <EmailNavbar />

        <MjmlSection fullWidth>
          <MjmlColumn>
            <MjmlText>Hi ${props.name}</MjmlText>

            <MjmlText>
              We're super glad to have you with us!
            </MjmlText>
          </MjmlColumn>
        </MjmlSection>

        <MjmlSection>
          <MjmlColumn>
            <CallToActionButton href={props.link}>
              Sign In
            </CallToActionButton>
          </MjmlColumn>
        </MjmlSection>

        <MjmlSection>
          <MjmlColumn>
            <MjmlText>Welcome aboard</MjmlText>
          </MjmlColumn>
        </MjmlSection>
      </MjmlBody>
    </Mjml>,
    { validationLevel: 'soft' }
  );
}
```

Now, let's write a function that renders the MJML email and sends it to our user:

```tsx
function sendTransactionalWelcomeEmail(props: {
  user: string;
  email: string;
}) {
  const { html, errors } = renderInviteEmail({
    link: `https://makerkit.dev/sign-in`,
    name: props.user,
  });

  if (errors.length) {
    throw new Error(
      `Found errors while rendering email: ${JSON.stringify(errors)}`
    );
  }

  return sendEmail({
    to: props.email,
    from: configuration.email.senderAddress,
    subject: `Welcome to Makerkit`,
    html,
  });
}
```

That's it! Learn more about [react-mjml](https://github.com/wix-incubator/mjml-react).

## Testing Emails

By default, when running the Firebase Emulators, Makerkit will use [Ethereal](https://ethereal.email) as an email transport provider. This service allows us to test our emails for free.

To configure Ethereal, subscribe to the service and grab the credentials generated for you. Then, add them as environment variables:

```
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
```

Alternatively, **Makerkit will generate these credentials for you**. Every time you send an email, the credentials are printed to the console so that you can grab them and inspect the emails sent: feel free to add these as your environment variables if you haven't added them yet. In this way, you will always reuse the same Ethereal account.


Sending emails with a Makerkit application


[Zod](https://github.com/colinhacks/zod) is a Typescript library that helps us
secure our API endpoints by validating the payloads sent
from the client and also facilitating the typing of the payloads with
Typescript.

Using Zod is the first line of defense to validate the data sent against our
API: as a result, it's something we recommend you keep doing. It ensures we
write safe, resilient, and valid code.

All Makerkit's API routes are secured with Zod: in this document, we want
to explain the conventions used by the SaaS Boilerplate, and how to use it
for your API endpoints.

When we write an API endpoint, we first define the schema of the payload:

```tsx
function getBodySchema() {
  return z.object({
    displayName: z.string(),
    email: z.string().email(),
  });
}
```

This function represents the schema, which will validate the following
interface:

```tsx
interface Body {
  displayName: string;
  email: Email;
}
```

Now, let's write the body of the API handler that validates the body of the
function, which we expect to be equal to the `Body` interface.

```tsx
import { throwBadRequestException } from `~/core/http-exceptions`;

export const action: ActionFunction = async ({request}) => {
  try {
     // we can safely use data with the interface Body
    const data = await req.formData();
    const body = Object.fromEntries(data.entries());
    const bodyResult = await getBodySchema().parseAsync(body);
    const { displayName, email } = bodyResult.data;

    return sendInvite({ displayName, email });
  } catch(e) {
    return throwBadRequestException();
  }
}
```

You can also use `safeParse` if you prefer not to throw an error when the
validation fails:

```tsx
export const action: ActionFunction = async ({request}) => {
  const data = await req.formData();
  const body = Object.fromEntries(data.entries());
  const result = await getBodySchema().parseAsync(body);

  // we use result.success as a type guard
  // when false, we throw an exception
  if (!result.success) {
    return throwBadRequestException();
  }

  // TS correctly infers result.data now
  return sendInvite(result.data);
}
```

To learn more about validating data with Zod, we suggest you
check out [the Zod official documentation on GitHub](https://github.com/colinhacks/zod).


Zod is a library for validating data with awesome support for Typescript. Learn how to use it within your Makerkit project.

Validating the Remix API inputs with Zod and Typescript


The Makerkit Boilerplate uses `pino` as logging library. Pino is simple and
lightweight, and it's used across the API functions to log important
information that helps you debug your code.

Generally speaking, you will find that we log every function, especially for
asynchronous operations that could fail for a number of reasons: network
issues, API exceptions, and so on.

So, how to log your API functions effectively? Our recommendation is to log
**before executing an operation** and then log the **result of the
operation**, without leaking important data.

Furthermore, we want to log information such as:
- which user is performing the operation?
- which organization is the user part of?
- any other information that can help you understand and debug what is
happening.

Let's assume you're writing an API function to write to your Firestore database:

```tsx
function addIntegrationHandler() {
  return writeToFirestore(data);
}
```

Let's rewrite the above by adding logging to your function:

```tsx
import logger from '~/core/logger';

async function addIntegrationHandler(
  userId: string,
  organizationId: number,
  integrationId: number,
) {
  // this is the context that every log will print out
  const loggingContext = {
    integrationId,
    organizationId,
    userId,
  };

  // Here we log what we're doing
  logger.log(loggingContext, `Adding new integration to organization`);

  try {
    await writeToFirestore(data);

    // Here we log that the result of the operation
    // was successful
    logger.log(loggingContext, `Integration successfully added`);

    // return successful response
    return res.json({
      integrationId,
      success: true
    });
  } catch (e) {
    // Here we log that the operation failed
    logger.error(loggingContext, `Encountered an error while adding integration`);

    // Logging errors can be okay but
    // ensure not to leak important information!
    logger.debug(e);

    // return 500
    return res.status(500).json({
      integrationId,
      success: false
    });
  }
}
```

If you use the filter `withExceptionFilter`, it will automatically
log eventual exceptions thrown by the function, which makes the try/catch
block optional.

NB: If you're using Vercel, logs are not persisted by default! [Check out the
Vercel integrations](https://vercel.com/integrations#logging) for adding persisting logs to your projects.


Logging is a fundamental part for your SaaS to understand and monitor the behavior of your code at runtime. Let's learn how to add logging to your Makerkit application.

Logging


Enabling CORS is required if you want to allow serving HTTP request to
external clients.

For example, if you want to expose an API to some
consumers: JS libraries, headless clients, and so on.

The code to enable CORS in Remix is very simple. In fact, you can enable it using the following code:

```tsx
function withCors() {
  const headers = new Headers();

  headers.append('Access-Control-Allow-Origin', '*');

  headers.append(
    'Access-Control-Allow-Headers',
    'Origin, X-Requested-With, Content-Type, Accept, referer-path'
  );

  return headers;
}
```

Additionally, you need to handle `OPTIONS` requests appropriately.

```tsx
if (request.method === `OPTIONS`) {
  return new Response(null, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, HEAD, POST, PUT, DELETE',
    },
  });
}
```

In your Makerkit codebase, this function is already available in the
`~/core/middleware/with-cors.ts` file.

To enable CORS, you can simply call it in your handler. If it fails, it will
throw an exception with the appropriate HTTP status code.

```tsx
import withCors from '~/core/middleware/with-cors';

export const action: ActionFunction = async ({request}) => {
  withCors(res);
  // your logic
}

export default apiHandler;
```

Additionally, you need to respond to `OPTIONS` request appropriately.

```tsx
export function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  withCors(res);

  if (req.method === `OPTIONS`) {
     // add the method you want to allow
     res.setHeader('Access-Control-Allow-Methods', 'GET');

     return res.end();
  }
}
```

Enable CORS


When storing sensitive data, such as API keys, you must ensure to encrypt your data in Firestore.

To use these utilities, you must provide an environment variable named `SECRET_KEY`. This should be provided safely using your CI since it's a secret key.

MakerKit provides some utilities to encrypt and decrypt your data. 

```tsx
import { encrypt, decrypt } from '~/core/generic/crypto';

// storing secrets
function storeApiKey(key: string) {
  const encryptedKey = encrypt(key);

  return storeKeyInFirestore(encryptedKey);
}

// retrieving secrets
function getApiKey(id: string) {
  const encryptedKey = await getApiKeyFromFirestore(id);

  return decrypt(encryptedKey);
}
```


When storing sensitive data, such as API keys, you must ensure to encrypt your data in Firestore. Here is how we can encrypt and decrypt it.

Encrypting Secrets


The MakerKit Starter has three default roles:

```tsx
export enum MembershipRole {
  Member,
  Admin,
  Owner,
}
```

We use an `enum`, but you can convert this to an object if you need more granular permissions.

The permissions are hierarchical, which means that if we had a role with a lower level (`Readonly`), we would add it before `Member`:

```tsx
export enum MembershipRole {
  Readonly,
  Member,
  Admin,
  Owner,
}
```

When writing permissions between users, we can check if the user performing the action has a greater role than the target user.

You can extend the role above easily by adding your own, for example:

```tsx
export enum MembershipRole {
  Readonly,
  AccountManager,
  Owner,
}
```

Afterward, remember to add the name and descriptions of these roles in the translations file `common.json`:

```json
"roles": {
  "owner": {
    "label": "Owner",
    "description": "Can change any setting, invite new members and manage billing"
  },
  "accountmanager": {
    "label": "Account Manager",
    "description": "Can change some settings, invite members, perform disruptive actions"
  },
  "readonly": {
    "label": "Readonly",
    "description": "Can only read information"
  }
}
```

Learn more about [using user roles in your permissions system](/docs/permissions).


Extend User Roles

Learn how to configure Stripe, and start collecting payments from your customers

Payments


MakerKit offers support for subscriptions and payments using [Stripe](https://stripe.com).

To get started with [Stripe Checkout](https://stripe.com/docs/payments/checkout), you will need to create an account using the [Stripe website](https://stripe.com).

If you want, you can get your business details sorted right away. If you
want to continue with the set-up, you can skip it for now and get back to it later.

## Configuration

Visit the [Stripe Checkout Tutorial](https://stripe.com/docs/checkout/quickstart?client=next) where we can copy the
configuration for our development environment.

If you click on the file `.env` of the code editor on the right-hand side,
you will be able to see the variables needed:

- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`

Copy these values to your local `.env` file.

<Alert type="warn">
  Make sure to keep your <code>.env</code> file private. It should not be committed to your repository. These environment variables should be added using your hosting provider's dashboard.
</Alert>

## Creating your SaaS plans in Stripe

Stripe allows us to create our plans using the UI in the Stripe Dashboard.

To get started, let's add a couple of testing plans that you can use while
developing your application.

Visit [the Stripe Dashboard](https://dashboard.stripe.com/test/products/prod_KpXDAnvbPkXkgp) and add a new product (for example, a one-time purchase or a SaaS subscription).

You can add multiple "prices": for example, if you're defining a
subscription, you could use two plans, "Basic" and "Pro".

## Creating a Webhook endpoint

Stripe allows us to create a webhook endpoint to receive events. To tell Stripe
where to send the events, we need to create a webhook endpoint that points to our application.

After creating a Stripe endpoint, we need to add the "Signing Secret" key in Stripe to the production environment variables. To do so, use the environment variables editor in your hosting provider's dashboard.

<Image src='/assets/images/docs/stripe-webhook-config.webp' width="1670" height="368" />

### Webhook API Endpoint

The API endpoint needs to point to your application's Stripe webhook: the path is `/resources/stripe/webhook`. For example, if your application is hosted at `https://myapp.com`, the webhook endpoint would be `https://myapp.com/resources/stripe/webhook`.

### Events

The events you want to receive from Stripe are:
- `checkout.session.completed`
- `customer.subscription.updated`
- `customer.subscription.deleted`

If you have any other events you want to receive, you need to add them here.

### Signing Secret

The signing secret is the value of the `STRIPE_WEBHOOK_SECRET` environment variable. 

<Alert type='warn'>
  If you do not follow these steps, you will not be able to receive events from Stripe. This will prevent you from being able to update the subscription status of your users. Please make sure to follow these steps.
</Alert>

### Pricing Table Configuration

Below is the default Pricing Table configuration of the kits. The `PricingTable` component will automatically generate the pricing table based on the Stripe plans you have created and added to the configuration (see below).

We have 3 products (Basic, Pro and Premium), each with 2 plans (monthly, yearly). By default, the Pro plan is set as the recommended plan.

Of course, the below is simply an example. You will need to customize this according to your application's plans.

```tsx
stripe: {
    products: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        badge: `Up to 20 users`,
        features: [
          'Basic Reporting',
          'Up to 20 users',
          '1GB for each user',
          'Chat Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$9',
            stripePriceId: 'price_1LfXGaI1i3VnbZTq7l3VgZNa',
            trialPeriodDays: 0,
          },
          {
            name: 'Yearly',
            price: '$90',
            stripePriceId: 'basic-plan-yr',
            trialPeriodDays: 0,
          },
        ],
      },
      {
        name: 'Pro',
        badge: `Most Popular`,
        recommended: true,
        description: 'Description of your Pro plan',
        features: [
          'Advanced Reporting',
          'Up to 50 users',
          '5GB for each user',
          'Chat and Phone Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$29',
            stripePriceId: 'pro-plan-mth',
            trialPeriodDays: 0,
          },
          {
            name: 'Yearly',
            price: '$200',
            stripePriceId: 'pro-plan-yr',
            trialPeriodDays: 0,
          },
        ],
      },
      {
        name: 'Premium',
        description: 'Description of your Premium plan',
        badge: ``,
        features: [
          'Advanced Reporting',
          'Unlimited users',
          '50GB for each user',
          'Account Manager',
        ],
        plans: [
          {
            name: '',
            price: 'Contact us',
            stripePriceId: '',
            trialPeriodDays: 0,
            label: `Contact us`,
            href: `/contact`,
          },
        ],
      },
    ],
  }
}
```

<Alert type="warn">
  The properties "stripePriceId" are placeholders. You will need to replace them with the IDs of your plans.
</Alert>

### Additional Configuration

You can also configure the following properties on each `product`:

- `recommended` - set to `true` if you want to highlight a plan as recommended
- `badge` - set to a string if you want to display a badge next to the plan name

You can also configure the following properties on each `plan`:

- `price` - any string that you want to display as the price (e.g. `$9.99` or `Free`)
- `label` - set to a custom string if you want to display a button label
- `href` - set to a custom URL if you want to link to a custom page (for example, a contact page)
- `trialPeriodDays` - set to the number of days you want to offer a free trial for

### Install The Stripe CLI

The Stripe CLI is required to help us test our integration.
Please [follow this guide to install the CLI on your system](https://stripe.com/docs/stripe-cli).

The default recommendation is to use Docker, which Makerkit uses by default.

### Connect CLI with your account

To connect the Stripe CLI with your account, run the following command:

```
npm run stripe:listen
```

This command requires Docker, but you can alternatively install Stripe on your OS and change the command to use `stripe` directly.

The CLI should prompt you to connect your account. If you signed in already, visit the link and follow the instructions.

If you followed the instructions, get back to the terminal, and then copy
the webhook secret to your `STRIPE_WEBHOOK_SECRET` environment variables in the
`.env` file.

Restart the next.js server to apply the changes.

## Billing Portal

MakerKit uses the [Stripe Billing Portal](https://dashboard.stripe.com/test/settings/billing/portal) to let your users manage their invoices and subscriptions.

The portal becomes accessible once the organization subscribes to a plan, which creates a `customerId` property, making it possible for the organization to access the portal.

### Enabling the Billing Portal in test mode

Please visit the [Stripe Billing Page](https://dashboard.stripe.com/test/settings/billing/portal) to enable the Billing Portal.

Choose the settings that best apply to your product and save your changes.

The only required fields to get started are `Terms of Service` and
`Privacy` URLs. You can add any URL at this stage. **However, remember to update these pages when you go live**.

For a technical deep-dive, we recommend reading our blog post where we [build the integration between Stripe and Next.js from scratch](/blog/tutorials/guide-nextjs-stripe). Because the result of the blog post is a simplified version of the Makerkit's implementation, it can be beneficial for understanding its code.


Learn how to configure Stripe with your MakerKit application

Set up Stripe Payments for Remix and Firebase SaaS applications


Makerkit handles five webhooks from Stripe and stores "just enough" data into the organization's entity to function correctly.

The Stripe's webhooks topics are defined here at `app/core/stripe/stripe-webhooks.enum.ts`:

```tsx
export enum StripeWebhooks {
  Completed = 'checkout.session.completed',
  SubscriptionDeleted = 'customer.subscription.deleted',
  SubscriptionUpdated = 'customer.subscription.updated',
}
```

To handle webhooks, we created an API route at `routes/resources/stripe/webhook.ts`.

This route is responsible for:

1. Validating that the webhook is coming from Stripe
2. Routing the webhook to its handler

## Validating Stripe's Webhooks

To validate the webhook, we do the following:
1. get the header 'stripe-signature'
2. create a Stripe instance
3. get the raw body
4. call `constructEvent` to validate and build an event object sent by Stripe. When this fails, it will throw an error

```tsx
const signature = req.headers['stripe-signature'];

// verify signature header is not missing
if (!signature) {
  return throwBadRequestException(res);
}

const rawBody = await getRawBody(req);
const stripe = await getStripeInstance();

const event = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  webhookSecretKey
);
```

## Handling Stripe's Webhooks

After validating the webhook, we can now handle the webhook type relative to its topic:

```tsx
switch (event.type) {
  case StripeWebhooks.Completed: {
    // handle completed
  }

  case StripeWebhooks.AsyncPaymentSuccess: {
     // handle async payment success
  }
}
```

As described above, we handle 5 events:

1. `Completed`: the checkout session was completed (but payment may not have arrived yet if it's asynchronous)
2. `SubscriptionDeleted`: the subscription was deleted by the customer
3. `SubscriptionUpdated`: the subscription was updated by the customer

### Checkout Completed

When a user completes the checkout session, we create the `subscription` object on the currently connected user's organization.

<Alert type='warn'>
  The payment may not have yet succeeded when it's "asynchronous", so the payment's status may be "AwaitingPayment" rather than "Paid". You may want to consider the subscription active only when the subscription's status is "active" or "trialing".
</Alert>

The subscription's object has the following interface:

```tsx
export interface OrganizationSubscription {
  id: string;
  priceId: string;

  status: Stripe.Subscription.Status;
  currency: string | null;
  cancelAtPeriodEnd: boolean;

  interval: string | null;
  intervalCount: number | null;

  createdAt: UnixTimestamp;
  periodStartsAt: UnixTimestamp;
  periodEndsAt: UnixTimestamp;
  trialStartsAt: UnixTimestamp | null;
  trialEndsAt: UnixTimestamp | null;
}
```

This interface is added to the `Organization` object.

### Subscription Updated

When a subscription is updated, we rebuild the subscription object and update it in the organization's Firestore entity.

### Subscription Deleted

When a subscription is deleted, we simply remove it from the organization entity.

## Adding additional webhooks

If you want to add additional webhooks, you can do so by adding a new case in the switch statement.

For example, if you want to handle the `customer.subscription.trial_will_end` event, you can do so by adding the following case:

```tsx
case 'customer.subscription.trial_will_end': {
  // handle trial will end
}
```

## Adding additional data to the subscription object

If you want to add additional data to the subscription object, you can do so by adding the data to the `OrganizationSubscription` interface.

For example, if you want to add the `quantity` property to the subscription object, you can do so by adding the following property to the interface:

```tsx
export interface OrganizationSubscription {
  // ...
  quantity: number | null;
}
```

Then, you can add the data to the subscription object using the `buildOrganizationSubscription` function:

```tsx title="lib/stripe/build-organization-subscription.ts"
import type { Stripe } from 'stripe';
import type { OrganizationSubscription } from '~/lib/organizations/types/organization-subscription';

export function buildOrganizationSubscription(
  subscription: Stripe.Subscription,
): OrganizationSubscription {
  const lineItem = subscription.items.data[0];
  const price = lineItem.price;

  return {
    // your props
    quantity: lineItem.quantity,

    // default props
    id: subscription.id,
    priceId: price?.id,
    status: subscription.status,
    cancelAtPeriodEnd: subscription.cancel_at_period_end,
    currency: lineItem.price.currency ?? null,
    interval: price?.recurring?.interval ?? null,
    intervalCount: price?.recurring?.interval_count ?? null,
    createdAt: subscription.created,
    periodStartsAt: subscription.current_period_start,
    periodEndsAt: subscription.current_period_end,
    trialStartsAt: subscription.trial_start ?? null,
    trialEndsAt: subscription.trial_end ?? null,
  };
}
```

Learn how MakerKit handles Stripe Webhooks in your application

How Makerkit handles Stripe Webhooks


While Makerkit uses subscriptions by default, you can offer your customers one-time payments.

Fortunately, Stripe Checkout makes it insanely easy. Let's see how to update  Makerkit's codebase to enable Stripe one-off payments for your product.

1) First, when choosing your Stripe Price's billing type, select `One Time.` [Learn more about creating Prices with Stripe](https://support.stripe.com/questions/how-to-create-products-and-prices).

2) Secondly, we need to change the payment mode in Makerkit's codebase. To do so, we will update the `createStripeCheckout` function defined at `~/lib/stripe/create-checkout.ts`.

If you open the file, you'll find the line below:

```tsx
const mode: Stripe.Checkout.SessionCreateParams.Mode = 'subscription';

// some code here...

return stripe.checkout.sessions.create({
  mode,
  // more code here...
});
```

To enable one-time payments, we will replace the `mode` constant from `subscription` to `payment`:

```tsx
const mode: Stripe.Checkout.SessionCreateParams.Mode = 'payment';

// some code here...

return stripe.checkout.sessions.create({
  mode,
  // more code here...
});
```

And that's it! Stripe will not charge our users recurringly but will simply charge them once.

<Alert type='warn'>
As the UI is set up for recurring subscriptions, you may want to tweak the Subscription Page UI to reflect that charges are not recurring and that the product has been successfully purchased.
</Alert>

## Handling the Payment Method dynamically

The above works great if you only offer one plan. However, let's assume you have multiple prices and want to dynamically update the payment mode based on the selected price.

In this case, let's do the following:
1. Extend the plan information in the application configuration
2. Select the appropriate method when creating the checkout by retrieving the plan's model

If you open your application's configuration, you will notice that plans have the following interface:

```tsx title="src/configuration.ts"
{
  name: 'Basic',
  description: 'Unlimited applications and 2-hour onboarding session',
  price: '$249/year',
  stripePriceId: 'price_***********',
}
```

Now, we can extend it with the payment mode, which would be `subscription` or `payment`:

```tsx
{
  name: 'Basic',
  description: 'Unlimited applications and 2-hour onboarding session',
  price: '$249 one off!',
  stripePriceId: 'price_***********',
  mode: 'payment'
}
```

Now, let's reopen the file `create-checkout.ts` file and find the payment mode of the selected price ID:

```tsx
const price = configuration.plans.find(item => {
  return item.stripePriceId === params.priceId;
});

if (!price) {
  throw new Error(`Price with ID ${params.priceId} not found in config`);
}

const mode: Stripe.Checkout.SessionCreateParams.Mode = price.mode;

// some code here...

return stripe.checkout.sessions.create({
  mode,
  // more code here...
});
```

🎉 Now it looks better and works for multiple plans based on their payment mode!


Learn how to switch from Stripe Subscriptions to One-Time Payments in your Makerkit application

Enabling One-Time Payments with Stripe


If you prefer using Lemon Squeezy instead of Stripe with your Makerkit kit, we provide a different branch from the main repository that you can use.

The branch is called `main-ls`. If you want to use Lemon Squeezy, you can clone the repository and checkout the `main-ls` branch.

NB: the integration is in beta, and I am working on improving it.

## Setting up Lemon Squeezy

### Step 1: Create a Lemon Squeezy account

First, you need to create a Lemon Squeezy account. You can do so by visiting [https://lemonsqueezy.io](https://lemonsqueezy.com).

Get your store setup (start in Test mode, so you don't need to wait for activation).

### Step 2: Create a Product/Variant in Lemon Squeezy

You can see this guide for [setting up SaaS subscription plans in Lemon Squeezy](https://docs.lemonsqueezy.com/guides/tutorials/saas-subscription-plans).

If you want, set up a monthly/annual plan for your product, or just a single plan.

<Image src="/assets/images/posts/lemon-squeezy-plans.webp" width={"1286"} height={"816"} />

To replicate the basic Makerkit subscription plans, you can create a plan for each of the following: Basic, Pro and Premium plans.

To get started quickly, you can also set up a single plan for your product.

### Step 3: Create a Lemon Squeezy API key

Now, we need to setup an API Key. Go to your Lemon Squeezy settings page and click on the [API Keys tab](https://app.lemonsqueezy.com/products).

Click on the "Create API Key" button and give it a **very specific name**, so you won't confuse it with your production keys. Copy the API key and ensure to store it. We will be adding this to your Makerkit's local environment variables file.

<Image src="/assets/images/posts/lemon-squeezy-api-key-name.webp" width={"946"} height={"614"} />

Depending on which kit you're using, you will add this key to either `.env.local` (Next.js) or `.env` (Remix). This key is not supposed to be committed to your repository, so we add them safely to our local files.

Additionally, we need to add the `LEMON_SQUEEZY_STORE_ID` to the local environment variables file, and a secret string `LEMONS_SQUEEZY_SIGNATURE_SECRET` that we use to verify the webhook signature.

Update them in your local environment variables file:

```
LEMON_SQUEEZY_API_KEY=<YOUR_KEY>
LEMON_SQUEEZY_STORE_ID=<YOUR_STORE_ID>
LEMONS_SQUEEZY_SIGNATURE_SECRET=<a random string>
```

#### Find your Lemon Squeezy Store ID

To find your Lemon Squeezy Store ID, visit your `Stores` page in the Lemon Squeezy dashboard.

You can do so by visiting the following URL: [https://app.lemonsqueezy.com/settings/stores](https://app.lemonsqueezy.com/settings/stores).

The ID is the number next to the store name.

Proceed by copying the Store ID into the `LEMON_SQUEEZY_STORE_ID` environment variable.

## Step 4: Configure Lemon Squeezy plans in the Makerkit configuration

Now, we need to configure the Lemon Squeezy plans in the Makerkit configuration, and enter the correct plan IDs.

To do so, open the `~/configuration.ts` file and edit the `stripe` object.

We can convert this to something more abstract, such as `subscriptions`, and add the relevant Lemon Squeezy product and variant IDs.

```ts title="src/configuration.ts"
{
  subscriptions: {
    products: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        badge: `Up to 20 users`,
        productId: 1, // <-- Lemon Squeezy product ID
        features: [
          'Basic Reporting',
          'Up to 20 users',
          '1GB for each user',
          'Chat Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$9',
            variantId: 1, // <-- Lemon Squeezy variant ID
          },
          {
            name: 'Yearly',
            price: '$90',
            variantId: 2, // <-- Lemon Squeezy variant ID
          },
        ],
      }
    ]
  }
}
```

**Note**: The `variantId` is the ID of the plan in Lemon Squeezy. The `productId` is the ID of the product.

#### Find your Lemon Squeezy product and variant IDs

To find your Lemon Squeezy product and variant IDs, we need to use the API.

Submit a `GET` request to the following endpoint using `curl` or Postman and insert your API key:

```
GET https://api.lemonsqueezy.com/v1/products
Accept: application/vnd.api+json
Authorization: Bearer {api_key}
Content-Type: application/vnd.api+json
```

The JSON response will return a list of products and variants. You can find the IDs in the response. Please add the IDs to the `configuration.ts` file.
### Step 4: Creating the Webhook In Lemon Squeezy

We need to create a Webhook from the Lemon Squeezy Dashboard so that we can receive the events to our webhook handler.

You will be prompted for the following:

- URL: point it to the ngrok URL (see below). Ensure you point it to the `/resources/ls/webhook` endpoint.
- Secret: the secret `LEMONS_SQUEEZY_SIGNATURE_SECRET` that you have set in the `.env` file
- Events: select the events that you want to receive. In our case, we want to receive the `subscription_created` and `subscription_updated` events.

<Image src="/assets/images/posts/lemon-squeezy-webhook-setup.webp" width={"1118"} height={"1666"} />

#### Testing Locally

To test the webhook handler locally, we can use the [ngrok](https://ngrok.com/) tool.

We add the following command to the `package.json` file:

```
"ngrok": "npx ngrok http 3000"
```

And you can run it with:

```bash
npm run ngrok
```

You can also use other alternatives, such as Localtunnel or Cloudflare Tunnel.

### Step 5: Go to production

Once you're ready to go to production, you can switch your Lemon Squeezy store to production mode.

Additionally, remember to set up the webhook in production mode as well, pointing to your production URL.

Lear how to migrate your MakerKit project to Lemon Squeezy

Use Lemon Squeezy with MakerKit

Learn about Makerkit's Organizations' model and members invites

Organizations


The Makerkit boilerplate's data model is modeled around *Organizations*. 

Organizations are groups of users, which can also be named Projects, Teams, and so on: it really depends on your application's domain.

The data model of an organization looks like the following:

```tsx title="organization.ts"
type UserId = string;

interface Organization {
  name: string;
  timezone?: string;
  logoURL?: string | null;
  subscription?: OrganizationSubscription;
  customerId?: string;

  members: Record<UserId, {
    role: number;
    user: Reference;
  }>;
}
```

### Renaming "Organizations" to another entity

Makerkit uses "organizations" to refer to a group of users. However, the name "organizations" may not make sense to your application's domain, even with a similar technical data model. 

For example, you may want to call them "Teams", or "Workspaces". In this case, we suggest you keep using "organization" as a technical concept (otherwise, you'd have to rename every instance) within the codebase while changing the labels in the UI using the i18n files at `public/locales`. 

To do so, simply rename all "Organization" instances according to your preferred choice.

MakerKit's Organizations


There are many ways you can extend the organization's data model in your applications: you will use this entity for the objects that are shared among the group's users.

For example, here is a popular scenario: we assume users can install integrations for their organizations. Integrations can have the following interface:

```tsx title="integration.ts"
enum IntegrationType {
  Zapier,
  Notion,
  // etc
}

interface Integration<IntegrationData = unknown> {
  type: IntegrationType;
  data: IntegrationData;
}
```

Then, you can extend the organization's interface and add an `integrations` property to `Organization`, and initialize it as an empty array `[]` when you create a new integration:

```tsx title="organization.ts"
interface Organization {
  // ...
  integrations: Integration[];
}
```

Extending Organizations


Most permissions are written in a single file at `src/lib/organizations/permissions.ts`.

Here, you can find some of the examples used in the boilerplate so that you can start writing your own.

Why are permissions written in a single file? Because it's easy to write inline logic and lose track of it. Therefore, we will write all the business logic within the same file and encapsulated as simple functions.

Let's take a look at a simple permission function in the boilerplate:

```tsx title="src/lib/organizations/permissions.ts"
/**
 *
 * @param currentUserRole The current logged-in user
 * @param targetUser The role of the target of the action
 * @description Checks if a user can perform actions (such as update a role) of another user
 * @name canUpdateUser
 */
export function canUpdateUser(
  currentUserRole: MembershipRole,
  targetUser: MembershipRole
) {
  return currentUserRole > targetUser;
}
```

The function takes two parameters: the current user's role and the target user's role, and checks if the current user can update the target user's role (or anything).

Now, we can use the function above with the `IfHasPermissions` component to display or hide some parts of the application. This component automatically injects the current user's role, such as below:

```tsx
<IfHasPermissions
  condition={(currentUserRole) =>
    canInviteUser(currentUserRole, targetUserRole)
  }
>
  <InviteUserComponent />
</IfHasPermissions>
```

The `InviteUserComponent` component will be displayed if the condition is truthy.

Otherwise, you can use these functions throughout the application on both the client and the server.


Learn how to write a simple permissions system based on the users' role in your Makerkit applications

Managing User Permissions


Makerkit provides some utilities to retrieve the current organization's
subscription: you can use these utilities to allow or gate access to
specific features, pages, or to perform certain actions.

1. On the client side, we can use the hook `useIsSubscriptionActive`
2. On the server-side, we can use the functions
`isOrganizationSubscriptionActive` and `getOrganizationSubscription`

## Client Side Gating

Let's assume we want to allow only users who belong to paying organizations to
perform a certain action:

```tsx title="src/lib/organizations/permissions.ts"
function isAdmin(
  role: MembershipRole
) {
  return role === MembershipRole.Admin;
}
```

Now, combine this function with other conditions:

```tsx title="src/lib/organizations/permissions.ts"
export function useCreateNewThing(
  userRole: MembershipRole,
) {
  const isPayingUser = useIsSubscriptionActive();

  return isPayingUser && isAdmin(userRole);
}
```

As you may know, I recommend adding all the permissions logic to the file
`permissions.ts` (or similar files), and never inline it: this makes it easy to
store logic in one single place rather than scattered across the
application.

Inlining logic in our code will make it hard to track logic
down and debugging it.

Once defined out logic functions in `permissions.ts`, we can then use these
in our components to hide the sections that users do
not have access to:

```tsx
function Feature() {
  const userRole = useCurrentUserRole();
  const canCreateThing = useCreateNewThing(userRole);

  if (!canCreateThing) {
    return <div>Sorry, you do not have access to this feature. Subscribe?</div>
  }

  return <FeatureContainer />;
}
```

### Firestore Rules

Another essential thing to take into account is securing our Firestore
rules using the organization's subscription.

For example, let's assume your application requires organizations to be
paying customers to write to a certain collection:

```js
function getOrganizationSubscription() {
  let organization = getOrganization(organizationId);

  return organization.subscription;
}

function isPayingOrganization(subscription) {
  return subscription != null && subscription.status === 'paid';
}

function isProPlan(subscription) {
  let organization = getOrganization(organizationId);

  return subscription.stripePriceId == 'pro-plan-id';
}

function canWriteToCollection(organizationId) {
  let subscription = getOrganizationSubscription();

  return isPayingOrganization(subscription) && isProPlan(subscription);
}

match /organizations/{organizationId} {
  match /tasks/{task} {
    allow create: canWriteToCollection(organizationId);
    allow list: if userIsMemberByOrganizationId(organizationId);
  }
}
```

## Server Side Gating

When gating access on the server side, we can use two utilities that allow
us to get the organization's subscription by its ID.

### Using Firestore utilities

When you need to check the user's subscription in your API functions, you can
use the functions `isOrganizationSubscriptionActive` and
`getOrganizationSubscription` exported from
`src/lib/server/organizations/memberships.ts`.

For example, let's assume we have an API handler that performs an action:

```tsx
export default async function action({ request }) {
  const organization = await parseOrganizationCookie(request);

  const isSubscriptionActive =
    await isOrganizationSubscriptionActive(organization);

  if (!isSubscriptionActive) {
    return throwForbiddenError();
  }

  // all good! perform action
}
```


Learn how to gate access to certain features or pagess based on the organization's subscription

Subscription Permissions


## useCurrentOrganization

This hook returns the current organization. It's a wrapper around the `OrganizationContext` context. The returned value is an `Organization` object.

```tsx
import useCurrentOrganization from '~/lib/organizations/hooks/use-current-organization';

const organzation = useCurrentOrganization();
```

## useIsSubscriptionActive

This hook returns a boolean indicating whether the current organization has an active subscription. It's a shortcut around the `useCurrentOrganization` hook that checks if the `status` property is set to `Paid`.

```tsx
import useIsSubscriptionActive from '~/lib/organizations/hooks/use-is-subscription-active';

const isSubscriptionActive = useIsSubscriptionActive();
```

## Other Organization Hooks

The kit has many more hooks that are used internally: they are not meant to be used directly unless you want to update the logic or fix a bug.

All the hooks are available in the `~/lib/organizations/hooks` directory.

Reference for the organizations React hooks

Organization React Hooks

Learn about the various utilities that come with Makerkit