Tutorials

In this blog post, I want to build with you an MDX-powered blog with Next.js and Tailwind CSS: at the end of this tutorial, we will have built a free blog template that you can use to deploy your portfolio and your blog today. In addition, we will also be using Typescript and Tailwind CSS.

## Getting Started

### Bootstrapping the Next.js template with create-next-app

Let's kick-start the project with `create-next-app` - a Vercel utility to build a minimal Next.js repository. Fire up your terminal and run the following command:

```
npx create-next-app --ts
```

The command should prompt you for the project's name; type it out and continue. The command will then install the packages, and if it all goes well, you should see the output below:

```
Initialized a git repository.

Success! Created mk-next-blog-kit at /Users/MakerKit/mk-next-blog-kit
Inside that directory, you can run several commands:
```

It should create a folder structure similar to the one below:

<Image
 layout='intrinsic'
 src='/assets/images/posts/cra-folder-structure.png'
 width='294'
 height='352'
 />

### Installing dependencies

Run the command below to install other dependencies we need:

```
npm i --save rehype-slug rehype-highlight rehype-autolink-headings gray-matter feed @mdx-js/mdx next-sitemap date-fns
```

### Adding Tailwind CSS

Tailwind CSS is the hottest CSS utility framework at the time of writing, and it will likely be for a while.

Create a file named `postcss.config.js` in your root folder:

```js
module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 },
};
```

And now paste the following configuration to a new file named `tailwind.config.js`:

```js
const plugin = require('tailwindcss/plugin');

module.exports = {
 content: ['./**/*.tsx'],
 darkMode: 'class',
 corePlugins: {
 container: false,
 },
 theme: {
 container: {
 center: true,
 padding: {
 DEFAULT: '1rem',
 sm: '2rem',
 },
 },
 fontFamily: {
 serif: ['Bitter', 'serif'],
 sans: [
 'SF Pro Text',
 'Inter',
 'system-ui',
 'BlinkMacSystemFont',
 'Segoe UI',
 'Roboto',
 'Ubuntu',
 ],
 monospace: [`SF Mono`, `ui-monospace`, `Monaco`, 'Monospace'],
 },
 },
 plugins: [customContainerPlugin, plugin(ellipisfyPlugin)],
};

function ellipisfyPlugin({ addUtilities }) {
 const styles = {
 '.ellipsify': {
 overflow: 'hidden',
 'text-overflow': 'ellipsis',
 'white-space': 'pre',
 },
 };

 addUtilities(styles);
}

function customContainerPlugin({ addComponents }) {
 addComponents({
 '.container': {
 '@screen lg': {
 maxWidth: '1024px',
 },
 '@screen xl': {
 maxWidth: '1166px',
 },
 },
 });
}

```

Of course, feel free to customize the configuration as you prefer.

The last step to activate Tailwind is to edit your `styles/global.css` file and prepend the following content to the existing styles:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

# rest of your file goes here...
```

Et voilá, we're all set to start using Tailwind CSS across our pages! Now on to building the entities of our blog.

### Blog Entities

To start, we create 3 empty directories in the root directory, in which we can place the three main entities of our blog: `_posts`, `_collections`, and `_authors`.

<Image
 layout='intrinsic'
 src='/assets/images/posts/blog-entities.png'
 width='347'
 height='111'
 />

Additionally, we create two more folders, `lib` in which we place logic and API, and `components,` which hosts the components of our codebase (except for pages, which we add to the `pages` folder).

#### Authors

Here we add the authors of our blog; if you're a solo writer, it can be overkill. If you have a team of writers, you can add them to the `_authors` folder as a JSON file with the following interface:

```tsx
type Author = {
 name: string;
 picture: string;
 url: string;
};

export default Author;
```

#### Collections

Collections are, as the name says, a collection of posts. For example, we included this blog post in the `tutorials` collection. If you pay attention to the URL of this blog post, you can notice that we structured it with the slug of the collection `tutorials` and the slug of the blog post.

Collections have the following interface:

```tsx
interface WithEmoji {
 emoji?: string;
}

interface WithLogo {
 logo?: string;
}

interface Collection extends WithEmoji, WithLogo {
 name: string;
 slug: string;
 emoji: string;
}

export default Collection;
```

As you can see, we added the possibility to assign an image or an emoji to the collection.

#### Posts

This entity contains the data of our blog post, made up of the content of our MDX files and some relative content retrieved using references.

```tsx
import Author from './author';
import Collection from './collection';

type BlogPost = {
 author: Author;
 collection: Collection;
 image: string;
 description: string;
 slug: string;
 title: string;
 date: string;
 live: boolean;
 tags: string[];
 readingTime: number;
 content: string;
};

export default BlogPost;
```

#### Adding our first blog post

Now that we are aware of the shape of our entities and where we can place them, we can add our first blog post. Let's start by adding our first Author, Giancarlo!

Let's create a file named `giancarlo.json` at `_authors/giancarlo.json` with the following content:

```json
{
 "name": "Giancarlo",
 "picture": "/assets/images/authors/giancarlo.png",
 "url": "https://twitter.com/gc_psk"
}
```

Next, we can add a collection; let's name it `tutorials` just like this post.

Let's create a file named `tutorials.json` at `_collections/tutorials.json` with the following content:

```json
{
 "name": "tutorials",
 "emoji": "🖥️"
}
```

Finally, we can create a blog post with the name `create-blog-post.mdx` at `_posts/create-blog-post.mdx`.
NB: in this case, we're writing an MDX file. Therefore the extension is `.mdx`.

You can use the content below or anything else you may think of:

```yaml
---
title: 'Create an MDX-powered Blog with Next.js'
collection: '_collections/tutorials.json'
author: '_author/giancarlo.json'
date: 2022-03-30
live: true
image: '/assets/images/posts/create-blog-mdx-nextjs.png'
description: "Let's create an MDX-powered blog and portfolio starter that you can deploy right away with Next.js and Tailwind CSS"
---

## My first blog post

Yay!
```

And yay, we added our first blog post!

As you may have noticed, both `collection` and `author` are references to paths, which we resolve when building the blog posts.

### Why add authors and collections as files?

Good question! Eventually, you will want to use a CMS (such as Forestry,
Netlify CMS, Tina, etc.); adding this metadata as files means you can add and
update them using the CMS rather than being forced to deploy a new version of
your code.

This will make it easier to make edits, especially if the blog post will be
maintained by non-technical users.

## Blog API

We need to define the functions to read the blog posts, collections, and authors.

We create a Typescript file named `api.ts` at `lib/blog/api.ts` in which we define the utilities to create our blog.

At the top of this file, we define a couple of constants we need to use:

```tsx
const POSTS_DIRECTORY_NAME = '_posts';
const COLLECTIONS_DIRECTORY_NAME = `_collections`;
const AUTHORS_DIRECTORY_NAME = `_authors`;
const CWD = process.cwd();

const postsDirectory = join(CWD, POSTS_DIRECTORY_NAME);
const collectionsDirectory = join(CWD, COLLECTIONS_DIRECTORY_NAME);
const authorsDirectory = join(CWD, AUTHORS_DIRECTORY_NAME);
```

Next, let's define the function that allows us to retrieve the list of JSON files at the path specified:

```tsx
function readJson(directoryName: string) {
 return readdirSync(directoryName)
 .map((slug) => {
 const path = join(CWD, directoryName, slug);

 if (existsSync(path)) {
 const json = readFileSync(path, 'utf-8');

 try {
 const data = JSON.parse(json) as Collection;
 const realSlug = slug.replace('.json', '');

 return {
 data,
 slug,
 realSlug
 };
 } catch (e) {
 console.warn(`Error while reading JSON file`, e);
 }
 }
 }
 })
 .filter(Boolean);
}
```

To read an MDX file, we need a small utility to read the `frontmatter` of the markdown file. To do so, we can use the dependency `gray-matter`:

```tsx
import matter from 'gray-matter';

