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

Getting Started


MakerKit is **the Next.js boilerplate project for SaaS** built for getting you started on the right foot.

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

MakerKit is ideal for any SaaS application or other 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
Next.js, Tailwind, and Firebase:

- **Scalable Next.js** 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 [Headless UI](https://headlessui.dev)
- **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**
- **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

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

### Debugging and Testing

Never waste time again chasing bugs.

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:

- **Resources, examples, and guides** for building a SaaS using *MakerKit*
(Coming Soon)
- 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 guide you through
so that you can easily adjust MakerKit to your application's domain.

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


Introduction to MakerKit: a SaaS starter built with Next.js and Firebase

Introduction to MakerKit: a SaaS boilerplate for Next.js and Firebase


MakerKit is built primarily with Next.js, Firebase, and Tailwind CSS.

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

### A Scalable Next.js Application
The codebase is entirely built with [Next.js](https://nextjs.org) (version 12),
a popular React meta-framework built by the fine folks at [Vercel](https://vercel.com).

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

### 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.

### 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 both light and dark themes, so you can choose to use both according to your user's OS settings, or you can manage it using a local cookie.

### Default Components built with Headless UI

Some components, such as `Dropdown`, `Popover` and `Modal`, have been
extended using [Headless UI](https://headlessui.dev), an accessible library
built by the Tailwind Team.

MakerKit uses Tailwindf CSS for styling all the other components too.

### Fully and Strictly Typed with Typescript

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

### Validation with Zod

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

### Tested 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.

### 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.

### i18n by default with next-i18n

We configured the application to be translated by default thanks to the
[next-i18n](http://next-i18next.com) package.

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**.

### 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 Next.js, 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 Next.js and Firebase SaaS template, we need to ensure
you have installed the required software first.

- Node.js LTS (Please do not upgrade yet to Node 18)
- Firebase Tools
- Git

Assuming that yu have likely installed Node.js and Git, please also install
the `firebase-tools` package using `npm`:

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

If you have already installed it, please ensure that you are running the
latest version.

### Cloning the repository

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

```
git clone --depth=1 https://github.com/makerkit/next-firebase-saas-kit 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 https://github.com/makerkit/next-firebase-saas-kit
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 make sure to 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. **Next.js Server**: the first command is for running the Next.js 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 comamand 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 Next.js Server

And now, the Next server:

```bash
next run dev
```

If everything went 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 filename=.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 Next.js and Firebase MakerKit application

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:

```typescript filename=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: `/api/stripe/checkout`,
      billingPortal: `/api/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  firebase: {
    apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
    authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
    storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
    measurementId: process.env.NEXT_PUBLIC_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.NEXT_PUBLIC_APPCHECK_KEY,
  navigation: {
    style: NavigationStyle.TopHeader,
  },
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  autoBanners: true,
  emulatorHost: process.env.NEXT_PUBLIC_EMULATOR_HOST,
  emulator: process.env.NEXT_PUBLIC_EMULATOR === 'true',
  production: process.env.NEXT_PUBLIC_NODE_ENV === 'production',
  plans: [
    {
      name: 'Basic',
      description: 'Describe your basic plan',
      price: '$249/year',
      stripePriceId: '<STRIPE_PRICE_ID>',
    },
    {
      name: 'Pro',
      description: 'Describe your pro plan',
      price: '$999/year',
      stripePriceId: '<STRIPE_PRICE_ID>',
    },
  ],
  testingPlans: [],
};
```

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

As you may have noticed, some of these values are taken from Node's
environment. We will use an additional file name `.env`, which is used by
`Next` to read the configuration.

This file is not to be committed (at least not
the "secret" variable). 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.

That means that to push your project to production, **you need to 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:

```
NEXT_PUBLIC_EMULATOR=true

GCLOUD_PROJECT=demo-makerkit
NEXT_PUBLIC_FIREBASE_PROJECT_ID=demo-makerkit
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=demo-makerkit.appspot.com
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=localhost
NEXT_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT=8080
NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT=9099
NEXT_PUBLIC_FIREBASE_STORAGE_EMULATOR_PORT=9199

# Change this with your project's APP ID
NEXT_PUBLIC_FIREBASE_APP_ID=<MAKERKIT_DEV_APP_ID>
# Change this with your project's API KEY
NEXT_PUBLIC_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 `NEXT_PUBLIC_FIREBASE_APP_ID` and `NEXT_PUBLIC_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`:

```
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=
NEXT_PUBLIC_SITE_URL=

FIREBASE_CLIENT_EMAIL=

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

NEXT_PUBLIC_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. This can differ between providers.

If you are using Vercel, make sure to 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 title of the blog 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 displayed by browsers. 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

This is your or your company's Twitter handle you can use to link your blog posts to.

## 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 it and paste it in, as it's all is 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 Next.js and Firebase

Define the global configuration of your MakerKit SaaS application with Next.js 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.production` file, which will automatically
populate the project configuration file `~/.configuration`.

```
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=
```

<Alert type='warn'>
Next.js bundles the environment variables prefixed with "NEXT_PUBLIC" with
your client-side code. It means that you should use these for non-secret values that need to be exposed.
</Alert>

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

<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 with 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 the
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

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

Setting up a Firebase project for your MakerKit application


While you may want to use Next.js'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 important to know how to set up Firebase Functions in a Next.js 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
```

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

```
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!

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 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 get started on 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 quite 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:

```
- src
  - lib
  - components
  - pages
    - api
  - core
```

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

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

### Core
Let's talk about the lower level: the `core`. This layer is a collection of building blocks, utilities, and API 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 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 logic for your application, and it is likely where you will add most of your code.

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

### Pages

Finally, the `pages` 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.

## 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 Next.js application with a scalable and production-grade architecture and folder structure

Architecture and Folder Structure for your Next.js SaaS application


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

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

<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 filename=Structure
- src
  - components
    - events
      - EventsContainerComponent.tsx
      - ...

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

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

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

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

#### Types

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

```tsx filename=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 filename=src/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 filename=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) Pages

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

```tsx filename=pages/events/index.ts
import { GetServerSidePropsContext } from 'next';

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

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

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

export default EventsPage;

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

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

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, but 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
}
```

By default, 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 very simple:

```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 Next.js and Firebase

The MakerKit Data Model for your SaaS project built with Next.js and Firebase

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

Authentication


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:
 - **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 filename=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 pages and the user's profile page.

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

We set up MakerKit to persist the user's session on all the website's pages using SSR.

SSR allows for seamless integration between the pages of your website. For example, your pricing page could prompt your 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

While it sounds great, there is a downside: by server-side rendering the page (SSR), we lose the possibility to statically generate the page (SSG), which is faster.

#### Should you use SSR or SSG?

Ultimately, it comes down to what your needs and preferences are. We recommend:

- using SSG for static pages, such as the home page, your blog, and the
documentation pages
- using SSR for dynamic pages, such as your application's code (the
 pages behind authentication)

The above is the default configuration of the Makerkit's codebase, so if you're fine with that, simply keep using the same patterns as the base application.



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

Setting up Firebase and Next.js 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 MakerKit application

Setting up Firebase Auth with Next.js


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 `getServerSideProps` function.

### 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 Next.js

Firebase and Next.js 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 filename=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 additional configuration that you need to
    enable on the provider's end.
  </p>
</Alert>


Learn how to setup Third-Paerty providers with Firebase Auth in your MakerKit application

Set up Third party authentication providers with Next.js 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 filename=configuration.ts
{
  auth: {
    providers: {
      emailPassword: false, // we switch this to false
      phoneNumber: false,
      emailLink: true, // we switch this to true
      oAuth: [GoogleAuthProvider, FacebookAuthProvider],
    },
  }
}
```

And, 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 Next.js 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 filename=configuration.ts
auth: {
  // flip this to "true"
  enableMultiFactorAuth: true,
}
```

After having enabled MFA, users will be able to 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


MakerKit uses SSR throughout the website. If you choose to use SSR, you can persist the user's authentication on every page.

Whether SSR on every page is something your website may need or not is up to your needs, but MakerKit makes this process very easy.

Let's assume the following is your Next.js Index page, and we want to show the user's Profile avatar if they signed in. You will need to fetch the user's data from the `getServerSideProps` function and return it as `props` to the current page.

The MakerKit default template does it for you, but you need to remember that you need to add the following snippet to every page you want the authentication persisted.

```tsx
import { withUserProps } from '~/app/with-user-props';

function Index({ user }) {
    // display user in your components
}

export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return withUserProps(ctx);
}
```

MakerKit also provides a `UserContext` context, which you can inject with `useContext` in any of your components. Assuming you have a component `AvatarComponent` in which you want to display your user's avatar:

```tsx
function ProfileAvatar() {
    const { user } = useContext(UserContext);

    return (
        <img src={user.profileURL} alt='Profile Photo' />
    )
}
```

Alternatively, you can use the hook `useUserSession`:

```tsx
function ProfileAvatar() {
    const {auth} = useUserSession();

    return (
        <img src={auth.profileURL} alt='Profile Photo' />
    )
}
```


Learn how to use SSR with Firebase Authentication and Next.js

Using SSR with Firebase and Next.js authentication


MakerKit provides various utilities that allow you to restrict access to
certain pages or API according to factors such as: sign-in state, role,
membership plan, etc.

## Protecting Next.js Pages

To protect against access to certain pages, we can use the function
`withAppProps`. This function is a server-side props handler which will take
care of checking the following conditions:

- if the user is signed in - otherwise will be redirected back to the sign
in page (this is customizable)
- if the user is onboarded - otherwise will be redirected back to the
onboarding
- if the page they are trying to access requires a certain membership plan

Assuming you want to protect the `Dashboard` page, it will be as easy as:

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

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  return await withAppProps(ctx);
}
```

It's likely that you will want to add additional logic, or additional props
to be sent to the page. In this case, you can partially evaluate
`withAppProps` and extend the props with other information:

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

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  const { props: appProps } =
    await withAppProps(ctx);

  const data = await getDataFromDb();

  return {
    props: {
      ...appProps,
      data,
    }
  };
}
```
This handler takes the following parameters:

```tsx
const DEFAULT_OPTIONS = {
  redirectPath: configuration.paths.signIn,
  locale: 'en',
  localeNamespaces: <string[]>[],
  requirePlans: <string[]>[],
}
```

- `redirectPath`: by default, we redirect the user to the signIn page when
they're not authenticated
- `redirectPath`: by default, we use the `en` locale
- `localeNamespaces`: additional namespaces you want to add to the route
- `requirePlans`: a list of Stripe price IDs that you ma want to require to
access this page. If you require more complex logic, it's best to handle it
separately

## Makerkit's default page guards

### withAppProps

The page guard `withAppProps` is ideal for internal pages of your application, ie. the pages that require that the user is authenticated and that have an active account, i.e. they went past the onboarding:

This page guard will:
- ensure the user is authenticated
- ensure the user created an account after the onboarding flow
- ensure the user belongs to an organization

### withAuthProps

The page guard `withAuthProps` will disallow users from entering authentication routes (sign-in, sign-up, password-reset) while they are authenticated:

This page guard will:
- ensure the user is not authenticated before granting access to pages that **require the user not to be authenticated**

### withTranslationProps

The page guard `withTranslationProps` is used by default by the other guards and is used to load the translations before rendering the page. Use this as the default guard for static pages that do not have any authentication requirement:

This page guard will:
- ensure the translations are loaded onto the page being rendered

Page Guards allow you to protect certain routes from unauthorized access. This docs explain how MakerKit makes the process of protecting your Next.js pages easy and quick.

Protect your Next.js application's pages with Guards


API Guards are similar to Page Guards, except they belong to the server and
will protect our API endpoints.

As an example, let's take MakerKit's implementation for handling user
invites. 

We want to check that:
- the user is authenticated
- the endpoint method being called is correct

```tsx
import { withAuthedUser } from '~/core/middleware/with-authed-user';

export default function inviteHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withMiddleware(
    withMethodsGuard(SUPPORTED_METHODS),
    withAuthedUser,
    inviteMembersToOrganizationHandler
  );

  return withExceptionFilter(req, res)(handler);
}
```

The `withMiddleware` is a simple utility that can chain API handlers that respect the interface of a Next.js handler. The above handler can be written as follows, by passing in the parameters `req` and `res` explicitly:

```tsx
export default withMiddleware(
  (req, res) => withMethodsGuard(SUPPORTED_METHODS)(req, res),
  (req, res) => withAuthedUser(req, res),
  (req, res) => inviteMembersToOrganizationHandler(req, res)
);
```

The final `inviteMembersToOrganizationHandler` is the one that gets called at the end and is responsible for returning data to the client.

## Makerkit Default API Guards

As you can see above, we're using various guards: `withMethodsGuard` and
`withAuthedUser`.

These two guards will make sure that the **request will get rejected if the
user isn't authenticated** or if the user **submitted a request using a
disallowed HTTP method**.

You can also simplify the above if you only want to check if the user is
signed-in:

```tsx
export default function myAPIHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await withAuthedUser(req, res);

  // do something with res
}
```

### withAuthedUser

The `withAuthedUser` API guard will reject the API request when the user is not authenticated.

### withMethodsGuard

The `withMethodsGuard` API guard will reject the API request when the method is not among the ones used. 

For example, the code below will never execute the handler `myApiHandler` if the method is not `GET`:

```tsx
export default withMiddleware(
  withMethodsGuard(['GET']),
  myApiHandler
);
```

### withAdmin

The `withAdmin` API guard will ensure the Firebase Admin is initialized before continuing with the rest of the handlers. This is useful before accessing any of the Firebase Admin packages.

MakerKit uses API Guards allow to protect your Next.js API endpoints from unauthorized users, bad input, etc.

Protect your Next.js application's API with Guards


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 finishing 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, make sure to 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 Next.js `.env` file:

```
NEXT_PUBLIC_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 will have to 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 Next.js application from abuse using Firebase AppCheck

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 filename=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 filename=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 form 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 filename=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 data of the record itself.

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 the from 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 very common scenario.