export function readFrontMatter(fullPath: string) {
 try {
 const fileContents = readFileSync(fullPath, 'utf-8');

 return matter(fileContents);
 } catch (e) {
 console.warn(`Error while reading Front matter at ${fullPath}`, e);
 }
}
```

The function below allows us to read a blog post using its slug and return its data and contents.

NB: don't worry about the functions within we haven't defined. We have skipped their implementations for simplicity, but you can find the complete source code at the end of the article.

```tsx
function getPostBySlug(slug: string) {
 const postFileName = `${slug}.mdx`;
 const postPath = join(postsDirectory, postFileName);
 const file = readFrontMatter(postPath);

 if (!file) {
 return;
 }

 const content = file.content;
 const data = file.data;
 const empty = Object.keys(data).length === 0;

 if (empty) {
 return;
 }

 const readingTime = getReadingTimeInMinutes(content);

 const post: Partial<BlogPost> = {
 live: data.live,
 readingTime,
 };

 for (const field in data) {
 if (field === 'slug') {
 post[field] = slug;
 continue;
 }

 if (field === 'collection') {
 post[field] = getCollection(data[field]);
 continue;
 }

 if (field === 'author') {
 post[field] = getAuthor(data[field]);
 continue;
 }

 if (field === 'content') {
 post[field] = content;
 continue;
 }

 if (field === 'date' && data.date) {
 try {
 post[field] = new Date(data.date).toISOString();
 continue;
 } catch (e) {
 console.error(`Error processing blog post date ${data.date}`);
 }
 }

 if (data[field]) {
 Object.assign(post, {
 [field]: data[field],
 });
 }
 }

 return post as BlogPost;
}
```

Let's summarize what happens in the function above:

- we read the blog post's matter by using its slug
- we iterate the fields of the MDX file and transform them into a processed object which has the shape `BlogPost`
- the collection and the author's data are also collected using the file system and transformed into their relative objects

Time to get our hands dirty with some components.

## Add a Next.js Blog Post page

As you may know, Next.js uses file-system routing. As such, we need to define the following path:

```
[collection]
 - [slug].tsx
```

The `collection` folder represents the collection name, while `[slug]` is the blog post's slug, which we use to find our blog post. The `slug` parameter reflects the way we named our MDX file.

Our goals are the following:
- fetch the correct post using the `slug` parameter provided
- fetch a few more posts to display belonging to the same collection
- compile the MDX content to raw HTML

Let's define a function to compile the raw MDX to HTML. To do so, we use the packages we installed in the very beginning:

```tsx
import rehypeHighlight from 'rehype-highlight';
import rehypeSlug from 'rehype-slug';
import rehypeAutoLinkHeadings from 'rehype-autolink-headings';

export async function compileMdx(markdown: string) {
 const { compile } = await import('@mdx-js/mdx');

 const code = await compile(markdown, {
 outputFormat: 'function-body',
 rehypePlugins: [rehypeHighlight, rehypeSlug, rehypeAutoLinkHeadings],
 });

 return String(code);
}
```

It's time to define the `[slug].tsx` page, which is our blog post page.

### Generating Blog Posts using getStaticPaths

When creating dynamic pages with SSG, we use `getStaticPaths,` a special Next.js function that allows you to create a list of paths generated as static files.

Let's explain the flow behind generating static paths with `getStaticPaths`
for each of our blog posts:

- **Collecting the posts**: initially, we collect all the blog posts from the
file-system
- **Adding the URL parameters**: for each blog post collected, we need to
pass an object containing the dynamic URL parameters of the page. In our
case, we need to pass the collection and the post's slugs

```tsx
export function getStaticPaths() {
 const posts = getAllPosts();

 const paths = posts.map((post) => {
 const slug = post.slug;
 const collection = post.collection.name.toLowerCase();

 return {
 params: {
 collection,
 slug,
 },
 };
 });

 return {
 paths,
 fallback: false,
 };
}
```

We build the array `paths` with items such as:

```tsx
{
 collection,
 slug,
}
```

These parameters are used to match the URL `/[collection]/[slug]`; the parameters get passed to the function `getStaticProps,` another specific Next.js function that takes the parameters collected and returns data fetched at build-time (i.e., when we build and deploy the Next.js application to Vercel).

We use the `getStaticProps` function to fetch a blog post from the
file-system and return it
to the page component, which is responsible for rendering the page's data.

### Passing data to the page component using getStaticProps

Using the data collected by the `getStaticPaths` function hook, we can
now retrieve the necessary data for rendering our blog posts. We
use the API functions we defined above in the post.

Let's summarise the flow:

- **Getting the Post**: we use the slug (retrieved from the URL parameter)
to fetch the post from the file-system using the function `getPostBySlug`
- **Getting similar posts**: retaining readers on blog is hard: it's very
valuable to get your readers' attention by displaying other blog posts they
could be interested in; we do so by getting the latest posts with the same
collection using the function `getPostsByCollection`
- **Compiling the MDX**: finally, we compile the MDX string to a format that
our component `MDXRenderer` can display
- **Passing data to the page component**: the data collected will be passed
to the page as component properties

```tsx
export async function getStaticProps({ params }: Params) {
 const { slug, collection } = params;
 const maxReadMorePosts = 6;
 const post = getPostBySlug(slug);

 if (!post) {
 return {
 notFound: true,
 };
 }

 const morePosts = getPostsByCollection(collection)
 .filter((item) => item.slug !== slug)
 .slice(0, maxReadMorePosts);

 const content = await compileMdx(post.content ?? '');

 return {
 props: {
 post,
 content,
 morePosts,
 },
 };
}
```

NB: to build the collections' and tags' pages, we do something quite similar to the above, but instead of fetching the posts, we fetch a unique set of collections and tags listing the articles assigned to them.

For simplicity, you can read the source code linked at the bottom of this article to check how we do it.

### Creating the Blog Post's Page Component

Our blog post's page looks like something similar to the below:

- **Header**: at the top of the page, we display the page's header
- **Post Head**: the head contains information and metadata about the post,
such as the Open Graph tags, Rich Results structured data, and other useful
SEO meta tags. For more information about this, check out the post about
[boosting your Next.js application SEO and get more traffic to your blog
posts](/blog/tutorials/improve-seo-nextjs)
- **Post**: the content of the blog post, such as the title and the MDX content
- **Posts List**: the list of the latest posts with the same collection

```tsx
const PostPage = ({ post, morePosts, content }) => {
 return (
 <>
 <Header />

 <Layout>
 <PostHead post={post} />

 <Post content={content} post={post} />

 <PostsList posts={morePosts} />
 </Layout>
 </>
 );
};

export default PostPage;
```

For simplicity, we won't be building all the components listed in this
post, but you are free to copy and read the code of the Next.js MDX Blog
Starter Template, which was the inspiration for this blog post.

## Rendering MDX content as HTML

To convert and render the compiled MDX code to HTML, we need to use a runtime function provided by the package `@mdx-js/mdx`.

Below, you can find the component that renders its relative HTML node, given compiled MDX code.

```tsx
import * as runtime from 'react/jsx-runtime.js';
import { runSync } from '@mdx-js/mdx';

type MdxComponent = React.ExoticComponent<{
 components: Record<string, React.ReactNode>;
}>;

function MDXRenderer({ code }: { code: string }) {
 const { default: MdxModuleComponent } = runSync(code, runtime) as {
 default: MdxComponent;
 };

 return <MdxModuleComponent components={{}} />;
}

export default MDXRenderer;
```

Take a good look at the property `components` of the `MdxModuleComponent` component: at the moment, it's empty. However, we can pass a list of components that we want to be able to render by default in our MDX files.

For example, we can augment the default `img` tag with our own. In fact, a common practice is to swap the default `img` tag with Next's own and optimized `Image` component. Let's see how it's done:

```tsx
type ImageLayout = 'fixed' | 'fill' | 'intrinsic' | 'responsive' | undefined;
type StringObject = Record<string, string>;

const NextImage: React.FC<StringObject> = (props: StringObject) => {
 const width = props.width ?? '4';
 const height = props.height ?? '3';

 return (
 <Image
 width={width}
 height={height}
 layout={(props.layout as ImageLayout) ?? 'responsive'}
 className={props.class}
 src={props.src}
 alt={props.alt}
 {...props}
 />
 );
};

const MDXComponents = {
 img: NextImage,
 Image: NextImage,
}

export default MDXComponents;
```

After having defined the object `MDXComponents`, we can edit the `MDXRenderer` component to include the augmentd components listed above:

```tsx
return <MdxModuleComponent components={MDXComponents} />;
```

 At this point, all the images will be rendered using Next.js's incredible `Image` component; furthermore, we can use the component `Image` directly in our MDX files, which allows us to use all the properties available:

 ```md
 <Image
 width={2012}
 height={680}
 alt={'Your Image txt'}
 src={'/assets/images/posts/image.png'}