For example, we assume you have a collection named `tasks`, with a foreign key
`organizationId` that 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 filename=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>`:

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

```
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`, which is 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 filename=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 Next.js 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, and 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 on, we can simply use the SDK as 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 thee 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

Development


Here are all the commands defined in the MakerKit's template:

### Analyzing the Next.js bundle

Run the command:

```
npm run analyze
```

The command will automatically bundle your clients and open a page with an analysis of your bundles. This will allow you to understand which libraries are taking the most space.

### Run the development server

Run the command:

```
npm run dev
```

### Run the E2E testing server

This command is needed for running the E2E tests. Run the command:

```
npm run dev:test
```

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

### Build RSS feeds

Run the command:

```
npm run rss
```

This is optional as it is automatically called after the `build` command.

### Build Sitemap

Run the command:

```
npm run sitemap
```

This is optional as it is automatically called after the `build` command.

### Format all the files

Run the command:

```
npm run format
```

### Healthcheck: Lint code and check types

Run the command:

```
npm run healthcheck
```

### 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 Tests and Exit

Run the command:

```
npm test
```

### Run the Local Stripe Webhooks Server

This is needed if you are testing Stripe.

Run the command:

```
npm run stripe:listen
```

### Run the Mock Stripe Server

Run the command:

```
npm run stripe:mock-server
```

### Index blog and documentation pages for making the documents available for searching

Run the command:

```
npm run blog-docs-indexer
```

### 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 `.prettierrc` you find in the project's root.

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 have to 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`.