/>
```

The Makerkit's Next.js Blog Starter template includes the following components: `Image,` `ExternalLink`, and `Video`.

## Final Result

Below is the final result of what we built, and what you will find in [Blog
Starter](https://github.com/makerkit/next-blog-kit):

<Video
 src={'/assets/images/posts/blog-post-demo.mp4'}
/>

## Blog Starter Source Code

The final result of this starter template is a fast, responsive, dark-mode
ready, and functional blog that you can use as the foundation for yours. In
addition, we have already optimized it for Search Engines, so SEO is also taken care of for you.

[You can find the complete source code on GitHub](https://github.com/makerkit/next-blog-kit). It's free and open-source, which means you can use it, fork it, and edit it.

Create an MDX-powered Blog with Next.js

While **SEO is a crucial part of a SaaS marketing strategy**, there isn't a ton of awareness
among most developers and founders about the topic of SEO.

Despite there being an endless stream of articles
about the topic of SEO (Search Engine Optimization) and SEM (Search Engine
Marketing), **much is widely outdated** or primarily focused on
growth-marketing most developers won't be keen on pursuing, such as
link-building.

In the past few years, Search Engines (and especially Google) **have become a
lot pickier about the content they decide to
index and rank**.

Various reasons caused Google to get picky:
vast amounts of content are published every day, and it's becoming
increasingly harder to understand which content has been generated by
machines (such as OpenAI's GPT3).

As a result, **the process of SEO ranking your websites has become longer
and more complex than ever**.

## Technical SEO

To create a proper SEO strategy, you need to consider both
internal and external factors. However, most people are mainly
comfortable with the factors internal to their websites,
typically referred to as **on-page SEO**.

This article focuses primarily on SEO's technical and internal aspects and how **we
at MakerKit have made our SaaS Starter for Next.js SEO-ready**.

### Meta Tags

The most basic but also a fundamental part of optimizing your Next.js website
is to **add the proper meta tags** to your web pages.

While not as crucial as they used to be, using the correct meta tags is
helpful to **help Search Engines understand what
the page is about**. On a separate note from SEO, setting meta tags
improves the readability and visibility of your web pages embedded externally.

#### Title

The most important meta tag is undoubtedly the `title` tag.

You must choose correctly the keywords included in the `title` tag,
and that you repeat these throughout the article to better signal to Search
Engines about what the page is about.

MakerKit comes with three title tags set for you: the page `title` tag, and
the [Open Graph](https://ogp.me/) and Twitter title tags.

```tsx
<title>{title}</title>

<meta
 key="og:title"
 property="og:title"
 content={title}
/>

<meta
 key='twitter:title'
 property='twitter:title'
 content={title}
/>
```

#### Description

Very similarly, we add the relative tags for the page's description.

For example, if you're adding these tags to your blog posts (you should!), you'd
use something similar to the below:

```tsx
<meta
 key='twitter:description'
 property='twitter:description'
 content={post.description}
/>

<meta
 key='og:description'
 property='og:description'
 content={post.description}
/>

<meta
 key='meta:description'
 name='description'
 content={post.description}
/>
```

### Structured Data and Rich Results

Adding Structured Data's tag helps search engines display your website's
content using a rich format.

For example, ever wondered how Google displayed a website's product price in
the search results? Thanks to Structured Data, you can do the same for your
blog posts, FAQ pages, eCommerce products, etc.

Below, we show you how we add Rich Results to our blog posts, which
 facilitates Google's job for displaying your posts in various places
outside the Search Engine, such as Google's Discovery, Google News, mobile
apps, and so on.

```tsx
const structuredDataJson = {
 '@context': 'https://schema.org/',
 '@type': 'Article',
 mainEntityOfPage: {
 '@type': 'WebPage',
 '@id': props.id,
 },
 image: [props.imagePath],
 headline: props.title,
 description: props.excerpt,
 author: {
 '@type': authorType,
 name: props.author.name,
 url: props.author.url,
 },
 datePublished: props.date,
};

<script
 key="ld:json"
 type="application/ld+json"
 dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredDataJson) }}
/>
```

## The most important SEO factors for your Next.js website

### Avoid Duplicate and Useless Content

There are good reasons for **excluding duplicate and useless content** from
your sitemap and generally from the pages you intend Google to index.

As we've said in the beginning, and something we need to keep in mind, is that
**Google is extremely picky**. Google assigns every website a certain
**Crawl Budget**: as the word says, **Google will not crawl every page of our website but only do so up to a certain point**.

If your website is recent, has few links, and has low domain authority, the crawl budget can be pretty low already.

As such, we have to be careful to **only feed to it what we deem is necessary and
important to index**: by adding content to Google that is
low-value risks taking budge from our high-value pages, which Google can ultimately exclude.

The above is not what we want, and therefore we need to think about carefully
what pages of our website do we want Google to index.

#### Pages to exclude from Google's Search

What sort of pages is worth excluding from Google, you ask? Let's see. One
of the most common mistakes is to add **pages that are simply reiterating and
relisting the website's content**, such as tags pages, categories
pages, and so on.

Likely, Google can reach one of the low-value pages using our internal link structure, even if it wasn't listed in our sitemap or blocked by a `robots.txt` file.

The best practice is to exclude pages we do not want Search Engines to index
is to exclude them using a `noindex` meta tag,
such as the below:

```html
<meta name="robots" content="noindex" />
```

By adding the tag above to your page, we can make sure to exclude it from
Search Engines, and most importantly, from precious **Crawl Budget**.

Excluding pages from a sitemap or using a `robots.txt` file cannot stop the spiders from indexing the pages if Google reaches those links from external sources.

### Site Structure

You users benefit from a good site structure to find what they're looking for; similarly, developing a good structure can help Google crawl all your links effortlessly.

The rule of thumb is that if your website is complex for your users to navigate, it's also hard for Google. So your best way forward with your website structure is to do an excellent job for your users to find their way around it.

Google starts crawling your website from the home page and visits all the links it detects. So, assuming the bulk of your content is at `/blog` and your links at `/blog/title,` you should ensure that users and Search engines can get to these pages via the home page.

One important rule to keep in mind is that all **your website's content should be within 5 clicks from the website's home page**; even better if less than that. Accordingly, Google should be able to get to all the content you want to index with a maximum crawl depth of 5 from your home page.

### Sitemap and RSS Feed

Your sitemap lets Google discover your links, but it's mainly essential for huge websites rather than small ones. If your website's structure is good, it's not as crucial as many seem to make it. With that said, there is no downside to using it.

RSS Feeds can help your visitors to consume your content from different sources. While not directly impacting SEO, it can help visitors find your content in more ways and **indirectly help your website get traffic and improve its ranking**.

MakerKit's websites generate automatically a sitemap (excluding the
pages with low-value and internal ones) and RSS feeds for your blog posts.

### Page Loading Speed

The speed at which your pages load is essential due to various reasons.

First, it's an important metric that Google uses to rank your website.
Secondly, pages that load faster use less crawl budget, **allowing Google to
index more of your pages**.

Next.js is not the fastest framework for page loading, but it can do a
pretty good job and is certainly better than 99% of the websites out
there.

**MakerKit can allow for hyper-fast loading thanks to Next.js' SSG** and,
ideally, Vercel's extraordinary edge caching.

If you're using MakerKit, you can be sure you will be running a very
fast-loading website, which helps you **improve your site's SEO and gain
an edge over your competitors**.

### Responsiveness

Similarly to page speed, one of the most critical metrics for Google is how
good your website displayed on mobile devices.

Thankfully, CSS frameworks such as Tailwind CSS make it a reasonably simple job.

## Topic Clusters

From a content marketing perspective, Google has become very interested into
Topics over keywords; indeed, many publications have started building **topic clusters** or **content hubs**.

Explained simply, think of a topic cluster as a **long article summarizing a
list of satellite articles around it**, where each section
introduces each
article; **satellite articles, instead, are a deep dive into the sub-topic**.

This blog, for example, uses a topic cluster for the topic of using
[Firebase Authentication with Next.js](/blog/tutorials/ultimate-guide-authentication-firebase-nextjs).

Because it's a long subject and can be split into different smaller articles,
the above is a decent example of how to write a topic cluster in the software
development space.

**Topic Clusters can help both the main topic page and the satellite articles
rank better by linking to each other**, helping Google understand the close
relationship between the two. From a UX perspective, you also facilitate
readers to dive into the topics if they want to.

## Final Words

SEO is undoubtedly a long and challenging game, and it's getting increasingly complicated.

However, having a solid technical foundation is paramount to **getting your SaaS in
front of potential customers** by placing your
website at the top of Google Search.

While writing the right content for your customers is something we cannot help you with, you can
count on us with the technical aspects of SEO.

**MakerKit's repository is a highly optimized Next.js codebase for ranking high in Google**: all you have to do is get the content to your users and grind for a while; we know, easier said than done, but, eventually, Google will reward you for your efforts.

How to improve your Next.js site SEO ranking

SaaS


The idea of a modern web application can vary greatly - but at MakerKit, **we have a good idea of what it looks like**.

Most SaaS companies use different codebases (or many) for the marketing website, the product application, and the documentation website. The marketing website usually is the top-level domain. The application gets hosted on a sub-domain (such as app.example.com), and the documentation at (docs.example.com)

Historically, there have been good reasons for doing so, such as:
- **Deployment**: separate deployment means **less risk of breaking one or the other** parts of the stack
- **Engineering Time**: having its dedicated marketing website (typically using a CMS such as WordPress) means that your company won't need to involve the engineers in technical aspects, **saving costly engineering man-hours**
- **SPAs**: the growth of client-side SPA (Single-page Applications) frameworks in the past decade made it **impossible to achieve the decent speed and SEO needed for any marketing website**
- **Concerns**: better **separation of concerns**; the marketing website needs to be an SEO beast, the product a fast and secure application
- **Analytics**: separate and **more straightforward analytics tracking**

As you can see from the above points, many would argue that having a separate codebase can be advantageous in many aspects. But it's not black and white, and for many reasons, **we at MakerKit think that a portion of websites would instead benefit from having a single codebase**.

## Technical Progress with SSR and SSG

While not anything new, it's only recently that SSR (Server-side rendering) and SSG (Static-site generation) have been popularized and democratized for Product applications.

Technical progress from frameworks (React, Next.js, Svelte, Vue, Angular Universal, etc.) and PaaS (Vercel, Firebase, etc.) have been outstanding and made it easier than ever to ship a full-stack application.

MakerKit uses Next.js and **makes the most of its incredible hybrid SSR and SSG** to ship dynamic pages for the product Saas, and static, SEO-optimized web pages for the marketing website's content and documentation.

## Branding and Styling

One of the most challenging undertakings for companies using separate codebases is **delivering unique and consistent branding and styling across all the codebases**. This is especially hard when outsourcing the marketing website to external companies or when built by a different internal engineering team.

One of the ways this can be solved is by using internal UI Components systems built with Web Components that you can reuse across various applications and websites. The downside to using Web Components is the added engineering cost of developing and maintaining the code necessary to deliver the needs of all the consumers involved.

A unified codebase means a **more consistent styling/branding**, **more reusable components**, and **fewer costs** associated with outsourcing your technology stack.

## Seamless Navigation and UX

Another issue with having separate codebases is that, in many instances, the navigation between the Marketing website, the SaaS application, and the documentation website happens across different domains and technologies. From a UX perspective, this is far from ideal.

The navigation will be slower, and the UI less consistent. Furthermore, it can be harder to deliver delightful experiences for your user, such as persisting the authentication, ad-hoc and personalized content to your visitors, etc.

A unified codebase means a **more seamless and much faster navigation and User Experience**, the ability to **deliver personalized content** (for example, providing an API key for users navigating through your documentation), and ultimately happier users.

## When not to use a unified codebase?

It's undeniable that, despite the solutions listed above, a unified codebase is not the most viable solution for every company.

It's not something we'd recommend in the following situations:
- **Company Size**: if your marketing speed and team outpace your engineering team, it's clear that having a codebase that needs development work and maintenance can hinder and slow down both your teams. Having a website that the marketing team can maintain is the best decision.
- **Mission-Critical product**: if your SaaS product is mission-critical (for example, a bank), it's clear that you will want to reduce any risk to your clients; in this case, a separate, ring-fenced codebase can be the right solution

## When should you use a unified codebase?

In our opinion, smaller companies, startups, solo developers, and indie hackers would benefit significantly from having a unified codebase. **SaaS starters such as MakerKit** would be the **best way to kick-start products and ship them quickly to your customers**.

These developers are the most likely to build all in-house and are usually more technical and agile.

Does it sound like you? [Contact us](/contact), and let's find out if MakerKit can be the starter for your next SaaS.


Benefits of a single codebase for SaaS Marketing and Product pages

There are tons of resources on the Internet for making a SaaS data model,
but very few use NoSQL or Firebase Firestore.

Firestore is fairly simple to use, but structuring it well requires
analysis from a different point of view compared to other databases:

- **securing the data** using [Firestore Security Rules](/blog/tutorials/in-depth-guide-firestore-security-rules)
- optimizing queries and writes to **save on billing costs** (remember, we pay
for reads/writes and the data transferred)
- due to the querying limitations in Firestore, ensuring that the
**data-model allows our queries**

Developing an architecture without taking into account the points above can
result in **expensive and inefficient decisions**.

We developed MakerKit with simplicity in mind, in a way such that you
can effortlessly adapt the data model we created to your application's domain.

In this post, we explore **the data model we at MakerKit adopted for our
own SaaS boilerplate**. Feel free to comment, take it and extend it as you wish!

### Overview of a simple SaaS data model

Every SaaS has a different data model, but we can identify certain entities
that will be pretty common across most apps.

These are:
- Users/Accounts
- Groups of users, such as organizations/teams/projects
- Invites a member to join a group
- A plan/membership the group subscribed to

The above is the core part of a SaaS and what any SaaS boilerplate should
provide by default. However, getting it right for every use case and scenario is impossible:
hence, MakerKit's model is exhaustive yet straightforward.

## Users and Accounts

Users/Accounts are the primary and most basic entities of most applications.
Thanks to Firebase, the aspect of authenticating accounts is separate from
the users' data, which helps simplify our job.

Whenever a user creates a new account for your application using Firebase
Authentication, this **will be added to the Auth Database, but not to
Firestore**.

So, how can we make sure that a user also has its relative
record in Firestore? There are a couple of ways.

## Creating user records in Firestore
First, what you should know is that the most common way of creating user
records in Firestore is to create a `users` collection.

We can set as the ID of the user record the same ID created by Firebase
Authentication, so we can keep them easily in sync and make sure it's unique
across the collection.

Let's assume the ID created by Firebase is `423631`, then we will create a
record in Firestore at the path: `/users/423631`.

#### Creating a record after sign-up

The simplest way is to create a Firestore record right after sign-up. It's
also not the most straightforward when you take into account that **the
transaction isn't atomic** and any
errors can happen between the sign-up and
the creation of the record, which may result in a poor UX and an out-of-sync DB.

#### Creating a record as part of an Onboarding Wizard

The below is my favorite way, especially for collecting valuable data for and about
your users.

After sign-up, your route guard checks that the user is onboarded or
that the user record exists. You can do this using a token's `custom metadata,`
for example.

If not, redirect to the onboarding wizard,
which will take care of creating a user record and its relative organization.

The above is the approach taken by MakerKit.

## Organizations

Organizations, or groups of users, contain information about their members
and their role within the organization.

In MakerKit, organizations have a property named `members,` which is a map
containing information about the member. **We use an object to simplify writing security rules**.

The following is the interface of an organization:

```tsx
type UserId = string; // this is the ID assigned by Firebase Auth

interface Organization {
 name: string;
 members: Record<UserId, FirestoreOrganizationMembership>;