The locales are split by functionality, page or entity: as your application grows, you may not want to load every JSON file to reduce the size of your bundle.

For example, the translations for the authentication are placed in `auth.json`, while the ones that are used across every page are placed under `common.json`. If you are not sure where to add some translations, simply add them to `common.json`.

<Alert type='info'>
  To simplify things, the MakerKit's starter uses by default all the available JSON files, and we recommend doing so until you have too many files.
</Alert>

### Adding a new translation file

To add a new translation file, simply add a JSON file at `public/locales/en/{filename}.json`. Then, open the file `src/lib/props/with-translation-props.ts` `withTranslationProps` and add the namespace to `DEFAULT_OPTIONS`.

For example, let's assume you add a new namespace (eg. a JSON file) named `editor.json`. Now, to automatically add the translations of this file, we will add it to the `DEFAULT_OPTIONS` variable:

```tsx
const DEFAULT_OPTIONS: Options = {
  locale: DEFAULT_LOCALE,
  localeNamespaces: [
    'common',
    'auth',
    'organization',
    'profile',
    'subscription',
    'editor' // <--- HERE IT IS
  ],
};
```

If you want to simplify things, simply merge all the files into one; the only downside is that lazy-loading translation files will not be possible.

### Lazy Loading Locale files

Let's assume your `editor.json` file is only loaded in your `EditorPage` component; so it can make sense to only load translations on that page. To do so, we can use `withAppProps`:

```tsx filename=pages/editor.tsx
export default function EditorPage() {
  return <></>;
}

export function getServerSideProps() {
  return withAppProps({
    localeNamespaces: ['editor']
  });
}
```

The `editor` namespace will be added to the default ones specified in  `DEFAULT_OPTIONS`. This approach is great if the translations in the specified JSON file are only added to a specific page.


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 good, and Makerkit doesn't really care about 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: '',
}
```

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 MJML to render emails

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 filename=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.mail) 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


Makerkit provides various utilities to reduce the boilerplate needed to write API functions with Next.js.

Normally, we write Makerkit's API handlers using the conventions below:

```tsx filename=/pages/api/members.ts
import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';
import { withAppCheck } from '~/core/middleware/with-app-check';
import { withAdmin } from '~/core/middleware/with-admin';

const SUPPORTED_METHODS: HttpMethod[] = ['GET', 'POST'];

export default function members(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    // throw if method is not in SUPPORTED_METHODS array
    withMethodsGuard(SUPPORTED_METHODS),
    // initialize Firebase Admin
    withAdmin,
    // check request is genuine with Firebase AppCheck
    withAppCheck,
    // check user is authenticated
    withAuthedUser,
    // execute API logic
    membersHandler
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}

async function membersHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const members = await fetchOrganizationMembers();

  res.json(members);
}
```

Let's take a look at these functions individually.

### Piping functions

Piping functions can be useful to augment a function, validate data, or do any other check before getting to the function handler, where we write the bulk of the logic.

The utility we use is `withPipe`, a dead-simple function that iterates over functions until one of them stops (or calls functions such as `req.end()`, `req.send()`, `req.json()`).

```tsx
export default withPipe(
  (req, res) => {
    if (req.method !== 'POST') {
      res.status(409).end();
    }
  },
  (req, res) => {
    // this will never execute!
  }
)
```

### Guarding against unsupported HTTP methods

This utility helps reject requests whose method is not defined in the array.

For example, let's assume we only want to reply to `GET` and `POST` requests:

```tsx filename=/api/hello.ts
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';

export default withPipe(
  withMethodsGuard(['GET', 'POST'])
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withMethodsGuard(['PUT']);
}
```

If the API is called with any other HTTP method, this function will throw a 405 error and add an `Allow` HTTP header with the list of allowed methods.

### Initializing the Firebase Admin

To be able to use the Firebase Admin functions in your Next.js API, you need to initialize it before calling its services, such as Firestore, Auth, etc.

```tsx
import { withAdmin } from '~/core/middleware/with-admin';

export default withPipe(
  withAdmin,
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withAdmin();
}
```

### Rejecting requests from non-authenticated users

This is one of the most important functions you will be using, i.e. ensuring the API request is coming from an authenticated user:

```tsx
import { withAuthedUser } from '~/core/middleware/with-authed-user';

export default withPipe(
  withAuthedUser,
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withAuthedUser();
}
```

### Rejecting requests from bots

If you enabled AppCheck in your application, you can disallow requests from bad actors and spammy clients:

```tsx
import { withAppCheck } from '~/core/middleware/with-app-check';

export default withPipe(
  withAdmin,
  withAppCheck,
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withAdmin();
  await withAppCheck();
}
```

### Handling Exceptions

The utility `withExceptionFilter` is useful for managing exceptions from an API handler.

This utility will report the exception to `Sentry.io` (if configured), log the exception so that you can debug it, and return a JSON with some metadata to **avoid leaking information to the clients**: therefore, I highly encourage you to use this utility where possible.

Check out the example below:

```tsx
export default function apiHandler() {
  const handler = withPipe(
    withMethodsGuard(SUPPORTED_METHODS),
    withAuthedUser,
    (req, res) => {
      return await getData();
    }
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}
```


Writing a Next.js API route with Makerkit


[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 a first line of defence 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`;

function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  try {
     // we can safely use data with the interface Body
    const schema = getBodySchema();
    const { displayName, email } = schema.parse(req.body);

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

export default function apiHandler() {
  const handler = withPipe(
    withMethodsGuard(['POST']),
    withAuthedUser,
    inviteMemberHandler,
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}
```

You can also use `safeParse` if you prefer not to throw an error when the
validation fails:

```tsx
function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const schema = getBodySchema();
  const result = schema.safeParse(req.body);

  // we use result.success as a type guard
  // when false, we throw an exception
  if (!result.success) {
    return throwBadRequestException(res);
  }

  // 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).


Validating the API inputs with Zod and Typescript


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:

- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`

Copy these values to your local `.env` file.

## 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".

They are the default plans in MakerKit, so it's good to start with these for
playing around with Stripe: you can change them later on.

Now that we have created the plans, we need to set the plan IDs in your
configuration. Open the file `~/configuration.ts` and set the
`stripePriceId` property with IDs of your plans:

```tsx
{
  name: 'Basic',
  description: 'Unlimited applications and 2-hour onboarding session',
  price: '$249/year',
  stripePriceId: '<YOUR_PRICE_ID_GOES_HERE>',
}
```

### 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).

### Connect CLI with your account

To connect the Stripe CLI with your account, run the following command:

```
npm run stripe:listen
```

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 very useful for understanding its code.

Learn how to configure Stripe with your MakerKit application

Set up Stripe Payments for Next.js and Firebase SaaS applications


Makerkit handles five webhooks coming from Stripe, and stores "just enough" data into the organization's entity to function correctly.

The Stripe's webhooks topics are defined here at `src/core/stripe/stripe-webhooks.enum.ts`:

```tsx
export enum StripeWebhooks {
  AsyncPaymentSuccess = 'checkout.session.async_payment_succeeded',
  Completed = 'checkout.session.completed',
  AsyncPaymentFailed = 'checkout.session.async_payment_failed',
  SubscriptionDeleted = 'customer.subscription.deleted',
  SubscriptionUpdated = 'customer.subscription.updated',
}
```

To handle webhooks, we created an API route at `pages/api/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. `AsyncPaymentSuccess`: an asynchronous payment arrived
3. `AsyncPaymentFailed`: an asynchronous payment failed
4. `SubscriptionDeleted`: the subscription was deleted by the customer
5. `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 "Paid".
</Alert>

The subscription's object has the following interface:

```tsx
export enum OrganizationPlanStatus {
  AwaitingPayment = 'awaitingPayment',
  Paid = 'paid',
}

export interface OrganizationSubscription {
  id: string;
  priceId: string;

  status: OrganizationPlanStatus;
  currency: string | null;

  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.

### Async Payment Success

When a payment is asynchronous, we need to wait for another webhook for confirmation. When this webhook is received, we turn the `status` property from `AwaitingPayment` to `Paid`.

### Async Payment Failed

When an asynchronous payment fails, we send an email to the customer to warn them.

### 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.

Learn how MakerKit handles Stripe Webhooks in your application

How Makerkit handles Stripe Webhooks


While using subscriptions by default, you can also offer one-time payments to your customers.

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, choose `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 particularly 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. 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 filename=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, that 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

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 filename=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" as a way to refer to a group of users. The name "organizations" may not make sense to your application's domain, even while having 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 filename=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 filename=organization.ts
interface Organization {
  // ...
  integrations: Integration[];
}
```

Extending Organizations


Most of the 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 logic within the same file and encapsulated as simple functions. 

Let's take a look at a simple permission function in the boilerplate:

```tsx filename=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 role (or anything) of the target user.

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

If the condition is truthy, then the `InviteUserComponent` component will be displayed.

Otherwise, you can use these functions throughout the application, both on the client and on the server. 

Let's assume we want to allow only paying users to perform a certain action:

```tsx filename=src/lib/organizations/permissions.ts
export function isPayingUser(
  subscription: Maybe<OrganizationSubscription>
) {
  return (
    subscription?.status === OrganizationSubscriptionStatus.Paid
  );
}

function isAdmin(
  role: MembershipRole
) {
  return role === MembershipRole.Admin;
}
```

Now, combine this function with other conditions:

```tsx filename=src/lib/organizations/permissions.ts
export function canCreateNewThing(
  subscription: Maybe<OrganizationSubscription>,
  userRole: MembershipRole,
) {
  return isPayingUser(subscription) && isAdmin(userRole);
}
```

Learn how to write a simple permissions system with Makerkit

Managing User Permissions

Learn how to configure and write your product's Blog and Documentation

Blog and Docs


MakerKit has both Blogs and a Documentation site built-in so that you can
start working on your content even before you launch your product.

We placed the sections together because, naturally, Blog and Docs share a good amount of code.

We can write the Blog posts and the documentation pages using [MDX
files](https://mdxjs.com/).

Thanks to MDX, we can augment the built-in components with richer styling and more complex components.


MakerKit allows you to easily add blog posts and a documentation website for your Next.js application

Add Blog posts and a Documentation website to your Next.js application


We can add your website's blog posts within the `_posts` folder.

## Collections

Before writing a blog post, we have to define the post's collection. We use collections to organize our blog posts by their category.

For example, your blog could have collections such as changelog,
announcements, tutorials, etc.

MakerKit generates every collection with their page, listing all the articles
associated with it.

To change a collection page, please change the file `src/pages/blog/[collection].ts`.

### Adding collections

Let's see how we can define a `collection` in Typescript:

```tsx
interface Collection {
  name: string;

  // image
  logo?: string;
  emoji?: string;
}
````

As you can see, the only required property to create a collection is a name. You can also attach an image or a simple emoji for each collection.

A collection can be simply the following file:

```json
{
  "name":"Changelog"
}
```

## Writing a Blog Post
The interface of a blog post is the following:

```tsx
interface Post {
  title: string;
  excerpt: string;

  date: string;
  live: boolean;
  tags?: string[];

  coverImage?: string;

  ogImage?: {
    url: string;
  };

  author?: {
    name: string;
    picture: string;
    url: string;
  };

  canonical?: string;
}
```

These values can be defined in MDX files using the `frontmatter`, for example:

```yaml
---
title: An Awesome Post title
except: "Write here a short description for your blog post"
collection: changelog.json
date: '2022-01-05'
live: true
coverImage: '/assets/images/posts/announcement.webp'
tags:
  - changelog
  - coolstuff
---
```

#### Title
The property `title` is the title of the blog post.

NB: it does not correspond to the URL. The URL
segment, instead, is defined by the name of the file.

#### Excerpt
Write a short description for your blog post. This description will also
populate the relative meta tags.

#### Collection
The property `collection` is the path to the collection associated with the blog post.

NB: the `.json` extension needs to be part of the name.

#### Live
You can choose to publish or not a blog post by setting this property to `false`.

### Cover Image
The property `coverImage` is the path to the post's image.

If `coverImage` is undefined, and the configuration property `autoBanners` is set to `true` then **a banner is
automatically generated** for your blog posts.

### Tags
A list of tags you can attach to the post.

For each tag, MakerKit generates a page with every blog post associated, which you can update at `src/pages/blog/tags/[tag.tsx]`.


Learn how to add blog posts in your MakerKit application

Add Blog posts to your Next.js application


We place the MakerKit's documentation pages within the `_docs` folder.

## Topics
The pages are defined hierarchically so that you can define your
documentation in the following way:

```
- _docs
  - [topic]
    - [topic.json]
    - [page].mdx
```

The documentation you're reading, for example, is defined as follows.

The MakerKit kit has a folder called `_docs`: in this folder, we have a list of
sub-folders for each topic we are describing.

Each folder has a metadata file named `meta.json`:

```json
{
  "title": "Blog and Docs",
  "position": 2,
  "description": "Learn how to configure and write your product's Blog and Documentation"
}
```

The `position` property defines the order of the topics. In
the case above, the topic `Blog and Docs` will be the third topic in the list.

## Pages

Within each topic, we define the collection pages defined as MDX files.
They share the same components as the blog posts' files.

A page is defined as follows:

```yaml
---
title: Blog
position: 1
---
```

The `position` property defines the order in which the page is listed within
the topic.


Learn how to add documentation pages in your Next.js application

Add a Documentation website to your Next.js application


Makerkit's blog and documentation pages come with built-in search
functionality that does not reply on complex and expensive cloud services
such as Alogolia and ElasticSearch.

Instead, we used [Minisearch](https://lucaong.github.io/minisearch/), a lightweight Javascript Search
Engine.

### How does Minisearch work?

Instead of indexing our posts at runtime, we index all our
documentation and blog articles at build time, right after the Next.js
application has finished building.

Minisearch creates a simple index file in the `public` folder. The API loads
the index and responds to the user's query.

By default, we index two directories: `_docs` and `_posts`. Of course, it's
easy to extend this to other folders if you create more types of content.

Below you can find our indexer script that takes care of indexing
recursively our `.mdx` files in the folders provided:

```tsx filename=search-indexer.ts
const FIELDS = ['content', 'path', 'tag', 'title', 'collection', 'slug'];

export async function searchIndexer() {
  const miniSearch = new MiniSearch({
    fields: FIELDS,
    storeFields: FIELDS,
  });

  const engine = new SearchEngine(miniSearch);

  await engine.indexDirectory(`_posts`, (doc) => {
    return { ...doc, tag: `blog` };
  });

  await engine.indexDirectory(`_docs`, (doc) => {
    return { ...doc, tag: `docs` };
  });

  await engine.export();

  process.exit();
}
```

Assuming you have another folder named `_guides`, you could add:

```tsx filename=search-indexer.ts
await engine.indexDirectory(`guides`, (doc) => {
  return { ...doc, tag: `guide` };
});
```

<Video src={"/assets/images/docs/search.mp4"} />

### Does it scale?

It's important to keep the index not larger
than few MBs, otherwise it will exceed the maximum memory available to the
API function.

That could be more or less a few hundreds pieces of content (eg. articles),
so you may have some room before having to migrate.


Learn how Makerkit makes it easy to add a simple search engine for your blog posts and documentation

Searching Posts and Documentation with Minisearch

Learn how to use, edit or replace MakerKit's UI components

UI Components


MakerKit comes with a few pre-built components by default.

While it will need some work, you are free to swap the default components with
your own or with your favourite UI library.

We used the the wonderful [Headless UI](https://headlessui.dev) built by the
            Tailwind team, to build components such as `Dropdown`, `Popover`
            and `Modal`.


MakerKit's UI React Component


The Route Shell Component is a layout wrapper for your application's pages.

```tsx
const Dashboard = () => {
  return (
    <RouteShell title={'Dashboard'}>
      <Head>
        <title key={'dashboard'}>Dashboard</title>
      </Head>

      <div>
        // Dashboard Content
      </div>
    </RouteShell>
  );
};

export default Dashboard;

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
  return await withAppProps(ctx);
}
```

## Properties

This component accepts two properties
- **title**: the title of the page
- **style**: 'topHeader', 'sidebar', or 'custom'

```tsx
interface Props {
    title: string;
    style: 'topHeader' | 'sidebar' | 'custom'
}
```

## Features
- It handles sign-out redirects automatically when the user signs out
- Sets the page title automatically
- It provides with 3 layout style configurations:
    - Top Menu
    - Side Menu
    - Custom

## Layouts

### Top Menu

In this style, the menu of the application is horizontal, and the whole
content is centered.

<Image src='/assets/images/docs/route-shell-top-navbar.webp' width={2456}
       height={1624} />

### Side Menu

In this style, the menu of the application is placed in a left-hand sidebar.

<Image src='/assets/images/docs/route-shell-sidebar.webp' width={2442}
       height={1628} />


### Custom

In this case, no layout is provided; it will simply wrap the children, and it
 will be the consumer's responsibility to set up the layout.


Route Shell Component


The component's styles have largely been placed in a single file `components.css`
which you can find at `src/styles/components.css`.

Ok, let us explain why.

Even though we are trying to MakerKit look fantastic from the get-go,
chances are you will be changing the design heavily.

To make it as easy as
possible, we think that by placing the styles in a single place, you'll be
able to go through each style faster than if you had to chase many files in
the codebase.

Each class has been defined styled using Tailwind. For example, the styles
of the `Alert` component is defined as follows:

```css
@tailwind components;

@layer components {
    .Alert {
        @apply
            py-4 border-l-8
            px-4 rounded-lg
            font-semibold text-sm
            flex items-center justify-between;
    }

    /* ... other components */
}
```

Styling MakerKit's Components with Tailwind CSS


### Container

A simple component used as a responsive main container.

```tsx
import Container from '~/core/ui/Container';

function MyPage({ value, children }) {
  return (
    <Container>
      { children }
    </Container>
  );
}
```

### If

The `If` component is useful to conditionally render the children components
based on a condition:

```tsx
import If from '~/core/ui/If';

function Component({ value, children }) {
  return (
    // this `children` tree will only render if `value` is truthy
    <If condition={value}>
      { children }
    </If>
  );
}
```

It's also possibly to pass a `fallback` parameter to conditionally render a
fallback component if `condition` is falsy.

```tsx
import If from '~/core/ui/If';

function Component({ loading, children }) {
  return (
    <If
      condition={!loading}
      fallback={<span>Loading...</span>}
    >
      { children }
    </If>
  );
}
```

### ClientOnly

The `ClientOnly` component is useful to only render the children components
if the component is being rendered in a browser environment:

```tsx
import ClientOnly from '~/core/components/ClientOnly';

function Component({ children }) {
  return (
    <ClientOnly>
      { children }
    </ClientOnly>
  );
}
```

### LazyRender

The `LazyRender` component is useful to render the component's children tree
only when visible (or when being intersected according to your configuration).

Very useful for SEO and performance improvements.

```tsx
import LazyRender from '~/core/components/LazyRender';

function Component({ children }) {
  return (
    <LazyRender>
      { children }
    </LazyRender>
  );
}
```

You can supply an additional parameter `rootMargin`, which is the
`Intersection Observer` [parameter that controls the configuration of the
intersection](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin).


MakerKit's React Components Utilities


The Alert component accepts the following parameters:

```tsx
interface Props {
  type: 'success' | 'error' | 'warn' | 'info';
  useCloseButton?: boolean;
  className?: string;
}
```

### Types

#### Info

<div className='flex flex-col my-4'>
  <Alert type='info'>
    <span>Info Alert</span>
  </Alert>
</div>

```tsx
<Alert type='info'>
  Info Alert
</Alert>
```

#### Success

<div className='flex my-4 flex-col'>
  <Alert type='success'>
    <span>Success Alert</span>
  </Alert>
</div>

```tsx
<Alert type='success'>
  Success Alert
</Alert>
```

#### Warn

<div className='flex my-4 flex-col'>
  <Alert type='warn' useCloseButton={true}>
    <span>Warn Alert</span>
  </Alert>
</div>

```tsx
<Alert type='warn' useCloseButton={true}>
  Warn Alert
</Alert>
```

#### Error

<div className='flex my-4 flex-col'>
  <Alert type='error' useCloseButton={true}>
    <span>Error Alert</span>
  </Alert>
</div>

```tsx
<Alert type='error' useCloseButton={true}>
  Error Alert
</Alert>
```


Alert Component

The Badge component accepts the following parameters:

```tsx
type Color = `normal` | 'custom';
type Size = `normal` | `small`;

interface Props {
  color?: Color;
  size?: Size;
  className?: string;
}
```

### Basic Badge

<div className='flex my-4'>
  <Badge>
    <span>Label</span>
  </Badge>
</div>

```tsx
<Badge>
  Label
</Badge>
```

### Badge Sizes

<div className='my-4 flex space-x-4 items-center'>
  <div>
    <Badge size={'small'}>
      <span>Small Badge</span>
    </Badge>
  </div>

  <div>
    <Badge size={'normal'}>
      <span>Normal Badge</span>
    </Badge>
  </div>
</div>

```tsx
<div className='my-4 flex space-x-4 items-center'>
  <div>
    <Badge size={'small'}>
      Small Badge
    </Badge>
  </div>

  <div>
    <Badge size={'normal'}>
      Normal Badge
    </Badge>
  </div>
</div>
```


Badge Component


The Button component accepts the following parameters:

```tsx
type Color =
  | 'primary'
  | 'secondary'
  | 'transparent'
  | 'danger'
  | 'custom';

type Size = 'normal' | 'small' | 'large' | 'custom';
type Style = `normal` | `outline` | `flat`;

interface Props {
  block?: boolean;
  color?: Color;
  size?: Size;
  style?: Style;
  loading?: boolean;
  href?: string;
}
```

### Button Types

<div className={`my-4 flex flex-col md:flex-row md:items-center space-y-2
 md:space-y-0 space-x-4`}>
  <Button color={'primary'}>
    Click Here
  </Button>

  <Button color={'secondary'}>
    Click Here
  </Button>

  <Button color={'danger'}>
    Click Here
  </Button>

  <Button color={'transparent'}>
    Click Here
  </Button>
</div>

```tsx
<Button color={'primary'}>
  Click Here
</Button>

<Button color={'secondary'}>
  Click Here
</Button>

<Button color={'danger'}>
  Click Here
</Button>

<Button color={'transparent'}>
  Click Here
</Button>
```

### Button Sizes

<div
  className='my-4 flex flex-col md:flex-row items-start md:items-center
  space-y-2
 md:space-y-0 space-x-4'
>
  <div>
    <Button color={'primary'} size={'small'}>
      Small Button
    </Button>
  </div>

  <div>
    <Button color={'primary'} size={'normal'}>
      Normal Button
    </Button>
  </div>

  <div>
    <Button color={'primary'} size={'large'}>
      Large Button
    </Button>
  </div>
</div>

```tsx
<div>
  <Button color={'primary'} size={'small'}>
    Small Button
  </Button>
</div>

<div>
  <Button color={'primary'} size={'normal'}>
    Normal Button
  </Button>
</div>

<div>
  <Button color={'primary'} size={'large'}>
    Large Button
  </Button>
</div>
```

### Loading State button

<div className='my-4'>
  <Button color={'primary'} loading={true}>
    Click Here
  </Button>
</div>

```tsx
<Button color={'primary'} loading={true}>
  Click Here
</Button>
```

### Button Link

The `Button` component with a `href` attribute will wrap a Next.js `Link`
component and can be used as a normal link styled as a button.

<div className='my-4'>
  <Button color={'primary'} href={'/docs/components-button'}>
    Go to Page
  </Button>
</div>

```tsx
<Button color={'primary'} href={'/docs/components-button'}>
  Go to Page
</Button>
```

### Full Width Button

You can add the `block` attribute to let the button grow as much as its parent.

<div className='my-4 w-60'>
  <Button block color={'danger'}>
    Are you sure you want to continue?
  </Button>
</div>

```tsx
<Button block color={'danger'}>
  Are you sure you want to continue?
</Button>
```


Button Component


The `TextField` is a wrapper around the native `input` HTML element.
Therefore, the component accepts the parameters accepted by
`HTMLInputElement`, and a further `innerRef` parameter to pass a React `ref`
to the inner input:

```tsx
type Props = React.InputHTMLAttributes<unknown> & {
  innerRef?: LegacyRef<HTMLInputElement>;
};
```

## Usage

<div className={'flex flex-col space-y-4'}>
  <TextField>
    <TextField.Label>
      Email Address
      <TextField.Input placeholder={'your@email.com'} />
    </TextField.Label>
  </TextField>

  <TextField>
    <TextField.Label>
      Password
      <TextField.Input type={'password'} placeholder={'**************'} />
      <TextField.Hint>Yo! Make it strong :)</TextField.Hint>
    </TextField.Label>
  </TextField>

  <TextField>
    <TextField.Label>
      Description
      <div className={'TextFieldInputContainer'}>
        <textarea
          className={'TextFieldInput h-20'}
          placeholder={'Write a description'}
        />
      </div>

      <TextField.Hint>
        <p className={'flex space-x-1 text-xs'}>
          <span>Write a description up to 160 characters</span>
        </p>
      </TextField.Hint>
    </TextField.Label>
  </TextField>
</div>

```tsx
<div className={'flex flex-col space-y-4'}>
  <TextField>
    <TextField.Label>
      Email Address

      <TextField.Input placeholder={'your@email.com'} />
    </TextField.Input>
  </TextField>

  <TextField>
    <TextField.Label>
      Password

      <TextField.Input
        type={'password'}
        placeholder={'**************'}
      />

      <TextField.Hint>Yo! Make it strong :)</TextField.Hint>
    </TextField.Label>
  </TextField>

  <TextField>
    <TextField.Label>
      Description
      <div className={'TextFieldInputContainer'}>
        <textarea
          className={'TextFieldInput h-20'}
          placeholder={'Write a description'}
        />
      </div>

      <TextField.Hint>
        <p className={'flex space-x-1 text-xs'}>
          <span>Write a description up to 160 characters</span>
        </p>
      </TextField.Hint>
    </TextField.Label>
  </TextField>
</div>
```


Text Field Component


The Heading component accepts the following parameters:

```tsx
type HeadingType = 1 | 2 | 3 | 4 | 5 | 6;

interface Props {
  type: HeadingType;
}
```

### Usage

<Heading type={1}>Heading 1</Heading>
<Heading type={2}>Heading 2</Heading>
<Heading type={3}>Heading 3</Heading>
<Heading type={4}>Heading 4</Heading>
<Heading type={5}>Heading 5</Heading>
<Heading type={6}>Heading 6</Heading>

```tsx
<Heading type={1}>Heading 1</Heading>
<Heading type={2}>Heading 2</Heading>
<Heading type={3}>Heading 3</Heading>
<Heading type={4}>Heading 4</Heading>
<Heading type={5}>Heading 5</Heading>
<Heading type={6}>Heading 6</Heading>
```


Heading Component


This Image Upload Input component is a wrapper around `input[file]` which
improves the UX of uploading file images.

The component accepts the following props:

```tsx
type Props = Omit<React.InputHTMLAttributes<unknown>, 'value'> & {
  innerRef?: LegacyRef<HTMLInputElement>;
  image?: string | null;
  onClear?: () => void;
};
```

## Usage

```tsx
function Form() {
  const onClear = () => console.log(`The user cleared the existing image`);
  const existingImage = `/a/url/to/an/image.png`;

  return (
    <form>
      <ImageUploadInput
        onClear={onClear}
        name={'photoUrl'}
        image={existingImage}
      >
        Upload Image
      </ImageUploadInput>
    </form>
  );
}
```

### Demo

Select an image:

<div>
  <label className={'w-full md:w-[250px]'}>
    <ImageUploadInput>
      <span>Select an Image</span>
    </ImageUploadInput>
  </label>
</div>


Image Upload Input Component


Sometimes, it can take some time to load a route, especially if you're hitting a cold function. To improve the user experience, it can be useful to display a loading spinner while the route is being loaded.

Makerkit provides the `AppRouteLoadingIndicator` component, which will automatically show up when a route is being loaded. Once the route is fully loaded, the spinner will disappear.

To add it to your application, simply add it to `_app.tsx`:

```tsx filename=_app.tsx
// import the component
import AppRouteLoadingIndicator from '~/core/ui/AppRouteLoadingIndicator';

// add it to your render function
<AnalyticsTrackingEventsProvider>
  <AppRouteLoadingIndicator>
    Loading. Please Wait...
  </AppRouteLoadingIndicator>

  <Component {...pageProps} />
</AnalyticsTrackingEventsProvider>
```

Router Loader Component

Learn about the various utilities that come with Makerkit

Utilities


MDX is one of the most common Markdown flavours for React-based websites. It
allows us to include our own components into our documents and take out
blog's interactivity to the next level.

The Makerkit starter uses MDX for writing documents in the blog and in the
documentation; it may be likely that you would want to add your own document
types and use MDX for other purposes; for example, you could replace some of
your HTML with MDX documents if you felt like for making it easier to change
by non-technical teammates.

In this section, we will explain how to compile MDX content with the
Makerkit's utilities.

## 1) Compiling MDX to JS

The first step is to compile MDX to Javascript.

To do so, compile your MDX files with the following utility:

```tsx
import { compileMdx } from '~/core/generic';

// MDX string
const content = '';

// JS representation of your MDX content
const compiled = compileMdx(content);
```

## 2) Pass the compiled MDX file into the MDXRenderer component

Finally, we import the `MDXRenderer` component that takes the string
compiled with the `compileMDX` utility and renders it as `HTML`.

```tsx
import MDXRenderer from '~/components/blog/MDXRenderer';

function ArticleBody(props: React.PropsWithChildren<{ content: string }>) {
  return (
    <div>
      <MDXRenderer code={content} />;
    </div>
  );
}
```

Under the hood, the component `MDXRenderer` will inject a couple of
custom components we use in the documents: these can be viewed and
edited at `~/components/blog/MDXComponents`.

## Custom MDX Components

### NextImage

The `NextImage` component replaces the default `img` HTML tag and adds the
awesome capabilities of the default `Image` component baked in Next.js.

You have 2 ways to use this:
1. Simply use an image tag as you would normally
2. Use `NextImage` as a component, which is better if you have to pass
custom attributes such as `width` and `height`

## ExternalLink

All links are automatically patched with the following attributes:
`target="_blank"` and `rel="noopener noreferrer"` for security and UX reasons.

## Video

To embed videos in your blog and docs, simply use the `Video` component:

```tsx
<Video src={"/path/to/video.mp4"} />
```

### Other UI Components

Additionally, we also imported some components from `~/core/ui` by default
that you can use in any MDX document.


Compile MDX Documents with Makerkit


Makerkit uses various React Hooks for very common tasks, such as a simple
reducer for asynchronous tasks, or for executing HTTP requests.

## useRequestState

You can use this hook as a simple reducer for asynchronous tasks, like HTTP
requests or asynchronous operations with Firestore.

To create the hook, you can use the following snippet:

```tsx
const { state, setError, setData, setLoading } =
    useRequestState<Data>();
```

This hooks returns the current state `state` and the methods to update it.
The `state` variable has the following interface:

```tsx
type State<Data, ErrorType> =
  | {
      data: Data;
      loading: false;
      success: true;
      error: Maybe<ErrorType>;
    }
  | {
      data: undefined;
      loading: true;
      success: false;
      error: Maybe<ErrorType>;
    }
  | {
      data: undefined;
      loading: false;
      success: false;
      error: Maybe<ErrorType>;
    };
```

## useApiRequest

You can use this hook to perform HTTP requests from your UI to your API and
uses `useRequestState` under the hood for managing the state.

The function has the following interface:

```tsx
function useApiRequest<Resp = unknown, Body = void>(
  path: string,
  method: HttpMethod = 'POST'
)
```

For example, if we wanted to make an API request to an endpoint, we could do
the following:

```tsx
function SignIn() {
  const [signIn, signInState] = useApiRequest(`/api/sign-in`);

  useEffect(() => {
    if (signInState.success) {
      window.location.href = '/dashboard';
    }
  }, [signInState]);

  if (signInState.loading) {
    return <span>Loading...</span>
  }

  return (
    <form onSubmit={() => signIn()}></form>
  );
}
```


Reusable React Hooks utilities for common tasks

Reusable React Hooks

Learn how to run and update the Cypress E2E tests

Testing


The Makerkit SaaS boilerplate comes with a set of predefined tests with the following goals:

1. Verify that the boilerplate application works well
2. Provide instructions for building your own tests

As your application grows, the tests will inevitably need to be updated and
maintained. We hope that our tests will be simple to understand and to
change when you will need them.

## Running the Next.js testing environment

First, we have to run the following command to run Next.js with a testing
environment (i.e. using `.env.test`):

```
npm run dev:test
```

This command will start a Next.js dev server at http://localhost:3000, so
it's important to make sure you have no other Next.js server running at the
same port.

Additionally, we have to start the **Firebase Emulator server**:

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

## Running Cypress in development mode

While you build your tests, it can be handy to use a windowed version of the
Cypress testing suite, so that you can easily retry the tests without having
to re-run the while tests suite.

To do that, run the following command:

```
npm run cypress
```

## Running All Cypress tests

Whenever you want to run all your tests at once, you can use the following commands:

```
npm run cypress:headless
```

This will run all the tests and exit.

## Running Cypress in CI mode

Whenever you want to run all your tests in a CI
environment, you can use the following commands:

```
npm test
```

The command above will:

1. Start the Firebase Emulator
2. Start the Next.js environment
3. Run the tests in headless mode
4. Exit and close all the processes

As you may have noticed, this is the command to run in your CI environment.

## Testing Stripe

Testing Stripe requires one more process to start, i.e. the official Stripe
emulator.

The command below **will require Docker installed**, which is why you can
choose to disable it by setting the environment variable `ENABLE_STRIPE_TESTING`
to `false` from the `.env.test` environment file:

```bash filename=.env.test
ENABLE_STRIPE_TESTING=false
```

If instead, you want to test Stripe Checkout as well, run the command below:

```
npm run stripe:mock-server
```

As we've mentioned, this will require Docker running. Of course, we think
it's worth it.


Learn how to run Cypress E2E tests for your Makerkit application

Running Cypress Tests with Firebase and Next.js


To run your tests in any CI, we recommend you simply run the following command:

```
npm test
```

This command takes care of running all the required services, importing the test data, executing the tests and then exiting.

### The Makerkit testing pipeline

As mentioned in the previous section, testing a Makerkit requires a few services to be up and running:

- the Next.js server
- the Firebase emulators
- optionally, the Stripe Mock server

While executing these tests in your CI, this can get cumbersome. Therefore, we provided a single script to execute all your tests in one simple command: you can find the script at `scripts/test.sh`, which will contain the following content:

```
set -e

npm run dev:test & npm run stripe:mock-server &
npm run cypress:headless
sh scripts/kill-ports.sh
```

Let's explain it, so you can add your own modifications to it.

The first command will run (in parallel and in the background) the Next.js server and the Stripe mock server:

```
npm run dev:test & npm run stripe:mock-server &
```

Afterward, we execute the Cypress tests in headless mode:

```
npm run cypress:headless
```

Finally, we clean up all the ports that may have remained open after executing the script:

```
sh scripts/kill-ports.sh
```

If you update your ports, remember to change them also in `scripts/kill-ports.sh`.

### Running the Tests in CI mode

Finally, the tests can be executed with the command `npm test`. 

This command **will automatically run the Firebase emulators** and the `test.sh` script, and is defined as:

```
"test": "firebase emulators:exec --project demo-makerkit --import ./firebase-seed \"sh ./scripts/test.sh\"",
```

When finished, the emulators will exit.

Learn how to test your Makerkit in your CI

CI Tests


Due to the hard-to-rollback nature of some tests (such as accepting invitations) - some Tests won't work well in development mode.

To have a clean testing environment at each run, we recommend running the following command:

```
npm test
```

Of course, some of the tests will work just fine, but not the ones related to accepting invites.

This would be solved if we could reset the Firebase Firestore data programmatically between test runs, but as far as we know this is not yet possible.

Testing Limitations

Learn how to prepare your application for shipping to production

Going to Production


Before going to production, it's essential to follow certain precautions to avoid failures.

## 1) Environment Variables

First, we need to inject the correct environment variables into its relative
environment and do so safely. MakerKit comes with predefined templates that allow you to understand where each variable should be added.

Before publishing your SaaS, or if you are making a production release after
a change and this included an environment variable, ensure your Vercel
Console is up to date with the correct variable in the correct environments.

## 2) Firebase Security Rules (Firestore and Storage)

Whenever your Security rules need updating, you have to make sure to
propagate these changes and publish them from your Firebase Console.

## 3) Firestore Indexes

As you may know, the Firestore emulator does not fail when a new index is
needed like its production version. This can be dangerous!

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

### Create Index Exemption by clicking on the link below

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

If you have added other complex queries that need a Firestore index
exemption, **ensure you are testing thoroughly with a real Firestore database
to avoid similar issues**.

## 4) Enable Authentication providers

If you have added authentication providers other than Google, make sure you
have enabled them from the Console and added the needed configuration so
that they work correctly. 

For many of them, you will have to provide an app
ID or a key, so make sure to configure and test them in a production environment.

## 5) Enable your Stripe account Billing Status

Remember to complete your Stripe account's information and enable billing
(of course, also replacing the correct environment variables) and not to
forget it in `Testing Mode`.

## 6) Enable Google Analytics (Optional)

Understand how visitors find your website early on.

## 7) Enable Sentry (Optional)

With 4000 events for free per month, we recommend that you use [Sentry.io](https://sentry.io) for
ensuring you can catch, analyze and fix any runtime errors in your application that your users will encounter.

Checklist to ship a MakerKit application to Production


Before going live to production, it's crucial to set the correct environment
variables for your production environment. As we've already seen before, you can organize your environment variables into three files:

- `.env`: here, you can add variables that are shared across environments
- `.env.local`: here go the variables that should be limited to your own machine, and it's recommended not to check this file in your VCS
- `.env.development`: here, you can add the variables that should only be used during development
- `.env.production`: here, you add the variables that should be used in your production environment

Typically, you would never place private data in your `.env.production` file because that would cause your data to be leaked.

You should set any value that is not secret or confidential (such as the API Key of your Firebase project or the value of a feature flag) in the `.env.production` file. 

Alternatively, suppose you are using variables such as the project's private key or any value that is supposed to be secret: in that case, you should ensure to inject these values from a secure environment, for example, your CI or your Vercel console.

## Shared Variables

As mentioned above, we can add variables shared across environments in the `.env` configuration file. MakerKit's `.env` template looks like the below:

```
# firebase
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID='
NEXT_PUBLIC_SITE_URL=
FIREBASE_CLIENT_EMAIL=
GCLOUD_PROJECT=
```

## Local Variables

To use data that is only limited to your machine, use a `.env.local` configuration file. Do not check this file in your VCS: therefore, you can use it to set private variables:

```
FIREBASE_PRIVATE_KEY=
SECRET_KEY_THAT_SHOULD_NOT_BE_EXPOSED=
```

## Development Variables

In our `.env.development` configuration, we will set variables such as the Firebase Emulator's configuration that will only run when running `next dev`, e.g., when we're developing the application:

```
NEXT_PUBLIC_EMULATOR=true
FIRESTORE_EMULATOR_HOST=localhost:8080
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIREBASE_STORAGE_EMULATOR_HOST=localhost:9199
FIREBASE_PUBSUB_EMULATOR_HOST=localhost:8085
NEXT_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT=8080
NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT=9099
NEXT_PUBLIC_FIREBASE_STORAGE_EMULATOR_PORT=9199
FEATURE_FLAG=true
```


## Production Variables

In our `.env.production` configuration, we will set variables for the production application.

```
NEXT_PUBLIC_SITE_URL=https://myamazingapp.com
FEATURE_FLAG=false
```

Careful! Do not add sensitive data here. Instead, add it from your CI or Vercel Console.

Setting the correct environment variables of a Next.js and Firebase application


When running the Firebase Emulator, you can update your Firebase Firestore and Storage security rules by simply changing the relative files `firestore.rules` and `storage.rules`.

Before deploying your application to your users, you need to make sure that
you're also publishing the security rules from your Firebase Console.

### Storage Security Rules

To publish your Firebase Storage security rules, navigate to the Firebase
Console.

From the main sidebar, click on "Storage". Afterwards, click on the "Rules" tab:

<Image
    width="955"
    height="719"
    src="/assets/images/docs/storage-rules-tab.webp"
/>

Afterwards, paste the content from `storage.rules` to the text editor, and
click "Publish".

<Image
    width="758"
    height="628"
    src='/assets/images/docs/storage-rules-editor.webp'
/>

### Firestore Security Rules

To update your Firestore Security rules, follow the same steps as for the
Storage rules explained above.

Of course, the only difference is navigating to the Firestore tab, and
choosing the content of `firestore.rules`.


Documentation

Explore our guides and examples to start building your app.