 timezone?: string;
 logoURL?: string | null;
 subscription?: OrganizationSubscription;
 customerId?: string;
}
```

Let's focus on the organization members for the time being.

Each member has the following interface:

```tsx
interface Member {
 role: MembershipRole;
 user: UserRef;
}
```

As you can see, we stored two properties:
- `role` is an enum that defines the user's role. This is very simple
and doesn't allow for granular permissions, which you may needs
- `user` is a Firestore `reference` to the user record for simplifying access to the user
record. It can also be an ID.

### Querying Organizations and Members

How does the data structure above allow us to fulfill the following use-cases?

- Fetch all the organizations the current user belongs to
- Fetch all the members of the selected organization
- Make sure our security rules can allow us to enforce permissions and allow
for efficient querying

#### Fetching data for a specific organization

The user's current organization is passed in via a cookie when the page gets
rendered using SSR. By selecting the first organization, the cookie
will hold the value of the current organization ID selected for the user.

We will use this cookie to fetch the data of the current organization. To do
so, we can query the path `/organizations/{id}`, using the following hook:

```tsx
function useFetchOrganization(organizationId: string) {
 const firestore = useFirestore();
 const path = `/organizations`;

 const ref = doc(
 firestore,
 path,
 organizationId
 );

 return useFirestoreDocData(ref);
}
```

##### Security Rules to read an Organization

How can we structure our Firestore Security Rules to allow this
query?

We can check if the authed user ID is within the members `map` of the
organization.

The function below allow us to read the current user ID:
```
function userId() {
 return request.auth.uid;
}
```

We can now check if the ID exists in the members' `map`:

```
match /organizations/{organizationId} {
 allow read: if userId() in existingData().members;
}
```

#### Fetching a user's organizations

To list all the organizations a user belongs to, we can check if the user ID
appears to be within the `members` property of the organization.

The hook below will allow us to list the user's organizations:

```tsx
export function useFetchUserOrganizations(userId: string) {
 const firestore = useFirestore();
 const path = `organizations`;

 const organizationsCollection = collection(
 firestore,
 path
 );

 const userPath = `members.${userId}`;
 const operator = '!=';
 const constraint = where(userPath, operator, null);

 const organizationsQuery = query(
 organizationsCollection,
 constraint
 );

 return useFirestoreCollectionData(organizationsQuery);
}
```

### Invites

We store `invites` to join an organization as a collection under each
organization, such as `organizations/1/invites/1`.

Because we may need to access an invitation without knowing the organization
ID, we have two ways to go:

- do not store invitations as a `subcollection`, but as a top-level collection
- create an index using the Firestore Console, which allows us to query deep
collection using the `collectionGroup` method. At MakerKit, we decided to go
with the second way

#### Defining the Invite's data model

Below is the interface of an `Invite`:

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

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

We stored the email of the user invited, which can also be helpful if you
want to restrict the invited user's email to the same one provided by the
inviter.

Additionally, it's essential to store the role assigned by the invitee, the
the time when we consider the invite expired, and a unique code `code`
which we can use to expose and retrieve the invite.

We also add (duplicate) some information about the organization to embed it
into the invitation email. Adding the organization saves one more read each time we query the
invite.

The invite gets sent with a URL similar to the following: `/auth/invite/{code}`. We know which invite we need to process by adding the code to the URL.

After the invite is processed, it gets deleted from the DB.

#### Security Rules for Invites

To securely list the invites to join an organization, we need to
check that the member reading the invites belongs to it:

```
match /organizations/{organizationId} {
 match /invites/{inviteId} {
 allow list: if userIsMemberByOrganizationId(organizationId);
 }
}
```

As you may have noticed above, we can access the organization ID,
which also allows us to query the organization document.

The functions below help us evaluate if, given an organization ID, the
current user belongs to it.

```
function userIsMemberByOrganizationId(organizationId) {
 return userIsMember(
 getOrganization(organizationId)
 );
}

function getOrganization(organization) {
 return get(/databases/$(database)/documents/organizations/$(organization));
}

function userIsMember(organization) {
 let role =
 getUserRole(organization, userId());

 return role >= 0;
}

function getUserRole(organization, userId) {
 let members = organization.data.members;
 let member = members[userId];

 return member != null ? member.role : -1;
}
```

Yes, it looks very similar, but the code below is not Javascript!

## Payments and Subscriptions

Without payments, your SaaS won't get paid. It's needless to say that any
SaaS will eventually need a payment system.

The most popular for startups is probably Stripe, but it's also common
having to integrate different billing
systems for hosting your SaaS on marketplaces: for instance, you may have to
get paid via Apple if you host your app on iOS, or using Shopify Billing if
you allow shops to install the app via the Shopify Marketplace.

In practice, it means we will need a model generic enough to adapt to
multiple payments processors.

### Subscription Model

The model below is added to an `Organization` when creating a plan. We consider it an optional field because
crating a plan may or may not happen.

```tsx
type PaymentProcessor = string;

enum OrganizationPlanStatus {
 AwaitingPayment = 'awaitingPayment',
 Paid = 'paid',
}

interface OrganizationSubscription {
 id: string;
 planId: string; // priceId in Stripe
 processor: PaymentProcessor;

 status: OrganizationPlanStatus;
 currency: string | null;

 interval: string | null;
 intervalCount: number | null;

 createdAt: UnixTimestamp;
 periodStartsAt: UnixTimestamp;
 periodEndsAt: UnixTimestamp;
 trialStartsAt: UnixTimestamp | null;
 trialEndsAt: UnixTimestamp | null;
}
```

The above is the bare minimum amount of data you may want to store; depending on
your needs, you may want to collect more information from the payments
processors' webhooks.

### Security Rules for Subscriptions

A membership is probably not something you want clients able to modify, no
matter which role the user has.

To avoid any issues, we will need to write a security rule that disallows
updating the `subscription` fields of an
organization.

```
match /organizations/{organizationId} {
 allow update: if canUpdateOrganization(organizationId);
}

function canUpdateOrganization(organizationId) {
 let isMember = userIsMemberByOrganizationId(organizationId);
 let noDisallowedFields = fieldsNotInUpdateAction(['members', 'subscription']);

 return isMember && noDisallowedFields;
}
```

As an alternative to this, you can also store subscriptions in their
collection. The only downside to this is that it takes one additional read
to grab the subscriptions' data.

## Final Words

Time to wrap this post. The above is an introduction to how we modeled our
Firestore data structure to support the basics needs of any SaaS application,
while keeping it open for change; as it will inevitably happen, there will
be lots of changes.

I hope you've found this helpful post. Consider [contacting us](/contact) if
you need any help with starting to build your SaaS application with Next.js
and Firebase. We're here to help.

A Data Model for your Firebase SaaS

Next.js is a serverless framework not particularly opinionated when it comes
to databases. Firestore is a common choice among Next.js developers due to
it being performant, scalable, simple, real-time, offline-first, and with a
generous free tier. There's a lot to like.

Firestore is a serverless database that we can use from both the client and
the server. Communicating with Firestore right from the browser
is likely one of its biggest strengths: you no longer need an API to read
and write to your database because it can be accessed directly via the SDK.

The possibility of not having to write an API is a huge time-saver for
developers, and further help to front-end developers who want to write
full-stack applications from scratch.

If you're wondering how we can keep our database secure despite being used
from a client (good question!), you may want to take a look at [this guide for
writing Security Rules for your Firestore database](/blog/tutorials/in-depth-guide-firestore-security-rules).

One of the biggest criticisms of Firestore was the fact that it added a
significant additional size to client-side bundles due to its heavy SDK.
Fortunately, The newly released version 9 of Firebase made massive
improvements in terms of size, which can go even further when using the
Lite version.

In this article, I want to introduce you to Firestore using Next.js at the
time of writing one of the most popular React frameworks, and the framework we built
MakerKit on.

## Setting Up Firestore with Next.js

If you haven't yet configured your application, you may want to get started
using our article about [setting up the Firestore Emulators with Next.js](blog/tutorials/setting-up-firebase-emulators-nextjs).

We use `reactfire`; it's a [Typescript library by Firebase](https://github.com/FirebaseExtended/reactfire) designed to
help developers use Firebase with any React codebase.

### Firestore Provider

We need to initialize Firestore and write a provider to wrap the children that use the Firestore hooks.

The code below is a simplified version of what MakerKit does to initialize a
Firestore instance:

```tsx
import { FirestoreProvider, useFirebaseApp } from 'reactfire';
import { useMemo } from 'react';

import {
 enableIndexedDbPersistence,
 connectFirestoreEmulator,
 initializeFirestore,
} from 'firebase/firestore';

import { isBrowser } from '~/core/generic';

export default function FirebaseFirestoreProvider({
 children,
 useEmulator,
}: React.PropsWithChildren<{ useEmulator?: boolean }>) {
 const firestore = useFirestore();

 // connect to emulator if enabled
 if (useEmulator) {
 const host = getFirestoreHost();
 const port = Number(getFirestorePort());

 try {
 connectFirestoreEmulator(firestore, host, port);
 } catch (e) {
 // this may happen on re-renderings
 }
 }

 const enablePersistence = isBrowser();

 // We enable offline capabilities by caching Firestore in IndexedDB
 // NB: if you don't want to cache results, please remove the next few lines
 if (enablePersistence) {
 enableIndexedDbPersistence(firestore)
 }

 return <FirestoreProvider sdk={firestore}>{children}</FirestoreProvider>;
}

function getFirestoreHost() {
 return process.env.NEXT_PUBLIC_FIREBASE_EMULATOR_HOST ?? 'localhost';
}

function getFirestorePort() {
 return process.env.NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT ?? 8080;
}

function useFirestore() {
 const app = useFirebaseApp();

 return useMemo(() => initializeFirestore(app, {}), [app]);
}
```

If we use the provider above in `_app.tsx`, every page can have access to
Firestore. Adding the Firebase providers may not be the best solution depending on what your application does and how lightweight you want your pages.

### Our first Firestore hook to read a document

The library `Reactfire` helps us with writing queries to our Firestore database
thanks to a list of predefined React hooks.

For example, one common query in SaaS applications is to fetch the
organization/project a user belongs to. In MakerKit, we wrote it similarly
to the code below:

```tsx
import { useFirestore, useFirestoreDocData } from 'reactfire';
import { doc, DocumentReference } from 'firebase/firestore';
import { Organization } from '~/lib/organizations/types/organization';

type Response = Organization & { id: string; };

export function useFetchOrganization(organizationId: string) {
 const firestore = useFirestore();
 const organizationsPath = `/organizations`;

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

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

We imported the `Firestore` instance using the React hook `useFirestore`. By using the function `doc` we can get a reference to a Firestore document at the path specified. In this case, we're fetching a reference of the path
`/organizations/${organizationId}`.

Using the hook `useFirestoreDocData,` we can directly query and retrieve the document's data.

By adding the property `idField`, we're also adding the `id` of the document to the data object. Adding the `id` field is the reason why we merge
the interface of the response with the interface `{ id: string }`.

#### Reading a list of documents using Firestore

To read a list of documents from a Firestore collection, we can use the
`useFirestoreCollectionData` hook.

```tsx
import { useFirestore, useFirestoreCollectionData } from 'reactfire';
import { collection, CollectionReference, where, query } from
'firebase/firestore';

export function useFetchUserOrganizations(userId: string) {
 const firestore = useFirestore();
 const organizationsPath = `organizations`;

 const ref = collection(
 firestore,
 organizationsPath
 ) as CollectionReference<Organization>;

 const userPath = `members.${userId}`;
 const operator = '!=';

 // adding the constraint where. This means: retrieve the organizations
 // where the field members[userId] is not null, eg: it exists
 const constraint = where(userPath, operator, null);
 const organizationsQuery = query(ref, constraint);

 return useFirestoreCollectionData(organizationsQuery);
}
```

### Using document queries in Firestore

Reactfire's hooks are async and therefore re-render based on the
status of the hook, which can be one of the following: `loading`, `error`, or
`success`.

```tsx
const Organization: React.FC<{
 id: string
}> = ({ id }) => {
 const { data: organization, status }
 = useFetchOrganization(id);

 // warn users there was an error
 if (status === 'error') {
 return Ops! Error encountered while loading organization data...
 }

 // show a loading indicator
 if (status === 'loading') {
 return Loading organization data...
 }

 // all good! display organization data
 return <OrganizationDetail organization={organization} />;
}
```

### Using document writes in Firestore

Unlike queries, `Reactfire` does not provide any hook to write to documents.

But we can easily make our own by using `useState` (NB: the following is a
a simplified example, but you'll get the gist).

```tsx
import { useCallback, useState } from "react";

import {
 collection,
 addDoc,
} from 'firebase/firestore';

export function useCreateOrganization() {
 const firestore = useFirestore();
 const [state, setState] = useState();

 const mutation = useCallback(async (organization: Organization) => {
 setState('loading');

 const organizationsPath = `/organizations`;
 const collectionReference =
 collection(firestore, organizationsPath);

 try {
 await addDoc(
 collectionReference,
 organization
 );

 setState('success');
 } catch (e) {
 setState('error');
 }
 }, [firestore]);

 return [
 mutation,
 state,
 ] as [
 typeof mutation,
 typeof state,
 ];
}
```

Using the pattern above, we send the mutation as the first element of the
array, and the state of the mutation as the second element.

The pattern can be used as follows:

```tsx
function OrganizationForm() {
 const [
 createOrganization,
 createOrganizationState
 ] = useCreateOrganization();

 if (createOrganizationState === 'error') {
 return Ops, we couldn't create this organization;
 }

 if (createOrganizationState === 'loading') {
 return Creating your organization. Please Wait....;
 }

 if (createOrganizationState === 'success') {
 return Yay! It worked.;
 }

 return (
 <OrganizationForm onSubmit={createOrganization} />
 );
}
```

You can also use the same patterns for deleting or updating a document.

### Should you use Firestore with your Next.js app?

OK, we've seen that Firestore is solid. But is it the best choice
for your application? Let's talk about this.

Many developers start using Firestore, only to meet certain obstacles along the
way: rigidity of the data model, need for full-text search, highly relational
data structures, and so on.

The above are all signs that Firestore may not have been
the best choice for your application or you as a developer (as you may
prefer relational databases, for example).

Below is my non-exhaustive checklist for choosing (or not) Firestore:

- I don't need a full-text search, OR I am ready to integrate and duplicate
data using a dedicated search engine (Algolia, ElasticSearch, MeilliSearch,
TypeSense, etc.)
- I am OK with duplicating data, and I know how and where to do so
- I don't need to make a large number of reads, or I am able
to load documents progressively (for example, using pagination)
- I need/want real-time updates
- I need/want offline persistence

## Final Words

Firestore is a robust database: easy to start with, secure, and scale.
But, at the same time, it's not always the correct choice, so it's worth remembering
if you're embarking on starting a SaaS using it.

For example, MakerKit uses Firestore extensively: while it's OK for most
applications, it won't be the perfect choice for several use-cases, and
that's fine.

If you need any help or want to know more about how we use Firestore in MakerKit,
[please reach out and let's talk](/contact).

Using Firestore with Next.js

Firebase's Firestore is a database that applications can communicate with
directly from the client-side. As a result, there are many security
considerations that developers need to take into consideration.

To help secure our databases, we can leverage Firestore's Security Rules using a
scripting language ([CEL](https://github.com/google/cel-spec)), which can be
extended using functions, not too differently from Javascript.

For both Cloud Firestore and Cloud Storage, we can use the following syntax:

```
service <<name>> {
 match <<path>> {
 // Allow the request if the following conditions are true.
 allow <<methods>> : if <<condition>>
 }
}
```

For example, for writing Cloud Firestore's root path, we'd be using the
following rules:

```
service cloud.firestore {
 match /databases/{database}/documents {
 // rules here
 }
}
```

### Document Paths
The `path` variable is the path to your Firestore document. If you specify a
path to a document, the ID of the document is defined as a variable:

```
match /organizations/{organizationId} {
 // rules here
}
```

For nested collections, we can insert additional rules within the same scope:

```
match /organizations/{organizationId} {
 match /invites/{inviteId} {

 }
}
```

### Methods
Methods will disallow any read and write by default. Writing and reading
permissions can be written in batch or granularly.

For example, we can write the following conditions:

```
match /organizations/{organizationId} {
 allow read: if canRead();
 allow write: if canWrite();
}
```

In most situations, you want to write granular conditions.

Reading documents can be split as follows:
- `list` - when we want to query a collection of documents
- `get` - when we want to query a single document

Writing a document, instead, can be split in the following ways:
- `create` - when we create a new document
- `update` - when we write to an existing document
- `delete` - when we delete an existing document

```
match /organizations/{organizationId} {
 allow list: if canList();
 allow get: if canGet();
 allow create: if canCreate();
 allow update: if canUpdate();
 allow delete: if canDelete();
}
```

#### Recursive Wildcards

If you want to apply a specific rule recursively to a deep hierarchy, we can
use the following syntax:

```
match /organizations/{organizationId=**} {
 allow read: if condition();
}
```

#### Security Rules are not filters

One important something you should notice is that **Firestore's rules are not
filters**: queries that violate the Security Rules will be rejected.

## Debugging Firestore's Security Rules using the Emulator UI

As you may know, the Firebase Emulators offer the ability to debug your
Firestore database and the queries/writes against it.

If you aren't sure how to run the emulators,
[take a look at our guide for setting up the Firebase Emulators for your
application](/blog/tutorials/setting-up-firebase-emulators-nextjs).

If you have followed the guide above, you should be able to view the
Firestore Emulator UI at
[http://localhost:4000/firestore](http://localhost:4000/firestore).

<Image
 width={2012}
 height={680}
 alt={'Firestore Emulator Debugging UI'}
 src={'/assets/images/posts/firestore-emulator-ui-debugging.png'}
/>

By clicking one of the rows, we can view and analyze the scope of the
request that the Firestore security rules have evaluated.

In certain situations, Firestore can be quirky and not fully documented, so
it can be necessary to inspect what data is available to the security rules.

You can inspect the scope of a Firestore request using the sidebar the
right-hand side after clicking on a request.

<Image
 width={1020}
 height={906}
 alt={'Firestore Emulator Debugging UI Sidebar'}
 src={'/assets/images/posts/firestore-debug-sidebar.png'}
/>

Knowing how to debug our security rules is the first but essential step to
start developing them effectively.

### Evaluating an existing document's data

When the client is executing a `write` (create, update or delete), we can access
the data of the document written passed via the request.

We can use the scoped data `request.resource` to access the document. We should use the `data` property to access the data itself.

In the image below, you can see the scope of a request that was used to
create a new Firestore document:

<Image
 width={1020}
 height={1226}
 alt={'Firestore Emulator Resource data'}
 src={'/assets/images/posts/firestore-debug-resource-data.png'}
/>

The function below is a quick way to access incoming data being written to a
Firestore document:

```
function incomingData() {
 return request.resource.data;
}
```

How to use this function? Let's write a security rule that allows us to create
a document if the document contains a field with a specific value:

```
function canCreateOrganization() {
 return incomingData().id != null;
}

service cloud.firestore {
 match /databases/{database}/documents {
 match /organizations/{organizationId} {
 allow create: if canCreateOrganization();
 }
 }
}
```

In the function above, we're checking that the `id` property of the document
exists.

### Evaluating the incoming document's data

When we're evaluating data of documents that are already in the database, we
need to use the scope `resource.data`:

```
function existingData() {
 return resource.data;
}
```

For example, let's assume the user wants to read the data from an
`organization` document, and that this document contains a map in which each
`key` is the ID of a member.

Explained: if the current user's ID is a key of
the `map` means the member belongs to the organization.

We can use the rule below:

```
match /organizations/{organizationId} {
 allow read: if userId() in existingData().members;
}
```

### Checking that the user is authenticated

The following function allows us to check that the user is authenticated.

Remember, this only means that the user is not anonymous, not that they're
authorized to perform a specific action.

```
function userId() {
 return request.auth.uid;
}

function isSignedIn() {
 return userId() != null;
}
```

### Accessing any path in Firestore

The security rule can allow us to access any path in the database by using
the correct path.

For example, knowing the user's ID (as it is passed via the `request` scope),
we could access the user record using the `get` function and the following
syntax:

```
get(/databases/$(database)/documents/users/$(userId));
```

Notice: **this will cost reads**. Every time our rule reads another document, it
will be billed as an additional read. It's a good practice to write security
rules efficiently, but sometimes it's simply impossible not to do so.

Similarly, we can use the `exists` function to check that a Firestore path
exists:

```
function userExists() {
 return exists(/databases/$(database)/documents/users/$(userId));
}
```

### Retrieve the currently signed-in user record

As we learned above, we can access paths in Firestore if we have the
data to build the paths to retrieve them.

Let's assume your application, like MakerKit, has a collection named `users`
where we store the data belonging to each user. Your Firestore's collection
name can differ, so you may need to update the snippet below.

It can be very helpful to read your current user's record to access data such
as permissions, the organizations they belong to, etc.

The functions below help you access the data regarding the currently
selected user:

```
function getUser(userId) {
 return get(/databases/$(database)/documents/users/$(userId));
}

function getCurrentUser() {
 return getUser(userId());
}
```

### Disallow writing to specific fields

The following function can prevent clients from writing the fields passed
in as strings when creating a new document. This can be useful when you want
to disallow particular writes from clients.

```
// use this function to prevent from writing certain fields
// to the document, such as sensitive data (permissions, etc.)
// create: if fieldsNotInCreateAction(["permissions"]);

function fieldsNotInCreateAction(fields) {
 return !(request.resource.data.keys().hasAll(fields));
}
```

### Disallow updates to specific fields

The following function can prevent clients from updating the fields passed
in as strings:

```
function fieldsNotInUpdateAction(fields) {
 return (fieldsNotInCreateAction(fields) && !(resource.data.keys().hasAll(fields)));
}
```

### Strictly typing writes

Firestore can also allow us to check if the fields sent by the client have
the correct data type.

The following snippet has been taken straight from the Firstore
documentation:

```
allow create: if request.resource.data.tags is list &&
 request.resource.data.tags[0] is string &&
 request.resource.data.product is map &&
 request.resource.data.product.name is string &&
 request.resource.data.product.quantity is int
 }
}
```

Of course, the best way to write long and complex logic is to split it into its
own function:

```
function canCreateReview(review) {
 return review.score is int &&
 review.headline is string &&
 review.content is string &&
 review.author_name is string &&
 review.review_date is timestamp
}

// conditions
allow create: if canCreateReview(request.resource.data);
```

In-depth guide to Firestore Security Rules

Firebase is a cloud backend platform backed by *Google Cloud*. Because it's a cloud environment, it wasn't possible to run it locally for a long time, which was rather complex and inconvenient during the development phase.

In addition, it required an Internet connection, and it was using the production services (even if it was a staging project) for just about anything, eating into the free quota available.

In 2021, Firebase finally finalized the roll-out of the Firebase Suite emulated locally. Installed as an NPM package, the `firebase-tools` library allows us to spin up the emulator for each part of the Firebase Stack:

- Authentication
- Firestore
- RealTime DB
- Hosting
- Cloud Functions
- Cloud Storage
- Cloud PubSub

Furthermore, the Firebase Emulators come with a UI console similar to the actual Firebase Console, although much more limited.

This blog post explains how to set up the Firebase Emulators locally and integrate them into a Next.js application using `reactfire`, the official Firebase package for React.

If you haven't created a Next.js application already, please run the following command:

```bash
npx create-next-app@latest --ts
# or
yarn create next-app --ts
```

## Installing the Firebase Tools package

First, we need to install the `firebase-tools` package for NodeJS. It's the Firebase CLI, which we can use for various tasks:

- switching projects
- install and run the emulators
- deploy the project

To install it in your existing Next.js project, please run the following command in your terminal, which installs the package globally:

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

In addition, please install the following NPM dependencies, handy to work with React and Firebase:

```
npm i -d reactfire firebase
```

## Installing the Firebase Emulators

If you haven't created a Firebase project yet, please run the following command to initialize it:

```
firebase init
```

The command above should return the following output:

<Image src='/assets/images/posts/firebase-init.webp' width='1894' height='936'/>

We recommend choosing the following options:

- Emulators
- Firestore
- Storage

Afterward, you can choose to create a new project, choose an existing one, or neither of them:

<Image src='/assets/images/posts/choose-firebase-project.webp' width='1468'
 height='560'/>

You are not required to create a project unless you use the Storage emulators.

The CLI should output the emulators you want to install: if you're unsure which ones you want, select them all except for Realtime DB and Cloud Functions. As you're using NextJS, we assume you want to use Vercel's API functions:

<Image src='/assets/images/posts/emulators-setup.webp' width='1474'
 height='478'/>

Finally, choose the ports assigned to each emulator and download the emulators. If you choose a port different from the default one, remember to update the Next.js environment variable we define in the next section.

<Image src='/assets/images/posts/ports-setup.webp' width='1472' height='534'/>

#### In case you have not yet created a Firebase project

If you have opted to start without creating a Firebase project, make sure to add a default project to your `.firebaserc` file, even if it is non-existent yet.

Afterward, open `.firebaserc` and paste the following content:

```json
{
 "projects": {
 "default": "ultimate-guide-auth-firebase-next"
 }
}
```

NB: make sure to update the default project when you create one.

#### After the Installation Completes

After this command completes, your project is going to have the following files generated for you:

```bash
- .firebaserc
- firebase.json
- firestore.rules
- firestore.indexes.json
```

NB: if you are running the Storage Emulators, **Firebase does require you to select a project**.

## Adding the Emulators to the Next.js App

We can now configure our Next.js application to use the Emulators instead of the production Firebase services as we have the emulators installed.

We add the emulators' host and ports to the Next.js environment file. Do not use a production `.env` file, but ideally use the local one (for example, `.env` or `.env.local`):

```
NEXT_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
NEXT_PUBLIC_EMULATOR=true
NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT=8080
NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT=9099
NEXT_PUBLIC_FIREBASE_STORAGE_EMULATOR_PORT=9199
```

Because we prefixed the environment variables with `NEXT_PUBLIC_`, Webpack compiles and adds these to the final client-side bundle.

Make sure you choose the exact emulator ports we defined when installing the emulators. If you have not changed the default ports, you're all set!

### Running the Emulators

To run the Firebase Emulators, we suggest creating a new NPM script that runs the following command:

```json
{
 "scripts": {
 "firebase:emulators:start": "firebase emulators:start"
 }
}
```

Assuming everything went well, you should see the output below:

<Image src='/assets/images/posts/running-firebase-emulators.webp' width='1438'
 height='920'/>

Yay! You did it!

#### Importing an Emulator Snapshot

To import a snapshot of the state, we need to add the parameter `import`:

```
firebase emulators:start --import ./firebase-seed
```

You can change the directory path to something else if you want to.

#### Exporting the current Emulator snapshot

To export the current emulator's snapshot, we can add and run the following command:

```json
{
 "scripts": {
 "firebase:emulators:export": "firebase emulators:export ./firebase-seed"
 }
}
```

### Adding the Auth Emulator

To add the `auth` emulator, we can import the *function* `connectAuthEmulator` from the package `firebase/auth`.

Let's create a component that connects to the Auth emulators and makes the SDK available to all its children:

```tsx
import React, { useEffect } from 'react';
import { AuthProvider, useAuth, useFirebaseApp } from 'reactfire';

import {
 initializeAuth,
 indexedDBLocalPersistence,
 connectAuthEmulator,
 inMemoryPersistence,
} from 'firebase/auth';

function getAuthEmulatorHost() {
 // we can access these variables
 // because they are prefixed with "NEXT_PUBLIC_"
 const host = process.env.NEXT_PUBLIC_FIREBASE_EMULATOR_HOST;
 const port = process.env.NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT;

 return ['http://', host, ':', port].join('');
}

function isBrowser() {
 return typeof window !== 'undefined';
}

export default function FirebaseAuthProvider({
 children,
}: React.PropsWithChildren) {
 const app = useFirebaseApp();

 // make sure we're not using IndexedDB when SSR
 // as it is only supported on browser environments
 const persistence = isBrowser()
 ? indexedDBLocalPersistence
 : inMemoryPersistence;

 const sdk = initializeAuth(app, { persistence });

 const shouldConnectEmulator =
 process.env.NEXT_PUBLIC_EMULATOR ==='true';

 if (shouldConnectEmulator) {
 const host = getAuthEmulatorHost();

 connectAuthEmulator(sdk, host);
 }

 return (
 <>
 {children}
 </>
 );
}
```

Whenever we want to use the Firebase Auth SDK within our application, we will need to wrap the page with the component defined above:

```tsx
const PageWithAuth = () => {
 return (
 <FirebaseAuthProvider>
 {
 // your page goes here
 }
 </FirebaseAuthProvider>
 );
};

export default PageWithAuth;
```

Are you looking for an example containing the code above? We got you sorted. [The full source code is available on Github](https://github.com/makerkit/ultimate-firebase-nextjs-authentication-guide): it's an open-source codebase with a fully functioning Authentication system with Firebase and Next.js. Feel free to clone, extend and share it as much as you wish!

Check out our [Ultimate Authentication Guide with Next.js and Firebase](/blog/tutorials/ultimate-guide-authentication-firebase-nextjs) that explains in detail how we built the example above.

Setting Up the Firebase Emulators with Next.js

The Ultimate Authentication Guide with Next.js and Firebase

Changelog

Hey everyone, happy new year!

Here at MakerKit, I started my 2022... making, of course!

More specifically, I improved MakerKit to support payments and
subscriptions using Stripe Checkout!

The last time I had used Stripe, the Checkout product was still unavailable:
it is incredible the amount of work it can save developers.

As incredible as is, Stripe Checkout cannot do everything for you. This is where
MakerKit jumps in.

At MakerKit, I wanted to make it dead-easy to define your Stripe plans,
automatically create a plan selector, and enable your app to
handle the webhooks received by Stripe to update your application's database
accordingly.

With this release, this is all possible.

## Defining the Plans

After having added and configured the plans in
Stripe, we do the same in your application.

We're going to add the plans to the `~/configuration.ts` file, which is
where we store most of our application's config:

```tsx
plans: [
 {
 name: 'Basic',
 description: '3 users and 10 todos',
 price: '$249/year',
 stripePriceId: '<STRIPE_PRICE_ID>',
 },
 {
 name: 'Pro',
 description: 'Unlimited users and todos',
 price: '$999/year',
 stripePriceId: '<STRIPE_PRICE_ID>',
 },
 ]
```

These are already configured to work with the `PlanSelector.tsx` component,
which pulls the plans from the configuration and creates a checkbox with the
data entered.

It's going to look similar to the below:

<Image
 layout={'responsive'}
 width={'2390'}
 height={'1610'}
 src={'/assets/images/posts/stripe-plan-selector.webp'}
/>

You can select a plan by clicking on one and then proceeding by clicking on
"Continue to Checkout".

<Video src={'/assets/images/posts/stripe-plan-selector-video.mp4'} />

## Checkout

Once a plan gets selected, the user can then continue to Stripe Checkout,
which is a page hosted and managed by Stripe.

Once selected and subscribed to plan the user gets redirected back to the
subscription page.

<Video src={'/assets/images/posts/subscribe-to-plan.mp4'} />

## Billing Portal

Once the user has subscribed, they should also be able to perform the
following actions:

- cancel the plan
- update to a new plan
- update payment method
- see previous invoices

Thankfully, the Stripe Portal can handle most of these for us!

The application's side (MakerKit) takes care of handling the webhooks sent
by Stripe when the user takes any of the actions above.

<Video src={'/assets/images/posts/billing-portal.mp4'} />

In the video above, the user accessed the Stripe billing portal, canceled their
plan, and then went back to the subscriptions page.

The user can now pick a plan again or visit their Billing Portal (as we
now can identify the user with a Stripe ID), so that they can manage their
billing settings directly from the customer portal.

## Documentation

Check out <a href="/docs/stripe-configuration">the documentation for setting up
Stripe and MakerKit</a>.

Thank you for reading so far! If you have any questions, please <a
href="/contact">contact us</a>.

Get paid with Stripe

Diary

As a *maker*, I often think about building new projects. Some for
fun, some for profit. As you're reading this post, I'm sure it's easy to relate to this feeling.

Sometimes, I used to think: despite having to code a ton of code in my career,
it never really compounded to anything.

If I did function after function, I'd have a complete codebase.
And by extension, if I had a codebase ready to deploy in a matter of
minutes, **I'd have superpowers**.

## Code is a superpower

Having super-powers: there is no other way to explain the feeling of being
able to deploy a product, with the potential of getting paid, in such a short amount of time.

I built MakerKit with the intention of being able to provide the following
out of the box:

- A landing page seamlessly integrated with the app
- An app that lets users authenticate and pay for the app's value proposition

Of course, MakerKit won't be able to provide you with your value proposition,
but **it can make it plenty easier to get it done**.

Ever dreamt of making a startup in 48 hours? Well, MakerKit can get you from
0 to 0.5 in under half an hour (considering creating a Firebase project and
setting it up).

Can you develop your value proposition's MVP in 47 hours of work? Congratulations! You have a startup.

## Let go of overthinking

I'm not a particularly fast maker: I tend to overthink. Is that button's
color correct? Is that how the menu should look? I'm a developer,
after all.

Overthinking is our favorite sport.

By starting with something that **looks good by default**, I'm able to skip
the overthinking part and get straight to business, focusing on shipping.

## What can you expect from this Saas Starter?

I built MakerKit with two principles:

- the code should be good enough to use as an example for
the code you will be building on top. At the same time, it should not be too
clever: figuring out the whys and hows should not be your concern when
shipping a product

- the starter should be a **solid foundation**, but without making too many
assumptions. Every product will be different and with its own peculiarities.
It's hard for a SaaS to provide an experience that suits most
applications, which is why the data model is light by default

What MakerKit voluntarily leaves out is:

- clever performance improvements: the application is simple, and I prefer
you to see simple code rather than something milliseconds faster

- complex data model: your data model will change heavily as you develop
your application, and if MakerKit stood in your way, it would be a huge
failure for us

For a complete list of the technical details (e.g. the libraries it is built on
top of), please check out the <a href="/docs/technical-details">Technical
Details</a> in the documentation.

## Will MakerKit release new kits?

Yes, most likely! These will come in the future, but it's in the plans, and
we look forward to shipping them.

Blog

Tutorials, Guides and Updates for building your Next.js SaaS