DEV Community: Rodion

Building an Instagram AI Agent with n8n

Rodion — Thu, 13 Mar 2025 14:22:38 +0000

1. About n8n

When I first dove into AI agent development, I was searching for a flexible platform that could handle complex workflows without breaking the bank. That's when n8n caught my attention!

Founded in 2019 by Jan Oberhauser, n8n (pronounced "n-eight-n") emerged as an open-source alternative to established workflow automation tools. Jan's vision was simple yet powerful: create a tool that gives users complete control over their automation while keeping their data private.

With the explosion of LLMs and AI capabilities in recent years, n8n has evolved into a perfect playground for building sophisticated AI agents. The platform now offers native integrations with OpenAI, Anthropic, and other AI providers, making it easier than ever to incorporate intelligence into your workflows.

What makes n8n stand out from Zapier and similar tools?

🔓 Truly open-source: You can self-host n8n and even modify the code to suit your needs
💰 Fair pricing: Their "fair-code" licensing model means affordable options for businesses of all sizes
🛠️ Ultimate flexibility: Complex branching logic and error handling that other platforms struggle with
🔐 Data privacy: Keep sensitive information on your own servers when self-hosting

For my project, these advantages made n8n the clear choice for building an AI agent that could handle Instagram business communications autonomously.

2. My Task: AI Agent to Automate Business Communications in Instagram 🤖

I was eager to build an AI agent and needed a real-life challenge to tackle. The perfect opportunity came through my fiancé Kateryna Baieva's ceramic studio, Osonnya Ceramics, where I help out whenever possible.

2.1. Osonnya Studio and their communication challenges

Like many small creative businesses, Osonnya Studio relies heavily on Instagram for client communications. The majority of their customers reach out through DMs with predictable questions:

Workshop pricing and payment options
Available time slots for upcoming classes
Booking procedures and confirmation

These conversations, while crucial for business, were consuming hours of Kate's time that could be better spent creating or teaching.

2.2. What I wanted to achieve

After analyzing the communication patterns, I defined a clear set of goals for my AI agent:

Handle routine Instagram messages automatically for specific delegated topics
Notify an administrator when conversations require human intervention
Integrate with external data sources (primarily Google Sheets) to access current pricing and availability
Automatically update booking information in Google Sheets when workshops are successfully booked

This narrowed scope gave me a perfect sandbox for experimenting with AI agent development while solving a genuine business problem.

3. Implementation 🛠️

3.1. Architecture

To build an AI communication agent from scratch in Python would require significant development work. But with n8n, the process becomes much more streamlined.

The architecture follows a simple flow:

Customer sends a message via Instagram
System identifies if the topic falls within AI's delegated responsibilities
If yes, the AI agent processes the request using available tools and context
The system generates an appropriate response and sends it back to the customer

All messages are saved to provide better context for future conversations. When a topic falls outside the bot's scope, we notify a human operator (via Telegram in my implementation) and pause automated processing. This architecture allows for seamless handoff between AI and human agents as needed.

3.2. Session Management

Each communication with a customer is defined as a session. A customer can initiate multiple sessions over time, but only one session can be active at any given moment. Think of these as separate conversations about different topics with the same person.

When our system recognizes a message as appropriate for AI handling, we mark the session as "AI" and let our agent manage the entire conversation thread until it ventures outside its zone of responsibility. If the topic shifts beyond the AI's capabilities, we mark the session as "human" and skip automated processing until that session closes.

To implement this session management, I needed a database to track and store conversation states. MongoDB proved ideal for this purpose with its flexible document structure. When a customer message arrives, we first check for an active session with that particular customer. If none exists, we create a new one and classify it as either "human" or "AI" based on message content. All subsequent messages in that conversation thread are stored within the same record to maintain conversation context.

3.3. AI Agent in n8n

The AI Agent node is one of n8n's most powerful building blocks for creating intelligent workflows. This node acts as the brain of your automation, allowing you to connect large language models (like GPT-4 or Claude) directly to your workflow with minimal coding.

What makes the AI Agent node particularly valuable is its ability to maintain conversation context and use tools. You can define custom functions and data sources that your AI can reference when generating responses, such as pulling pricing information from Google Sheets or checking availability in a calendar. The node handles all the complex prompt engineering behind the scenes, letting you focus on what matters - building useful workflows.

For the Osonnya Studio project, I configured the AI Agent with specific instructions about ceramic workshops, pricing structures, and appropriate response styles. By connecting it to our session database and external data sources, the agent can provide accurate, contextual responses that feel natural to customers while maintaining business consistency.

3.4. AI Agent Deployment 🚀

Finally, I needed to find the best place to deploy my Agent to make it live. I could have used n8n cloud for this purpose, but it turned out to be too expensive for a small business like Osonnya Studio—at least 20 euros per month for the starter package.

So I explored alternatives and eventually settled on Railway: for a hobby project of this size, it costs just 5 dollars a month, which fit my budget perfectly.

BTW, to easily deploy my n8n project to Railway I used this nice template.

On top of this base cost, there's the expense of each LLM call to Anthropic's Claude model, which I chose for this project. Since we weren't expecting thousands of messages daily—just tens at most—the API costs remained reasonable. Overall, this deployment strategy provided an excellent balance of performance and cost-effectiveness that I can definitely recommend for similar small-business automation projects! 💯

4. Results and Conclusion 🎉

Building an AI-powered Instagram agent with n8n was an engaging, hands-on exploration into combining low-code automation with modern AI capabilities. Leveraging n8n’s flexibility, seamless LLM integration, and robust session management allowed for rapid development and iterative refinement, ultimately delivering a practical and efficient automation solution tailored specifically to the communication needs of a small creative business.

Mastering CRUD with NextJS

Rodion — Thu, 05 Dec 2024 16:35:32 +0000

In web development, CRUD operations are fundamental building blocks and crucial for managing data. They are ubiquitous in virtually every application, from simple websites to complex enterprise solutions.

NestJS Boilerplate users have already been able to evaluate and use a powerful new tool - CLI, which allows you to automatically create resources and their properties. With this tool, you can make all CRUD operations and add the necessary fields to them without writing a single line of code manually. Meanwhile, as we have repeatedly announced, the BC Boilerplates ecosystem includes a fully compatible Extensive-React-Boilerplate to provide full functionality (which, in principle, can be a completely independent solution). Let’s now explore CRUD operations from the frontend perspective.

In Next.js, a React framework with server-side rendering capabilities, these operations can be efficiently managed with features that enhance performance, SEO, and developer experience. Previously, we published an article about an Effective Way To Start a NextJS Project, and now we want to go further and analyze the details and nuances of working with the APIs in Next.js.

As we know, the acronym CRUD stands for Create, Read, Update, and Delete. This concept represents the fundamental operations that can be performed on any data. Let's consider working with CRUD operations using the example of the administrative panel user, where functionalities like adding, editing, and deleting users are implemented, along with retrieving information about them. The custom React hooks discussed below, handling data processing in React Query, pagination, error management, and more, are already integrated into the Extensive-React-Boilerplate. Naturally, you can leverage this boilerplate directly. In the following sections, we’ll share our insights on implementing these features.

Create Operation

Use Case: Submitting data to create a new resource (e.g., user registration, adding a new product).
Implementation: Collect data from the form, send a POST request to the server, handle the response, and update the UI accordingly.

Let’s observe an example. Making a POST request to the API is incorporated creating a new user. In the snippet below the usePostUserService hook is used to encapsulate this logic. We’ve specified the data structure for creating a new user by defining the request and response types but omit this part here to help you focus. You can see more detailed information or a more complete picture in the repository Extensive-React-Boilerplate because this and all the following code snippets are from there.
So, we’ll create a custom hook usePostUserService that, uses the useFetch hook to send a POST request. It takes user data as input and sends it to the API:

function usePostUserService() {
  const fetch = useFetch();
  return useCallback(
    (data: UserPostRequest, requestConfig?: RequestConfigType) => {
      return fetch(`${API_URL}/v1/users`, {
        method: "POST",
        body: JSON.stringify(data),
        ...requestConfig,
      }).then(wrapperFetchJsonResponse<UserPostResponse>);
    },
    [fetch]
  );
}

The function wrapperFetchJsonResponse will be examined later in this article when we get to "error handling".

Read Operations

Use Case: Fetching and displaying a list of resources or a single resource (e.g., fetching user profiles and product lists).
Implementation: Send a GET request to fetch data, handle loading and error states, and render the data in the UI.

In our example, reading data involves making GET requests to the API to fetch user data. It can include fetching all users with pagination, filters, and sorting or fetching a single user by ID after defining the request (UsersRequest) and response types (UsersResponse).
To fetch all users in the custom useGetUsersService hook, we send a GET request with query parameters for pagination, filters, and sorting:

function useGetUsersService() {
  const fetch = useFetch();

  return useCallback(
    (data: UsersRequest, requestConfig?: RequestConfigType) => {
      const requestUrl = new URL(`${API_URL}/v1/users`);
      requestUrl.searchParams.append("page", data.page.toString());
      requestUrl.searchParams.append("limit", data.limit.toString());
      if (data.filters) {
        requestUrl.searchParams.append("filters", JSON.stringify(data.filters));
      }
      if (data.sort) {
        requestUrl.searchParams.append("sort", JSON.stringify(data.sort));
      }

      return fetch(requestUrl, {
        method: "GET",
        ...requestConfig,
      }).then(wrapperFetchJsonResponse<UsersResponse>);
    },
    [fetch]
  );
}

For fetching a Single User the useGetUserService hook sends a GET request to fetch a user by ID:

function useGetUserService() {
  const fetch = useFetch();
  return useCallback(
    (data: UserRequest, requestConfig?: RequestConfigType) => {
      return fetch(`${API_URL}/v1/users/${data.id}`, {
        method: "GET",
        ...requestConfig,
      }).then(wrapperFetchJsonResponse<UserResponse>);
    },
    [fetch]
  );
}

Update Operation

Use Case: Editing an existing resource (e.g., updating user information, editing a blog post).
Implementation: Collect updated data, send a PUT or PATCH request to the server, handle the response, and update the UI.

Let’s carry out updating an existing user, which involves sending a PATCH request to the API with the updated user data. For this, in the custom usePatchUserService hook, we send a PATCH request with the user ID and updated data after defining the request UserPatchRequest and response types UserPatchResponse:

function usePatchUserService() {
  const fetch = useFetch();
  return useCallback(
    (data: UserPatchRequest, requestConfig?: RequestConfigType) => {
      return fetch(`${API_URL}/v1/users/${data.id}`, {
        method: "PATCH",
        body: JSON.stringify(data.data),
        ...requestConfig,
      }).then(wrapperFetchJsonResponse<UserPatchResponse>);
    },
    [fetch]
  );
}

Note: Using PATCH instead of PUT is more advanced for partial data updates, while PUT is typically used for full resource updates.

Delete Operation

Use Case: Removing a resource (e.g., deleting a user or removing an item from a list).
Implementation: Send a DELETE request to the server, handle the response, and update the UI to reflect the removal.

In our next example, deleting a user involves sending a DELETE request to your API with the user ID. After defining the request (UsersDeleteRequest) and response types (UsersDeleteResponse) in the useDeleteUsersService hook, a DELETE request is transmitted to remove the user by ID.

function useDeleteUsersService() {
  const fetch = useFetch();
  return useCallback(
    (data: UsersDeleteRequest, requestConfig?: RequestConfigType) => {
      return fetch(`${API_URL}/v1/users/${data.id}`, {
        method: "DELETE",
        ...requestConfig,
      }).then(wrapperFetchJsonResponse<UsersDeleteResponse>);
    },
    [fetch]
  );
}

These hooks abstract the complexity of making HTTP requests and handling responses, Using such an approach ensures a clean and maintainable codebase, as the data-fetching logic is encapsulated and reusable across your components.

Retrieving data in Next.js

Ok, we have dealt with examples of processing CRUD operations, and let's take a closer look at the methods of obtaining data offered by Next.js because it, as a framework, adds its functions and optimizations over React. It is clear that Next.js, beyond CSR (Client-Side Rendering), provides advanced features like SSR (Server-Side Rendering), SSG (Static Site Generation), built-in API routes, and hybrid rendering. So, let's discuss commonalities and differences in retrieving data in Next.js and React.

As soon as React apps are purely client-side, so data fetching happens on the client after the initial page load. For dynamic pages that need to fetch data every time a page is loaded, it is more suitable to use SSR, in this case, data is fetched on the server at the request time.
In the case of SSG, which is suitable for static pages where data doesn’t change often, data is fetched at build time. So, the getStaticProps method helps us to fetch data at build time (SSG). If we need pages to be pre-render based on dynamic routes and the data fetched at build time, the getStaticPaths method is allowing to do this. It is used in conjunction with the getStaticProps to generate dynamic routes at build time. It should be noted that starting with Next 14, we can make requests directly in components without these methods, which gives a more "React experience".

Client-Side Data Fetching with useQuery can be used for interactive components that need to fetch data on the client-side, with initial state hydrated from server-side fetched data. For fetching data that changes frequently or for adding client-side interactivity it is useful the useSWR strategy. It’s a React hook for client-side data fetching with caching and revalidation. It allows fetching data on the client side, usually after the initial page load. Nevertheless, it does not fetch data at build time or on the server for SSR, but it can revalidate and fetch new data when required.

To summarize the information about the methods above, we can take a look at the table that provides a comprehensive overview of the different data fetching methods in Next.js, highlighting their respective timings and use cases.

Method	Data Fetching	Timing	Use Case
getStaticPaths	Static Site Generation (SSG)	At build time	Pre-render pages for dynamic routes based on data available at build time.
getStaticProps	Static Site Generation (SSG)	At build time	Pre-render pages with static content at build time. Ideal for content that doesn't change frequently.
getServerSideProps	Server-Side Rendering (SSR)	On each request	Fetch data on the server for each request, providing up-to-date content. Ideal for dynamic content that changes frequently.
useQuery	Client-Side Rendering (CSR)	After the initial page load	Fetch initial data server-side, hydrate, reduce redundant network requests, Background Refetching.
useSWR	Client-Side Rendering (CSR)	After the initial page load	Fetch and revalidate data on the client-side, suitable for frequently changing data.

Using React Query with Next.js

React Query provides hooks for fetching, caching, synchronizing, and updating server-state, making it a great tool for handling data in both React and Next.js applications. Key benefits of its use are:

Efficient data fetching: It handles caching and background data synchronization, reducing redundant network requests.
Automatic refetching: Data can be automatically refetched in the background when it becomes stale, ensuring that the UI always displays the latest information.
Integrated error handling: Built-in support for handling errors and retries, making it easier to manage network failures and server errors.
Optimistic updates: The useMutation hook provides optimistic updates by providing an easy way to handle both the optimistic UI changes and rollback logic if the server request fails.
Ease of integration with Next.js: It can be seamlessly integrated with other Next.js data fetching methods like getStaticProps or getServerSideProps (if needed).
Inspection of query and mutation: the ReactQueryDevtools tool provides the possibility of viewing the status, data, errors, and other details of all active queries and mutations and watching the query states update in real-time as your application runs.

QueryClientProvider

QueryClientProvider is a context provider component that supplies a QueryClient instance to the React component tree. This instance is necessary for using hooks like useQuery. To set it up, it needs to be placed at the root of your component tree and configure global settings for queries and mutations like retry behavior, cache time, and more. After this, it initializes the React Query client and makes it available throughout the application.

// src/app/[language]/layout.tsx
import ReactQueryDevtools from "@/services/react-query/react-query-devtools";
...
export default function RootLayout({
...
}) {
 return (
   <html lang={language} dir={dir(language)}>
     <body>
       <InitColorSchemeScript />
       <QueryClientProvider client={queryClient}>
         <ReactQueryDevtools initialIsOpen={false} />
         …
       </QueryClientProvider>
     </body>
   </html>
 );
}

So, why should it be added to the project? It is beneficial for:

Centralized configuration for all queries and mutations.
Easy to set up and integrate into existing React applications.
Enables features like caching, background refetching, and query invalidation.

React Query Devtools

The other important feature provided by React Query is React Query Devtools - a development tool for inspecting and debugging React Query states. It can be easily added to your application and accessed via a browser extension or as a component like in the example before.
During development, React Query Devtools can be used for inspection of individual queries and mutations, understanding why certain queries are prefetching and monitoring the state of the query cache, and seeing how it evolves over time.

Pagination and Infinite Scrolling

To implement pagination controls or infinite scrolling using features in libraries, useInfiniteQuery is a perfect fit. First, we generate unique keys for caching and retrieving queries in React Query. The by method here creates a unique key based on the sorting and filtering options.

const usersQueryKeys = createQueryKeys(["users"], {
 list: () => ({
   key: [],
   sub: {
     by: ({
       sort,
       filter,
     }: {
       filter: UserFilterType | undefined;
       sort?: UserSortType | undefined;
     }) => ({
       key: [sort, filter],
     }),
   },
 }),
});

To do this, we will use the useInfiniteQuery function from React Query and take the useGetUsersService hook discussed above in the Read Operations section.

export const useUserListQuery = ({
 sort,
 filter,
}: {
 filter?: UserFilterType | undefined;
 sort?: UserSortType | undefined;
} = {}) => {
 const fetch = useGetUsersService();

 const query = useInfiniteQuery({
   queryKey: usersQueryKeys.list().sub.by({ sort, filter }).key,
   initialPageParam: 1,
   queryFn: async ({ pageParam, signal }) => {
     const { status, data } = await fetch(
       {
         page: pageParam,
         limit: 10,
         filters: filter,
         sort: sort ? [sort] : undefined,
       },
       {
         signal,
       }
     );

     if (status === HTTP_CODES_ENUM.OK) {
       return {
         data: data.data,
         nextPage: data.hasNextPage ? pageParam + 1 : undefined,
       };
     }
   },
   getNextPageParam: (lastPage) => {
     return lastPage?.nextPage;
   },
   gcTime: 0,
 });


 return query;
};

QueryFn here retrieves the user data based on the current page, filter, and sort parameters, and the getNextPageParam function determines the next page to fetch based on the response of the last page. When the user scrolls or requests more data, useInfiniteQuery automatically retrieves the next set of data based on the nextPage parameter - this is how infinite scrolling happens. The cache time for the query is set by the gcTime parameter.

Overall, React Query provides a comprehensive solution for managing and debugging server-state in React applications. QueryClientProvider ensures a centralized and consistent configuration for all queries and mutations, while ReactQueryDevtools offers powerful tools for inspecting and understanding query behavior during development.

Error Handling

Implementing CRUD operations always requires proper error handling to ensure user-friendliness and application reliability. Server errors are usually associated with failed processing of a client request, errors in server code, resource overload, infrastructure misconfiguration, or failures in external services. For error handling, Extensive-react-boilerplate suggests using the wrapperFetchJsonResponse function:

async function wrapperFetchJsonResponse<T>(
 response: Response
): Promise<FetchJsonResponse<T>> {
 const status = response.status as FetchJsonResponse<T>["status"];
 return {
   status,
   data: [
     HTTP_CODES_ENUM.NO_CONTENT,
     HTTP_CODES_ENUM.SERVICE_UNAVAILABLE,
     HTTP_CODES_ENUM.INTERNAL_SERVER_ERROR,
   ].includes(status)
     ? undefined
     : await response.json(),
 };
}

Conclusion

In this article, we covered the fundamental CRUD operations, explored data retrieval techniques in NextJS. We delved into using React Query to manage state, also outlining the capabilities of QueryClientProvider and ReactQueryDevtools for debugging and optimizing data retrieval. Additionally, we discussed implementing pagination and infinite scrolling to handle large datasets and addressed error handling to make your applications more resilient and ensure a smooth user experience.

By following the examples and techniques outlined in this article, you should now be well-equipped to handle CRUD operations in your NextJS projects. Alternatively, you can use our Extensive-react-boilerplate template for your project. It has a fully compatible Nestjs-boilerplate backend that implements the ability to work with CRUD operations in minutes, without a single line of code using the CLI, we've covered this in more detail here and here for entity relationships. Keep experimenting, stay updated with best practices, and welcome to try this boilerplate if you find it useful.

Our BC Boilerplates team is always seeking ways to enhance development. We’d love to hear your thoughts on GitHub discussions or in the comments below.

Full credits for this article to Olena Vlasenko and Vlad Shchepotin 🇺🇦

Enhanced CLI Capabilities in NestJS Boilerplate

Rodion — Wed, 06 Nov 2024 10:07:35 +0000

In our previous post about bc boilerplates, we discussed the integration of a CLI for generating resources like controllers, services, and entities. This feature significantly speeds up setup time, especially considering the use of hexagonal architecture, which provides the boilerplate with the flexibility to choose between document-oriented and relational databases (e.g., PostgreSQL with TypeORM) or even both simultaneously.

The introduction of CLI commands has greatly simplified the generation of resources such as controllers, services, and entities. However, since the types available for new properties were limited to strings, numbers, and booleans, we received many requests for establishing relationships One-To-One, One-To-Many, Many-To-One, or Many-To-Many within the hexagonal architecture. Recognizing that modeling relationships between entities is essential in many backend projects, we understood the importance of enhancing the boilerplate CLI to support these features automatically. This not only addresses a widespread need but also aligns with our goal of further reducing setup time, enabling developers to focus on the more complex aspects of their applications.

In a previous post we demonstrated the use of the CLI to create endpoints through examples and wrote about future work on expanding property types. Now we're pleased to announce that this idea has been implemented, and the CLI in the latest version of the NestJS Boilerplate offers significantly more capabilities for creating resources and handling relationships between objects — all without writing a single line of code.

To create a new resource, use the following command, replacing <name> with the desirable entity name (e.g., Publication):

npm run generate:resource:relational -- --name=<name>

This will generate all necessary files (controller, module, service) in a new directory at src/publication.
To add a new field to this entity, use the command:

npm run add:property:to-relational

The interactive mode will now prompt you to specify the entity to which the new field should be added and enter the name of the new property. After that, you will be prompted to select the field type. You can choose from:

Primitive types (string, number, boolean);
Reference to another entity (e.g., relationships like one-to-one, one-to-many);
Duplication of data from another entity (if you want to store a snapshot of data).

If you select a reference to another entity, you’ll then choose from specific relationship types: one-to-one, one-to-many, many-to-many. Following these steps in interactive mode means you don’t have to worry about manual configuration, as it’s handled automatically. For more information on adding properties, you can check the documentation on GitHub.

Let’s go through the step-by-step commands useful for creating a database. Assume we're setting up a blog. We'll go through the CLI commands to show how, in just a few steps, you can build the database structure for a blog without writing any code.

By combining object generation and relationships directly in the CLI, we’ve eliminated the need to manually create template code. The boilerplate now allows you to create a fully functional backend with a basic design and CRUD operations in just minutes, without touching the code. This allows developers to focus on business logic and complex use cases instead of tedious setups.

If you’re already using a previous version of the NestJS Boilerplate, update to the latest version to take advantage of these new features. And if you’re a newcomer, you can also use this boilerplate to create your backend, as it will significantly simplify the development process.

NestJS Boilerplate Update: New Features and Improvements

Rodion — Wed, 14 Aug 2024 15:27:56 +0000

We are excited to share the latest news about our NestJS Boilerplate! Recently, we’ve received many requests from you and the community regarding the following improvements:

Automatic removal of unnecessary functionality during project installation.
The ability to add resources (controllers, services, entities, etc.) through the CLI, as this process was previously quite labor-intensive, especially considering the use of hexagonal architecture.

These improvements have now been implemented😊 So let's take a closer look at how users of the boilerplate can take advantage of them.

New CLI for Generating Resources

We’ve added a CLI that allows you to create resources and their properties automatically. To demonstrate its use, let's look at an example of creating endpoints for a blog. We’ll start the backend using the NestJS Boilerplate (in this example, we’ll use MongoDB). If you have any questions or difficulties with deploying the boilerplate itself, we recommend watching the video below, where all the steps are shown step by step. The video also covers the use of the CLI with a relational database.

After launching the boilerplate, we already have routes for Users, Files, Auth, and Home, which can be seen in Swagger. To generate a new resource, we’ll use the following command:



npm run generate:resource:document -- --name=Publication

After executing the command, a new module with the files publication.controller.ts, publication.module.ts, publication.service.ts, as well as nested folders domain and infrastructure, where entities and other necessary files will be stored, will appear in the src/publication folder.

The newly created resource will also be added to Swagger, where you can see new endpoints for creating, retrieving all publications with pagination, retrieving one by id, updating, and deleting publications.

At the time of generation, the model contains only the fields id, createdAt, and updatedAt.

In our example, each blog publication is expected to have a title and body. To add the "title" field, you need to use the following command:



npm run add:property:to-document

In interactive mode, specify the name of the entity (Entity name) where the property should be added (in our example, it's Publication), enter the Property name, choose the type as string, and add to DTO for further modification. As a result, we see the added property "title" in the dto, domain, schema, and mapper. We then update Swagger and see that the Schema Example Value in both Parameters and Responses now includes the created field {"title": "string"}.

The next field we intend to add is "body". The steps to add it are similar to the previous ones and can be seen in the screenshot.

That's it, a new resource and its properties are created, and you can use it. Try working with the new API routes in Swagger.

We’d like to emphasize once again that nestjs-boilerplate uses a hexagonal architectural approach (ports and adapters), which makes it easy to change the database or other infrastructure without affecting the business logic. You can read more about this in the documentation. Therefore, the commands for working with resources will differ when working with a relational database (e.g., PostgreSQL with TypeORM) or with two types of databases simultaneously.

Thus, we created five CRUD endpoints and added the necessary fields without writing a single line of code manually!

Future Plans and Improvements

We continue to work on improving the bc boilerplates. For example, we are currently working on expanding the data types for fields, as only string, number, and boolean are available at the moment. In the future, users will be able to choose not only between primitive types but also references to other entities with the ability to create one-to-one, one-to-many, and many-to-many relations.

We are always open to dialogue and would love to hear your ideas on how we can enhance our boilerplates. And your stars on GitHub inspire us to keep working!

Experiencing the Migration from Cypress to Playwright

Rodion — Thu, 08 Aug 2024 13:45:49 +0000

In our post about extensive-react-boilerplate updates, we mentioned that we migrated e2e-testing from Cypress to Playwright. Now, let's delve a little deeper into this change.

At the time of writing the automated tests, we had a small amount of functionality to cover and didn't face significant limitations when using Cypress. Yet, we decided to turn our attention to Playwright for several reasons. We wanted to explore the framework created by Microsoft and understand why it is gaining popularity. Additionally, similar to the case when we added MongoDB support, we received requests from the community and colleagues who wanted to start a project based on boilerplate with Playwright tests.

As we began the process of migrating tests, we acknowledged that the volume of tests was insignificant. Therefore, we decided to rewrite the tests manually in order to familiarize ourselves with the new framework in more detail.

First, we start discussing the documentation. We can confidently say that Cypress documentation surpasses Playwright. Cypress documentation is very detailed and contains numerous examples and tutorials. There is also an entire project on GitHub with examples for every action that can be performed on a typical website. Additionally, the Cypress community is larger in comparison to Playwright. Although experienced developers may be content with the information provided in Playwright’s documentation, less experienced developers may find learning Cypress more enjoyable.
Moving on to setting up the configuration file. We don’t find significant differences between the two frameworks. We only need to configure the timeouts and the base URL. We also explored some new capabilities that Playwright offers in this regard, such as:
- setting timeouts for each test, including test and Before/After hooks in config parameters timeout: 2 * 60 * 1000
- support of testing on WebKit, which is based on Apple Safari, whereas Cypress lacks such support
- Playwright also has the ability to start a local development server with your project before running tests, which can be easily implemented using the webServer parameter.

     webServer: {
       command: process.env.CI
         ? "npm run build:e2e && npm run start"
         : "npm run dev",
       url: "http://127.0.0.1:3000",
       reuseExistingServer: !process.env.CI,
     },

Next, we write our first test. The difference in syntax between the two frameworks is notable. Cypress uses chainable syntax and has its own implementation of asynchrony, while Playwright supports the ECMAScript 2015 standard (ES6) and works with convenient async/await construction for asynchronous functions.

Here is a Playwright code sample:

  test("should be successful open page and check data is displayed", async ({
    page,
  }) => {
    await page.getByTestId("profile-menu-item").click();
    await page.getByTestId("user-profile").click();
    await page.waitForURL(/\/profile/);
    await expect(page.getByTestId("user-name")).toHaveText(
      `${firstName} ${lastName}`
    );
    await expect(page.getByTestId("user-email")).toHaveText(email, {
      ignoreCase: true,
    });
    await page.getByTestId("edit-profile").click();
    await page.waitForURL(/\/profile\/edit/);
    await expect(page.getByTestId("first-name").locator("input")).toHaveValue(
      firstName
    );
    await expect(page.getByTestId("last-name").locator("input")).toHaveValue(
      lastName
    );
  });

And here is Cypress:

  it("should be successful open page and check data is displayed", () => {
    cy.getBySel("PersonIcon").click();
    cy.getBySel("user-profile").click();
    cy.location("pathname").should("include", "/profile");
    cy.getBySel("user-name").should("contain.text", firstName + " " + lastName);
    cy.getBySel("user-email").should("contain.text", email);
    cy.getBySel("edit-profile").click();
    cy.location("pathname").should("include", "/profile/edit");
    cy.get('[data-testid="first-name"] input').should("contain.value", firstName);
    cy.get('[data-testid="last-name"] input').should("contain.value", lastName);
  });

When it comes to running the tests, we notice the architectural differences between the frameworks. Cypress executes commands inside the browser, which gives it easy access to important components such as DOM, local storage, and window objects. On the other hand, Playwright uses a client-server architecture and communicates with browsers via a WebSocket connection.
After rewriting all the tests, we ran them all and observed that by default, Playwright runs tests in parallel, providing this feature for free. In contrast, Cypress performs parallelization only for different machines, and it is a paid feature.
Running the same tests in both frameworks revealed that Playwright completed the tests more quickly than Cypress.
We conducted the tests and found that Playwright completed them in 2.7 minutes

…while Cypress took 3.82 minutes, showing a significant time difference in favor of Playwright.

Considering all the above points, one might wonder why we decided to change the framework. Although we did not see significant benefits at that moment, we took into account the future of our project and potential projects that will be built on top of boilerplates from the bcboilerplates ecosystem. From this perspective, Playwright seemed more promising than Cypress due to its parallelization of tests, higher speed, the possibility of testing mobile applications, the ability to use programming languages other than JS and TS, and the backing of a major player like Microsoft.

An effective way to start a NextJS project

Rodion — Thu, 27 Jun 2024 10:57:04 +0000

Choosing a framework for starting a new project can be quite challenging, considering the many frameworks and tools available today. Developers who want to build high-performance and scalable web applications often choose Next.js over others. No wonder, since Next.js is a React framework created by Vercel, offers a comprehensive solution for building server-side rendered (SSR) and static web applications. Here are some of the key advantages:

Server-Side Rendering (SSR) and Static Site Generation (SSG): Next.js supports both SSR and SSG, allowing developers to choose the best rendering method for their needs. SSR improves SEO and page load speed by rendering pages on the server, while SSG can pre-render pages at build time for faster performance.
Built-in Routing: Next.js simplifies routing with its file-based routing system. By organizing your files and folders in the pages directory, you can automatically create corresponding routes, eliminating the need for an external router library.
Optimized Performance: Next.js comes with a host of performance optimizations out of the box, including code splitting, automatic static optimization, and image optimization, ensuring your application runs efficiently.

Starting from scratch can be time-consuming, especially when configuring essential features like authorization and CRUD operations. A proper approach is to use a ready-made boilerplate that includes these settings, allowing you to focus on building features rather than setting up the basics. By applying a ready-to-use Next.js boilerplate, you would get:

Time and Effort Savings: a boilerplate provides a foundation with pre-configured settings, saving you from the hassle of initial setup and configuration.
Best Practices: experienced developers follow industry best practices when building boilerplates, ensuring your project starts on the right foot.
Included Features: built-in features such as authentication, routing, and state management, that a lot of boilerplates include, allowing you to hit the ground running.

Getting Started with a Next.js boilerplate

Let's go step-by-step on how to start your project using a boilerplate.

Choose a Boilerplate: Select the boilerplate that best fits your requirements. In this review, we’ll use the extensive-react-boilerplate as an example, because we use it in our company. In our boilerplate overview article, we've provided the reasons behind its creation and implementation.

Clone the Repository: Clone the boilerplate repository to your local machine using Git.

git clone --depth 1 https://github.com/brocoders/extensive-react-boilerplate.git my-app

Install Dependencies: Navigate to the project directory and install the necessary dependencies.

cd my-app
npm install

Configure Environment Variables: Set up your environment variables for authentication and other configurations. To do this, copy the example environment file.

cp example.env.local .env.local

Run the Development Server: Start the development server to see your project in action.

npm run dev

Customize Your Project: With the boilerplate set up, you can now start building your features. The boilerplate provides a structure and essential configurations, allowing you to focus on the core functionality of your application.

Conclusion

Starting a project with Next.js offers numerous advantages, from server-side rendering to built-in routing and performance optimizations. Using a ready-made boilerplate can further accelerate your development process by providing pre-configured settings and best practices. By leveraging these tools, you can focus on what matters most: building a high-quality, scalable web application. In the next article, we'll delve into mastering CRUD operations in Next.js, providing you with the tools and knowledge to manage data effectively in your applications.

How We Went from 46 to 99 Performance Score to Improve Our Website Speed

Rodion — Wed, 19 Jun 2024 09:31:22 +0000

In 2018, Google announced that page speed from then on would be a ranking factor for both desktop and mobile search results. But it's not only ranking that is influenced by page speed. According to research, a 3-second page loading time means a 13% bounce rate, so the page speed doesn't only impact the search results but the user experience as well.

So what do you do if your website is slow? Fixing website performance is not easy, which is why many companies do only minor optimizations just to keep their websites somewhere in search results. Our Brocoders's website ended up in the same situation. But unlike other businesses out there, we decided to eliminate every performance issue we had.

Keep reading to find out how we went from a 43 performance score to 99 and why (apart from being very proud of ourselves) having one of the fastest websites in the industry is worth the effort.

Our starting point: what was the problem and why we had to solve it

The old Brocoders's site, live since 2011, served us well and we loved it very much as it was our first child. However, after several years we felt it was time for a change. That’s why in 2020 we decided to invest in a new website for our company.

This is what the old Brocoders's website looked like. Forever in our hearts.

By rebuilding our website, we aimed to achieve three major goals:

Increase conversion rates through faster page loads, better UX, and higher-quality content.
Improve SEO and get better visibility in search engines.
Improve our brand image by introducing new portfolio projects and client reviews.

These goals guided us in deciding what features we had to add. Here is the essential functionality we came up with to achieve our goals:

New highly flexible web pages with a great look and feel to demonstrate our services, industries, technologies, and case studies.
Updated blog post pages with a search option, tags, and categories.
'Get in touch' and other forms to easily contact us.
Numerous third-party integrations: Google Tag Manager, Cookiebot, and Hubspot to name a few.

All in all, our goal was to build a secure static website. That’s why we chose GatsbyJS, a React framework that perfectly aligns with this goal.

Why Gatsby, you ask? The secret sauce behind @GatsbyJS is its ability to transform web development into a seamless and fast experience, weaving together pre-built HTML, CSS, and JavaScript during compilation. Developed with React, GatsbyJS also allowed us to create our own templates and components, using extensions from the React ecosystem.

Another thing we had to care about for the new website was the API backend. Our choice fell on @Strapi, an open-source content management system. Not only did it allow us to customize our data schemas and extend API functionality to manage different types of content like text, images, and videos, but also save us a great amount of time and money – with its user-friendly admin panel and additional features we didn't have to build it all from scratch.

Finally, for server requests, we used GraphQL. Perfect for collaboration with GatsbyJS, it lets us define the query structure and specify only the necessary fields and relationships, avoiding excessive data, which in turn leads to faster page loading time.

The combination of technologies allowed us to achieve the perfect website stability and security

Once done, the new website was there, gratifying us with higher rankings and renewed design. At first…But then, things gradually went downhill. After adding new pages, making numerous edits, and integrating third-party software, the codebase had become so heavy that our performance scores on Google's Lighthouse, a tool that analyzes web page speed, dropped drastically.

Lighthouse scores that our website had before we started working on improvements

With such a low score, Google wouldn’t rank us high. And even if it would, users wouldn’t wait until it loads.

Ericsson Research found that the level of stress from waiting for pages to load on mobile can be compared to watching a horror movie. When talking about performance, every second counts. We knew the pain, so we started improving our site’s performance right away.

Improving website performance step by step

To achieve a significant performance boost, we analyzed the main website issues and started working on solving each of them. Here’s how we overcame the main challenges.

1. Accelerating network connections establishment by 2X

GMetrics, a tool that shows website loading behavior, helped us identify resources from external domains that caused the longest connection times.

In purple, you see the time it took for a Domain Name Server to receive the request for a domain name's IP address, and in light green, you see server connection time. They took too long, so we accelerated them by reducing server connection time.

To speed up our website, we made a few technical optimizations. First, we used Resource Hints, a method involving HTML <link> attributes. These hints help the browser proactively establish connections before making requests for resources from the server. For resources from external domains, we incorporated DNS-prefetch and pre-connect hints that instruct the browser in advance to set up connections with specified domains. Consequently, when the browser needs resources from external domains, they load quicker since the initial setup is already done.

For internal files like scripts and stylesheets, we applied "preloading" and "prefetch" hints. These hints ensure that when users move between pages on our site, the needed resources are loaded from their local cache, avoiding the need to fetch them from a distant server and making the process faster.

These optimizations helped us shorten *Largest Contentful Paint from 2,9 seconds to 0,8 and *First Contentful Paint from 1 second to 0,6, allowing the browser to load resources as quickly as possible.

*LCP, a Core Web Vitals metric that measures the time from when the user starts loading the page until the largest image appears in the viewport.

*FCP, the time from when the user first accesses the page to when the content is rendered on the screen.

2. Achieving better font loading with fast text rendering

On our website, we use both custom and open-source fonts. We host the open-source font "Manrope" from Google using the Fontsource collection as this method is the fastest way to access a font.

However, there was a delay in loading the font package, even though the text was already retrieved from the HTML file. To avoid this disruption between text and font loading, our initial strategy was to show an invisible fallback font until our intended web font fully loads. It worked, but such an approach made the LCP metric longer, which is why we decided to change the strategy and opt for fast text rendering.

Here is how it works. First, the browser finds an available font within the declared font family and uses it to render the text. Then, after loading the original font, the browser seamlessly swaps the first font with the required one. It’s the fastest way to load fonts but this approach poses risks of unexpected text shifts because of changes in font size. To address layout shifts and improve the Cumulative Layout Shift (CLS, a metric that measures how much the elements on a webpage move around unexpectedly as it loads), we applied CSS Fonts Module Level 5, a set of specifications that includes descriptors like size-adjust, descent-override, and line-gap-override, that helped us avoid shifts in page content.

CSS Fonts Module Level 5 worked perfectly and now fonts change without any layout shift

As a result, three metrics – First Contentful Paint, Largest Contentful Paint, and Cumulative Layout Shift improved. In particular, CLS was reduced from 0,143 to 0 seconds.

3. Improving the loading of images and video

Another performance issue we had was enormous network payloads. Site testing revealed that we had to optimize the loading of images and videos, reducing their size without losing the quality.

Yellow Lab Tools testing showed us that among all types of files videos and images overweighted our website the most

On the website, we use two types of images – vector images (in Scalable Vector Graphics (SVG) format) and raster images (in PNG and JPG formats). For each type we applied different optimization approaches.

3.1 Optimization of vector images

Vector images are usually lightweight but the problem was that each image required a new HTTP request to load, which slowed down the performance. To address this, we decided to adopt inline SVG, a method that allows embedding the image directly into HTML. To achieve this, we adopted the 'gatsby-plugin-react-svg', a Gatsby framework plugin that allowed us to abstract the process.

3.2 Optimization of raster images

To accelerate the loading of PNG and JPG images, we converted them to the modern .webP format that ensures excellent compression with minimal quality loss. Similarly, we converted videos from .mp4 to .webM, ensuring more efficient compression and quality. Both .webP and .webM became our primary formats, but the old browser versions do not support them. To exclude this problem, we also left fallbacks to .png, .jpg, and .mp4 formats for browsers that don’t support .webP and .webM.

Next up, we had to optimize image display for different devices. Mobile, tablets, laptops, or 4K monitors require images of different dimensions, so uploading the same image for both phones and 4K monitors only made our website longer to load. That’s why we employed adaptive graphics. We included different image options in the code, letting the browser pick the best one based on things like window size, screen resolution, network speed, and other factors. Using packages like 'gatsby-background-image' and 'gatsby-image', we created various image variants for different devices. In the Network tab screenshot below, you see the “Toggle device toolbar” where we switched between page display modes.

This is where we toggled a device toolbar, optimizing image loading for different devices

Here you can see the same file with reduced size optimized for different devices

3.3 Lazy loading for behind-the-scenes images

Finally, we leveraged lazy loading with a blurred image effect to ensure images load only when the user sees them, optimizing the experience for users with limited data plans or slower internet connections.

This is how the lazy loading of images works

The results were worth all the sweat – we significantly reduced the weight of the images on the website without sacrificing quality.

After improvements, Yellow Lab Tools shows that the video – not surprisingly – still takes a larger portion of the page's weight but the weight of images has significantly decreased (purple section)

The optimizations greatly improved user experience and metrics like CLS and LCP. Thanks to using image optimization plugins exclusively from the Gatsby ecosystem, we made it easier to optimize performance.

4. Optimizing caching

We have to confess that caching, a technique where the web server retains a copy of the web page, was initially overlooked during the website development. It was truly a missed opportunity because effective caching would help us speed up the website and reduce server load. We decided to catch up with cache optimization but faced several specific challenges.

Our goal was to fasten the loading of resources by keeping them saved for future visits instead of downloading them every time. To achieve this, we employed the 'cache-control' attribute in the HTTP header and set the time for how long the file should stay in the cache. But then another issue appeared. When we made updates to the website content or design, the changes wouldn't show up immediately because the browser kept using the old saved copy.

How did we solve it? We added a hash to the file names, which updates with every file edit. This way, we could keep files in the cache for a long time but still make changes easily. As a result, the First Contentful Paint (FCP) metric went from high to medium.

Now, we're considering another type of caching called browser caching. Unlike server caching, which requires a constant server connection and uses bandwidth to load the response, browser caching allows users to access the webpage without a network connection. But it also has its limitations – if the user's device is running out of storage space, the browser might delete older stuff to make room for new things.

For you to get a better idea, here is a comparison of how server-side caching and client-side caching work

5. Eliminating large JavaScript bundles

Bundles are simply collections of files, usually JavaScript, CSS, and other assets, grouped in a single file for more efficient delivery. As our website grew in complexity, the size of our bundles continued to expand, overweighting the website. It was high time to identify problem areas and get rid of them.

There are some handy tools for identifying and addressing problematic bundles. One of them, Bundlephobia, gives insights into how much an NPM package contributes to bundle size, helping avoid too large collections of files. Import Cost, a VSCode Extension, calculates the 'cost' of imported packages, helping to make informed decisions. As part of our optimization strategy, we've swapped out hefty JS libraries, such as replacing the widely-used 'classnames' package with the more efficient 'clsx', a faster and smaller drop-in replacement tailored to our website needs.

Then, with the Webpack Bundle Analyzer plugin, we discovered problematic areas in bundles.

Bundle Analyzer highlighted our biggest bundles – client-location and map-with-flashing-dots

To break down these piles of files, we split big bundles into smaller parts using code-splitting and lazy-loading. Webpack's built-in code-splitting feature allowed us to transform the import command into a function that points to a file path instead of directly importing files. This creates a promise, which is like a commitment that the file will be loaded. When a similar structure appears in the code, this promise is fulfilled, and the file is uploaded.

For non-critical view, HTML, and JS, we used dynamic imports which let us reduce the initial size of the webpage. Dynamic here means that the website decides whether to load additional files based on specific conditions, making sure it doesn't disrupt the user experience.

Here’s the result of our optimizations: a streamlined loading with no isolated large bundles

After splitting large bundles into smaller parts, we successfully lightened the page and eliminated all large file collections.

6. Minimizing HTML and CSS with code compression

Code compression was a game-changer for us. By shrinking the code and removing unnecessary white spaces, we achieved smaller file sizes, lightning-fast downloads, and reduced bandwidth consumption. Now our server delivers website files in a gzip format, making it faster and significantly improving important metrics like FCP and FID (First Input Delay, a metric that quantifies the delay between the first click and the browser's response) from low to medium performance levels.

7. Code quality and memory leaks

Finally, we reviewed our code and discovered some sneaky memory leaks. The problem was that objects were still in memory even when they were no longer needed, resulting in a cluttered space.

To fix this, we applied two methods. If the event listener (a mechanism that awaits specific occurrences, such as user interactions or system events, and responds accordingly) is only needed once, we use the {only: true} parameter. It ensures that after the listener is triggered, it's automatically removed, preventing any memory issues. As for the second method, we made sure to explicitly remove event listeners using the removeEventListener() function. We did this before removing the element or when the listeners were no longer needed. This ensured a clean disconnection between elements and functions, avoiding memory leaks.

Another thing related to addEventListener is using the { passive: true } parameter. We adopted it for scrolling, avoiding interface hiccups, and ensuring a smoother user experience.



useEffect(() => {

setScrolled(document.documentElement.scrollTop > 50);

window.addEventListener('scroll', handleScroll, { passive: true });

return () => {

document.body.style.overflowY = 'scroll';

window.removeEventListener('scroll', handleScroll);

};

}, []);

Before and after: how performance boost impacted our website

Truth be told, our starting point was far from good – a website wrestling with sluggish load times and an overloaded server that drastically impacted the user experience. But armed with insights and optimization techniques, we did our best and received impressive results. Were we happy with them? Absolutely.

PageSpeed Insight handed us a shiny report card, showcasing significant improvements

The testing of the 28-day performance showed impressive results – all metrics were improved several times compared with the starting point

All these improvements wouldn’t be possible without hours and days of dedicated work, but there was something else that greatly contributed to our success – the right tools. Some instruments saved us a lot of time during the work and we can’t help but mention them.

Tools for performance optimization: PageSpeed Insights and Lighthouse

In performance analysis and improvement, two Google instruments stand out: PageSpeed Insights and Lighthouse. These tools analyze various aspects of a web page to provide insights into its speed, user experience, and overall performance. Here are the metrics that they both consider:

Largest Contentful Paint (LCP) - measures the time it takes for the largest content element (such as an image or text block) in the viewport to become visible to the user.
First Contentful Paint (FCP) - measures the time it takes for the browser to render the first piece of content, such as text or an image.
First Input Delay (FID) - measures the delay between a user's first interaction (such as clicking a button) and the browser's response to that interaction.
Cumulative Layout Shift (CLS) - measures the sum of all individual layout shift scores that occur during the page's lifespan. A layout shift occurs when visible elements on a page move unexpectedly.
Interaction to Next Paint (INP) - measures the time it takes for the browser to respond to user interactions (such as clicks or taps) by updating the visual content on the page.
Time to First Byte (TTFB) - measures the time it takes for the browser to receive the first byte of data from the server after a request is made.
Total Blocking Time (TBT) - measures the total amount of time during which the main thread of the browser is blocked and unable to respond to user input.
TTI (Time To Interactive) - measures the time it takes for a page to become fully interactive, meaning all necessary resources are loaded, and the page responds promptly to user input.
FID (First Input Delay) - measures the delay between a user's first interaction and the browser's response to that interaction.

You can use either of these tools to get insights into your website's performance. Lighthouse is more flexible and provides more detailed information. PageSpeed Insights, on the other hand, focuses on monitoring the performance of individual pages.

The most commonly used, these two aren’t the only tools we recommend. Here are a couple of resources you’ll find useful in your performance optimization journey.

Bonus tools for a deeper dive

GTMetrix: a powerhouse that not only audits pages but also visualizes loading in a digestible format, making performance improvements tangible.

Yellow Lab Tools: an insightful dashboard that classifies and evaluates dozens of metrics. It not only pinpoints issues but also provides detailed recommendations for optimization.

These tools have been our guiding lights, helping us enhance performance and offer a superior user experience. Keep them in mind when you start to improve your website performance.

Bottom line

If your business depends on the website, you can’t sleep on its performance. This factor can move you to the top of the Google results or, on the contrary, make your users leave for faster websites that give them a better experience. To help you avoid this scenario, we shared the story of our website transformation.

Our performance odyssey isn't over as there will always be room for improvement. Lately, we've been noticing that GatsbyJS is experiencing not the best times and we are deliberating about switching to NextJS. But this is the subject of the other article.

But like there are no identical businesses, there is no single instruction on how to improve your site performance. Every case is unique and you need to address the challenges that pose the issue in your case. Not an easy task to do, but we can help. If you want to give your website a performance boost, drop us a note, and we’ll see what we can do for you.
`

BC Boilerplates: Recent Updates

Rodion — Wed, 12 Jun 2024 10:25:39 +0000

Over the past few months, BC Boilerplates have undergone several changes, covering important aspects from testing to automating installation processes.
Below, we are pleased to present updates that will facilitate the development process of applications built on boilerplates from the BC Boilerplates ecosystem.

Extensive-react-boilerplate received the following updates:

From now on, e2e test development will ensure their stability through the Playwright tool (previously Cypress was used), which has excellent support from Microsoft. The ability to run parallel tests is provided, reducing execution time (in Cypress, this was available for an additional fee).
Sign-Up Disablement: For convenient management of the registration mode offered by the Boilerplate, it is now sufficient to specify the exact value of the env variable in the config file (true/false).
```
{IS_SIGN_UP_ENABLED && (
<Button
onClick={handleCloseNavMenu}
sx={{ my: 2, color: "white", display: "block" }}
component={Link}
href="/sign-up"
>
{t("common:navigation.signUp")}
</Button>
)}
```
Availability of a privacy policy page with contact information for any questions.

New features of nestjs-boilerplate are related to the running tests in watchAll mode and CLI usability:

Tests. The separate 'container' which by default runs in watchAll mode was improved. Compared to the previous approach, it used to be necessary to run each time a container with e2e tests from the very beginning, but now it is running continuously in standby mode. If you change any test, you can run exactly the ones you need at that moment.
CLI has been added to assist the installation process of your project. Now you have the option to choose a database for the backend (Postgres or Mongo), whereas previously, more than 60 files had to be manually changed. You can remove unnecessary features for your development with just a few clicks.
CLI for resource generation. Automatic generation of domains, endpoints, repository, Swagger documentation, swagger documentation, and the necessary entity, providing resources and interfaces for the Extensive-react-boilerplate from the backend side.

Some changes apply simultaneously to extensive-react-boilerplate and nestjs-boilerplate:

A section for editing the email address has been added to the user profile. It is important to note that the user must confirm their request to change their email address by responding to the confirmation sent to the new email address provided.
A common CLI tool for automating tasks related to release-it package versions and publication has been added. It handles versioning of the existing code and generates an automatic changelog based on commits, using the specification rules for recording changes in conventional commits (refer to CHANGELOG.md).

The proposed updates will significantly increase the convenience and efficiency of development and will become an even more powerful tool for creating and supporting modern SaaS solutions. We're always looking for ways to improve your development experience. Please, let us know what you think and share your feedback via https://bcboilerplates.com/#contacts in the way you prefer.

Top 12+ Battle-Tested React Boilerplates for 2024

Rodion — Mon, 29 Apr 2024 18:52:13 +0000

The matter of choosing the most popular web framework to start

Recently, React has become one of the most beloved interface frameworks of all time. According to a 2023 survey, React.js is used by 40.58% of developers worldwide, making it one of the most popular web frameworks. Developed by Facebook, React.js is also relied upon by other tech giants such as PayPal, Uber, Instagram, and Airbnb for their user interfaces. Undoubtedly, its widespread adoption and strong community support have been facilitated by React's combination of productivity, component-based architecture, and declarative syntax. This means developers are building projects on React more than ever before.

The React library is non-opinionated by design, meaning that "out of the box", it doesn't include practically any additional features beyond the core functionality of defining and managing components. Therefore, it's easy to mess up without knowing best practices for prop passing, decomposing, structuring React application files, scaling the application as a whole, and other nuances. These pitfalls can be avoided by using a boilerplate that contains built-in functions and configurations, providing a comprehensive foundation with core tools and libraries, optimizing the development process, and allowing developers to focus on building their application logic rather than dealing with initial setup and configuration. In other words, it serves as a standardized starting point for initiating application development. Searching for 'react-boilerplate' on GitHub yields 44.8k repositories at the moment. The question arises regarding which template to choose for development, one that fits your application and is good for scalability and future maintenance.

Types of React boilerplates

In the past, the most commonly used way for starting React projects was create-react-app (CRA) - a popular and officially supported boilerplate by Facebook. However, the new React documentation, published on March 16, 2023, no longer recommends CRA as the best solution for creating React programs. Let's consider the alternatives, compare them, and decide on the best way to start a project.
By delving into the various aspects of React boilerplates, let's consider the criteria by which they can be divided:

Libs and Configs:

Minimalistic Boilerplates: provide basic configurations for a React project, including basic setups (such as Webpack, Babel, and ESLint). They assume that developers will add certain libraries and features as needed. The majority of boilerplates fall into this category.
Feature-Rich Boilerplates: come with pre-configured additional libraries and tools. These may include state management (e.g., Redux), routing (React Router), and testing, also may include basic UI components and pages, further speeding up development by providing common UI elements and layouts.

Authentication and Registration:

Boilerplates with Auth and Registration: include components for login, signup, and user sessions.
Boilerplates without Auth: leave authentication implementation to developers.

Full-Stack vs. Frontend-Only:

Full-Stack Boilerplates: provide a comprehensive solution for building web applications, covering both the frontend (React) and backend.
Frontend-Only Boilerplates: focus solely on the React interface. Developers need to integrate them with the desired server.

UI Components Libraries:

Boilerplates with UI Components: include a full set of UI components that adhere to consistent design patterns (e.g., buttons, forms, modals).
Boilerplates without UI Components: leave the development of components entirely to the developer using the boilerplate.

Paid vs. Free:

Free/Open-Source Boilerplates: freely available, community-supported, and often well-maintained.
Paid Boilerplates: some commercial templates offer additional features, premium support, or extended functionality.

Based on the above classification, it can be said that the most popular React boilerplates, such as Vite, Create React App (CRA), Create Next App, Razzle, include only the basic libraries and configurations necessary to start developing with React (Minimalistic Boilerplates).

React template selection criteria

Deciding which boilerplate to use during development can be quite challenging because it's not just about creating an application but also about scaling and maintaining it afterward. So how to choose the appropriate solution from the given variety of existing boilerplates, and how do you choose them in general? Here are the key points we suggest paying attention to when choosing a boilerplate to start your project:

Support and Maintenance Options: Is the project regularly updated?
Performance Scores
Code Quality (structure cleanliness, scalability, code organization)
Production Readiness: Is the project ready for production use right now?
Availability of features such as authentication, routing, internationalization, form handling, testing, basic pages, and UI components - the list could go on, you just need to determine which ones are needed for your project implementation and look for them in the boilerplate.

React Project Scaffolding Tools

The initial step in developing React applications typically involves choosing among Vite, Create React App, Create Next App, or Razzle as the foundation. They provide framework-like functionality, particularly regarding setting up the initial project structure, configuring build tools, and providing development servers.

Vite focuses on providing an extremely fast development server and workflow speed in web development. It uses its own ES module imports during development, speeding up the startup time.

Create React App (CRA) abstracts away the complexity of configuring Webpack, Babel, and other build tools, allowing developers to focus on writing React code. It includes features such as hot module reloading for efficient development.

Next.js is a React framework for building server-rendered and statically generated web applications. It configures Next.js projects with sensible defaults, including features like server-side rendering (SSR), file-based routing, and API routes.

Razzle is a build tool created by Airbnb, which also simplifies server-side rendering. It abstracts away the complexity of configuring server-side rendering settings and allows developers to easily create versatile JavaScript applications. Razzle supports features like code splitting, CSS-in-JS, and hot module replacement, making it suitable for building React applications that require server-side rendering.

The above-mentioned build tools are often referred to as React boilerplates. Since they only abstract the complexities of setup away, provide basic configurations, and optimize build workflows, they are not very functional and do not contain additional features themselves. Therefore, according to the classification provided above, we classify them as Minimal Boilerplates. Essentially, they often serve as boilerplate templates, that is, they are great tools for creating more feature-rich React boilerplates.

Table of selected Boilerplates

Next, we will consider React boilerplates that do not charge a license fee and/or offer their features for money and also take into account the date of the last update (not more than six months ago). Based on this, we have taken into consideration 12 boilerplates*:

	Stars	Contributors	Last Commit Date	Open Issues	About
extensive-react-boilerplate	341	8 contributors, supported and used by Brocoders	23-11-2024	2	Extensive React Boilerplate: ✔️NextJS ✔️Auth ✔️I18N ✔️MUI ✔️Forms demo
React Starter Kit	22.5k	5 contributors	15-02-2024	2	The web's popular Jamstack front-end template for building web applications with React demo
react-redux-saga-boilerplate	606	6 contributors	06-02-2024	-	Starter kit with react-router, react-helmet, redux, redux-saga and styled-components demo
Next-js-Boilerplate	7k	24 contributors	05-04-2024	1	Boilerplate and Starter for Next.js 14+ with App Router/Page Router, Tailwind CSS 3.4, TypeScript demo
landy-react-template	1.1k	1 contributor	06-04-2024	4	Landy is an open-source React landing page template designed for developers and startups demo
core	307	6 contributors	27-03-2024	6	Boilerplate for React/Typescript, built based on Vite
nextjs-boilerplate	127	1 contributor	18-03-2024	-	Next.js 14+ boilerplate with typescript, husky, lint-staged, eslint, prettier, jest, react-testing-library, storybook, ghaction and plop demo
react-pwa	501	6 contributors	09-01-2024	8	Starter kit for modern web applications demo
Vitamin	485	5 contributors	06-04-2024	1	Opinionated Vite starter template demo
next-saas-stripe-starter	722	1 contributor	02-04-2024	-	An open-source SaaS Starter built using Next.js 14, Prisma, Planetscale, Auth.js v5, Resend, React Email, Shadcn/ui, Stripe and Server Actions demo
gatsby-starter-apple	132	3 contributors	01-04-2024	-	Gatsby blog starter kit with beautiful responsive design demo
fullstack-typescript	359	7 contributors	28-03-2024	3	FullStack React with TypeScript starter kit

as of April 2024

Comparison of boilerplates by features

Now let's take a closer look at the features developers can get from using boilerplates and what else needs to be taken into account:
API Integration: Some templates may contain configurations for integrating with specific APIs or server services.
State Management Solutions: Options like Redux, MobX, Recoil, or built-in React state management. Also, it's hard to ignore asynchronous React Query.
Testing Configuration: Predefined testing setups or none of them at all.
Authentication and Authorization: Whether user authentication and authorization are prescribed and how they are handled, in particular, whether there is integration with certain authentication libraries;
Internationalization (i18n) and Localization: Providing the ability to support multiple languages using libraries like react-i18next or react-intl.
ESLint Rules Compliance: Allows not only to detect or fix problems during code formatting but also to identify potential bugs.
Styling Solutions: The solution for using CSS modules, styled-components, or UI libs, which will ensure easy and effective reuse of styled components.
Type Safety in the Project: Using TypeScript to provide static typing during development, utilizing classes or modules to create more scalable and reliable applications.
App Theme Selection: Allowing users to switch between light and dark themes based on their preferences or automatic settings.
Ready-made Form Components: Providing components intended for reuse across forms, reducing code duplication, and promoting standardization. They may also include built-in validation and error handling, making development more reliable.
UI Component Libraries: Offering ready-made and customizable components, such as buttons and modal windows, that developers can easily integrate into their applications, saving time and effort on designing and coding these elements from scratch.
We analyzed each boilerplate and obtained the following table:

	extensive-react-boilerplate	React Starter Kit	react-redux-saga-boilerplate	Next-js-Boilerplate	landy-react-template	core	nextjs-boilerplate	react-pwa	Vitamin	next-saas-stripe-starter	gatsby-starter-apple	fullstack-typescript
Documentation	+	-	-	+	-	+	+	+	-	+	+-	-
Authentication features	+	+	-	-	-	-	-	-	-	+	-	-
Social sign in	+	+	-	+	-	-	-	-	-	+	-	-
Internationalization	+	-	-	+	+	-	-	-	-	-	-	-
User profile	+	-	-	-	-	-	-	-	-	+	-	-
Forms	+	-	-	+	+	-	-	-	-	+	-	-
Statement management	+	+	+	-	-	-	-	+	-	+	-	-
Tests	+	-	+	+	-	-	-	+	+	-	-	-
UI components	+	+	+	-	+	-	-	+	-	+	-	-
Eslint	+	+	+	+	-	+	-	+	+	+	+	+
Paid	-	-	-	-	-	-	-	-	-	-	-	-
Styled-components	+	-	+	-	+	-	-	+	+	-	+	+
TypeScript	+	+	+	+	+	+	+	+	+	+	+	+
Themes	+	+	+	+	-	-	-	+	+	+	+	-
UI Component	Material ui	Material ui	gilbarbara/ components	-	antd	-	Tailwind CSS	Material ui	Tailwind CSS	@radix-ui	-	Material ui

Description of boilerplates from the table

Extensive-react-boilerplate. This React boilerplate is designed for all types of projects. It's not only fully compatible with the backend boilerplate nestjs-boilerplate but also stands as an independent solution, which is one of its main advantages. This template offers a wide range of functionalities, such as:

User authentication and authorization, including the possibility of using Google or Facebook accounts.
Page private or public access settings.
ESLint setup with custom rules to enhance code efficiency and cleanliness.
Type safety to ensure the reliability of the written code.
Project localization using a custom useLanguage hook.
E2E testing support.
Light or Dark Mode at the discretion of the user.
A library of controlled components based on MUI, integrated with react-hook-form by default. So, no longer a need to spend extra time connecting input fields to controllers.
State management using React Query for handling asynchronous operations.
User management functionalities (CRUD).
Avatar selection and upload feature with dropzone capability.
Support for Next.js framework (SSR) for improved application performance and SEO optimization.

As you can see, from the above mentioned features, this boilerplate significantly reduces the startup time for your project (approximately 193 hours), making it a worthwhile consideration.

Categories: Feature-Rich Boilerplates, Boilerplates with Auth and Registration, Frontend-Only (and has a fully compatible backend boilerplate, thus can be used as Full-Stack Boilerplates), Free.

React-starter-kit. A template for creating web applications based on React. It comes with pre-configured setups such as CSS-in-JS, Vitest, VSCode settings, Cloudflare support, and SSR. A connection to Firestore is used as a database. It includes implementations of some UI components like a toolbar or sidebar based on Joy UI.

Categories: Feature-Rich Boilerplates, Boilerplates with Auth and Registration, Frontend-Only, Free.

React-redux-saga-boilerplate. A starter project for creating a React application that uses Redux for state management. It provides support for Unit and End 2 End Testing, react-helmet, and uses the Emotion library for styling, simplifying CSS styling with JavaScript. It includes custom components like a header or footer implemented using styled functionality.

Categories: Feature-Rich Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

Next-js-Boilerplate. This boilerplate has a flexible code structure where you only need to select and save the necessary functionality. It supports integration with Tailwind CSS, authentication with Clerk, and is compatible with SQLite, PostgreSQL, and MySQL databases. Unit testing is done using Jest, and the Zod library is used for describing validation schemas.

Categories: Feature-Rich Boilerplates, Boilerplates with Auth and Registration, Frontend-Only, Free.

Landy-react-template. This boilerplate comes with multilingual support, smooth animations, and all content is stored in JSON files, allowing users to manage texts without prior knowledge of React.js. Contains a set of its own components (button, input, textarea, etc.) created based on styling HTML elements using styled-components.

Categories: Feature-Rich Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

Core. A modern template was developed based on the fast project creation tool — Vite. It supports TypeScript for type safety and includes good configurations for ESLint, Prettier, CommitLint, Husky, and Lint-Staged.

Categories: Minimalistic Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

Nextjs-boilerplate. This React boilerplate uses Next.js for static page generation. It supports git message convention, component generation using Plop, and uses Tailwind CSS for styling organization. Has its Storybook for component documentation.

Categories: Minimalistic Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

React-pwa. A ready-made set to start your project from scratch. It consists of a minimalistic combination of core libraries, components, and utilities typically needed by developers when creating React applications. It contains its own HOC for error handling on the page and is developed based on Vite.

Categories: Feature-Rich Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

Vitamin. A starter project containing Tailwind CSS with a basic style reset and a Prettier plugin that automatically organizes your classes. For testing, tools such as Vitest, Testing Library, and Cypress are used, but it does not include React UI Component Libraries.

Categories: Minimalistic Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

Next-saas-stripe-starter. By using this boilerplate, you can extend the capabilities of your project with features like Next.js, Prisma, Planetscale, Auth.js v5, Resend, React Email, Shadcn/ui, and Stripe. It includes a library of components built using Radix UI and Tailwind CSS.

Categories: Feature-Rich Boilerplates, Boilerplates with Auth and Registration, Full-Stack Boilerplates, Free.

Gatsby-starter-apple. A template for creating applications with a nice responsive design and contains animations for a mobile menu. The basis for styling the used components is styled-components. The boilerplaite supports search engine optimization well and has RSS feed capabilities.

Categories: Minimalistic Boilerplates, Boilerplates without Auth, Frontend-Only, Free.

Fullstack-typescript. This boilerplate is a full-stack application for quickly launching your project. It has a library of custom components based on Material UI, and axios is used for client-server communication. It does not support certain state management technologies like Redux, MobX, etc.

Categories: Minimalistic Boilerplates, Boilerplates without Auth, Full-Stack Boilerplates, Free.

Peculiarities of implementation of some features

In general, React templates offer various implementation features aimed at speeding up and standardizing the development process. They include UI Component Libraries and encompass a general approach to styling, state management, and basic ESLint configurations.

React UI Component Libraries

The implementation of functionalities in React boilerplates often revolves around modular development, where components are designed to be reusable and composable. Analyzing current libraries and according to this article, the following can be considered the most popular ones:

We can say for sure, Material UI is currently the most popular library with 91.2k GitHub stars and more than 3 million weekly downloads. Thanks to its responsive web design (RWD) feature, you can be confident that your application will automatically adapt to various screens and devices.

Styling Solutions

Styling solutions such as CSS modules, styled-components, or Sass are usually included in React boilerplates. They offer different approaches to styling components, providing flexibility and scalability while maintaining component encapsulation.

Advantages of using styled-components as a styling solution:

The library automatically tracks components rendered on the page and applies only their styles.
Automatically generates a unique class name for styles, ensuring no errors in class names.
Styles are attached to specific components, simplifying the removal of CSS itself.
Effortless dynamic styling (code examples below belong to bc-boilerplates)

const AvatarInputContainer = styled(Box)(({ theme }) => ({
  display: "flex",
  position: "relative",
  flexDirection: "column",
  alignItems: "center",
  padding: theme.spacing(2),
  marginTop: theme.spacing(2),
  border: "1px dashed",
  borderColor: theme.palette.divider,
  borderRadius: theme.shape.borderRadius,
  cursor: "pointer",

  "&:hover": {
    borderColor: theme.palette.text.primary,
  },
}));

Using dynamic props of a component during styling. This ensures that the style is updated based on the value of the variable.

const StyledCollapseBtn = styled("button")<ICollapse>(({ isOpen, theme }) => ({
  justifySelf: "flex-end",
  color: COLOURS.black,
  backgroundColor: "transparent",
  border: "none",
  cursor: "pointer",
  paddingLeft: theme.spacing(2.5),
  position: "absolute",
  bottom:theme.spacing(3),
  left: isOpen ? "150px" : "unset",
}));

This allows for the reuse of styles from one component to another or for influencing one component over another (parent-child relationship).

const Link = styled.a`
display: flex;
align-items: center;
padding: 5px 10px;
background: papayawhip;
color: #BF4F74;
`;

const Icon = styled.svg`
flex: none;
transition: fill 0.25s;
width: 48px;
height: 48px;

${Link}:hover & {
  fill: rebeccapurple;
}
`;

State Management

State management is another important aspect that simplifies application state handling, providing scalability and maintainability, especially in complex applications. Usually, Redux, MobX, and Zustand come to mind when choosing a state management tool. However, they are client-side libraries, and compared to a tool like React Query, their application for storing asynchronous data may not be as efficient.

React Query is a server-state library used in some boilerplates like bc-boilerplates. It is responsible not only for managing asynchronous operations between the server and the client but also provides ready-to-use functionality for searching, caching, and updating data in React and Next.js applications. With just a few lines of code, React Query replaces the boilerplate code used to manage cached data in your client state.

ESLint Rules in Boilerplates

The efficiency of using ESLint rules during the development of your project is also manifested in writing custom rules. Since ESLint has extensive functionality and flexibility, you can create not only formatting and rules but also consider internal project decisions. For example, working with forms, it is possible to control and warn developers about possible unnecessary renders, incorrect solutions when working with objects, or simply point out unused imports. For example, extensive-react-boilerplate addresses such issues as follows:

warn about rules regarding incorrect usage of patterns


      {
        "selector": "ConditionalExpression[consequent.type=Literal][consequent.value=true][alternate.type=Literal][alternate.value=false]",
        "message": "Do not use \"condition ? true : false\". Simplify \"someVariable === 42 ? true : false \" to \"someVariable === 42\""
      },
      {
        "selector": "JSXElement[openingElement.name.property.name=Provider] JSXElement[openingElement.name.name]",
        "message": "Do not put your regular components inside Context \".Provider\". Create new component, for example ComponentProvider. Put Provider's logic to ComponentProvider. Render \"{children} instead of regular component. Wrap regular component via new ComponentProvider \". Example: \"src/services/auth/auth-provider\""
      },
      {
        "selector": "Property[key.name=/^(padding|margin|paddingLeft|paddingRight|paddingTop|paddingBottom|paddingVertical|marginLeft|marginRight|marginTop|marginBottom|marginVertical)$/][value.type=/^(Literal|UnaryExpression)$/]:not([value.value=\"0 !important\"]):not([value.value=\"0\"]):not([value.value=\"0 auto\"]):not([value.value=\"auto\"])",
        "message": "Use theme.spacing() instead of literal."
      },
      {
        "selector": "CallExpression[callee.name=/^(useQuery|useInfiniteQuery)$/] Property[key.name=queryKey]:not(:has(Identifier[name=key]))",
        "message": "Use key created via createQueryKeys function instead of your solution"
      },
      {
        "selector": "CallExpression[callee.name=refresh]",
        "message": "Do not use refresh() function for update or change result in react-query. Use \"queryClient.resetQueries\" or pass new filter data to queryKey."
      },
      {
        "selector": "ExpressionStatement[expression.callee.object.name=JSON][expression.callee.property.name=parse][expression.arguments.0.callee.object.name=JSON][expression.arguments.0.callee.property.name=stringify]",
        "message": "Do not use JSON.parse(JSON.stringify(...)) for deep copy. Use structuredClone instead."
      }

inform about the possibility of uncontrolled renders


      {
        "selector": "VariableDeclaration[declarations.0.init.callee.name=useForm] ~ VariableDeclaration[declarations.0.init.callee.name=useFieldArray]",
        "message": "\"useFieldArray\" in main form component (which use \"useForm\") will re-render the whole form component. Move your useFieldArray's logic to separate component."
      },
      {
        "selector": "VariableDeclaration[declarations.0.init.callee.name=useForm] ~ VariableDeclaration[declarations.0.init.callee.name=useController]",
        "message": "\"useController\" in main form component (which use \"useForm\") will re-render the whole form component. Move your useController's logic to separate component."
      },
      {
        "selector": "VariableDeclaration[declarations.0.init.callee.name=useForm] ~ VariableDeclaration[declarations.0.init.callee.name=useFormContext]",
        "message": "\"useFormContext\" in main form component (which use \"useForm\") will re-render the whole form component. Move your useFormContext's logic to separate component."
      },
      {
        "selector": "VariableDeclaration[declarations.0.init.callee.name=useForm] ~ VariableDeclaration[declarations.0.init.callee.name=useFormState]",
        "message": "\"useFormState\" in main form component (which use \"useForm\") will re-render the whole form component. Move your useFormState's logic to separate component."
      },
      {
        "selector": "CallExpression[callee.name=useForm][arguments.length=0], CallExpression[callee.name=useForm][arguments.length=1]:not(:has(Property[key.name=defaultValues]))",
        "message": "Pass object with \"defaultValues\" for correct \"formState\" behavior. More info here: https://react-hook-form.com/api/useform/formstate#main"
      }

Conclusion

The choice of an effective React template is crucial for the success of your project. Instead of reinventing the wheel, leveraging the power of a well-chosen boilerplate can significantly speed up your development process and create a solid foundation. When selecting a boilerplate, we recommend familiarizing yourself with its directory structure and configuration files to understand its underlying foundation, ease of integration, modularity, and maximum alignment with technical requirements. Consider whether the available features can provide the functions you need. This can save development time and potentially offer well-maintained and tested code.

Since there was often a question of how to apply multiple boilerplates simultaneously due to the lack of comprehensive functionality in such templates, the bc-boilerplates team proposed a solution in the form of the extensive-react-boilerplate. In our opinion, it can carve out its niche among well-known counterparts and become a worthy competitor deserving of your attention. We invite you to try it out and look forward to your feedback in the form of a new star.

Full credits for this article to Olena Vlasenko and Liudmyla Kostenko🇺🇦

Extensive React Boilerplate to kickstart a new frontend project

Rodion — Wed, 14 Feb 2024 13:15:50 +0000

How much time do we typically spend on project setup? We're talking about configuring installed libraries and writing boilerplate code to structure and implement best practices for achieving optimal website performance. At Brocoders, we often start new projects from scratch. That's why over 3 years ago, we created a NestJS boilerplate for the backend so that we wouldn't have to spend time developing core functionality that the end user doesn't see but is crucial for developers. Over this time, the boilerplate has received 2.4k stars on GitHub and has gained significant popularity beyond our company. Now, we've decided to take it a step further and created the Extensive React Boilerplate for the frontend. So, in purpose to keep our best practices in project development together, avoiding familiar pitfalls and reducing development time, we've created bc boilerplates.

Modules and libraries included in the boilerplate

To have server-side rendering out of the box, automatic page caching, preloading, and other speed optimizations, we use the Next.js framework. It extends React by adding static site generation and is a powerful tool for creating productive and SEO-friendly web applications. To ensure code reliability, performance, and readability in the boilerplate, TypeScript is utilized.

To prepare the website for supporting local languages and settings, we use the experienced language expert for web applications - the internationalization-framework i18next. It helps organize all added language versions and adapt the content of the site, menu, and messages for different languages and regional settings. We expanded it with packages to detect the user's browser language and transform resources into the server-side of i18next.

Material-UI is used for quickly creating interfaces without spending time writing components from scratch, such as buttons, input fields, tables, modal windows, and more. With dark mode support, the application based on the boilerplate is automatically configured to use the user's system theme.

React Hook Form library is integrated for form management, providing a simple and intuitive API optimized for high performance as it works with data without unnecessary re-renders of the entire form.

"React Query" is used for state management and data caching. It automatically optimizes queries, reducing their duplication, and supports data caching on both the client and server sides, allowing easy cache management across environments.

The Cypress library provides an interface for tracking and debugging tests, supporting various types of tests including unit tests, integration tests, user interface tests, and more.

ESLint helps to ensure that the style of the code in the project is consistent with the rules already established in the .eslintrc.json file to avoid potential problems and warn about possible errors.

Architecture of the react boilerplate project and folder structure

The project structure allows for easy navigation and editing of various parts of the application. Automated tests are located in the /cypress folder, divided into different specifications for testing various aspects of the application. All source code of the project, following the logical structure of the application, is concentrated in the /src folder. Nested within it, the /app folder displays various application pages, such as the administrative panel with pages for creating and editing users, email confirmation pages, password reset, password change, user profile, login, and registration.The /components folder contains common components that can be used on different pages of the application. The services section is responsible for interacting with the API server, its files contain modules that are important for proper functionality and interaction with the backend and external services.

As far as this boilerplate uses Next.js framework for building React applications, the folders are used as routes. This means the more folders you add to your app folder, the more routes you will get. Additionally, if you create a new folder inside of another folder, you will get nested routes. To better understand these concepts, we suggest looking at the image below.

We use dynamic segments in routing when flexible routes are needed. Within the file structure in the /app folder, such routes wrap the folder name in square brackets. Thus, it is easy to guess that the variable segments in the route src/app/[language]/admin-panel/users/edit/[id]/ will be language and id.

Mechanisms of authentication and user interaction

Since the web application supports internationalization, additional middleware is added to each page to determine the language, so the language of the authentication form will be displayed depending on the basic system settings of the user's device.

Sign Up page

The Sign Up page contains a registration form with fields for user registration, as well as the option to register via Google and Facebook. The necessary API for requests to the server to create a new account is specified, and saving user data is implemented using a context.

export function useAuthGoogleLoginService() {
 const fetchBase = useFetchBase();

 return useCallback(
   (data: AuthGoogleLoginRequest) => {
     return fetchBase(`${API_URL}/v1/auth/google/login`, {
       method: "POST",
       body: JSON.stringify(data),
     }).then(wrapperFetchJsonResponse<AuthGoogleLoginResponse>);
   },
   [fetchBase]
 );
}

export function useAuthFacebookLoginService() {
 const fetchBase = useFetchBase();

 return useCallback(
   (data: AuthFacebookLoginRequest, requestConfig?: RequestConfigType) => {
     return fetchBase(`${API_URL}/v1/auth/facebook/login`, {
       method: "POST",
       body: JSON.stringify(data),
       ...requestConfig,
     }).then(wrapperFetchJsonResponse<AuthFacebookLoginResponse>);
   },
   [fetchBase]
 );
}

Access and refresh tokens are acquired and stored for future requests if the backend status is ok, otherwise, error handling procedures are executed.

Sign In page

The Sign In page contains an authentication form with fields for logging in an already registered user, and again, the option to log in via Google or Facebook. After successful authentication, the user receives an access token and a refresh token, which are stored for future requests.

if (status === HTTP_CODES_ENUM.OK) {
     setTokensInfo({
       token: data.token,
       refreshToken: data.refreshToken,
       tokenExpires: data.tokenExpires,
     });
     setUser(data.user);
   }

const setTokensInfo = useCallback(
   (tokensInfo: TokensInfo) => {
     setTokensInfoRef(tokensInfo);

     if (tokensInfo) {
       Cookies.set(AUTH_TOKEN_KEY, JSON.stringify(tokensInfo));
     } else {
       Cookies.remove(AUTH_TOKEN_KEY);
       setUser(null);
     }
   },
   [setTokensInfoRef]
 );

Restore and update password

A user may forget their password, so functionality for resetting the old password by sending a link to the email is created. Of course, for such cases there should be a corresponding API on the server, like in our nestjs-boilerplate , which is perfect for for two-way interaction.

Also, there is an ability to update the password. The logic of sending an api request to the server for updating the user's password and further processing of its results is specified.

After registering a new account on the server, a link for email confirmation must be generated. Therefore, the boilerplate has logic for the confirm-email route as well.

Public and private routes

Both public and private routes are implemented - the user's authorization is checked before displaying certain pages, and if the user is not authorized or the authorization data has not yet been loaded, the user is redirected to the sign-in page. Below is the HOC function that implements this logic:

function withPageRequiredAuth(
 Component: FunctionComponent<PropsType>,
 options?: OptionsType
) {
 // …
 return function WithPageRequiredAuth(props: PropsType) {
   // …
   useEffect(() => {
     const check = () => {
       if (
         (user && user?.role?.id && optionRoles.includes(user?.role.id)) ||
         !isLoaded
       )
         return;

       const currentLocation = window.location.toString();
       const returnToPath =
         currentLocation.replace(new URL(currentLocation).origin, "") ||
         `/${language}`;
       const params = new URLSearchParams({
         returnTo: returnToPath,
       });

       let redirectTo = `/${language}/sign-in?${params.toString()}`;

       if (user) {
         redirectTo = `/${language}`;
       }

       router.replace(redirectTo);
     };

     check();
   }, [user, isLoaded, router, language]);

   return user && user?.role?.id && optionRoles.includes(user?.role.id) ? (
     <Component {...props} />
   ) : null;
 };
}

Cypress tests have been added for sign-in, sign-up and forgot-password to detect errors and check that all the functionalities of the authentication forms work on different browsers and devices.

User’s profile management

The boilerplate includes user data pages and pages for editing their data. Functionality has been added to implement an avatar component that allows users to upload or change their profile photo.

The /profile/edit page has been created to implement the ability to edit the profile, which includes a form with personal data that the user entered during registration, such as name, surname, password, as well as adding/changing an avatar. Additionally, to ensure code quality, detect potential security issues, and verify that the profile editing functionality works properly, this part of the code is also covered by Cypress tests.

describe("Validation and error messages", () => {
 beforeEach(() => {
   cy.visit("/sign-in");
 });
 it("Error messages should be displayed if required fields are empty", () => {
   cy.getBySel("sign-in-submit").click();
   cy.getBySel("email-error").should("be.visible");

   cy.getBySel("password-error").should("be.visible");

   cy.getBySel("email").type("useremail@gmail.com");
   cy.getBySel("email-error").should("not.exist");
   cy.getBySel("sign-in-submit").click();
   cy.getBySel("password-error").should("be.visible");

   cy.getBySel("password").type("password1");
   cy.getBySel("password-error").should("not.exist");

   cy.getBySel("email").clear();
   cy.getBySel("email-error").should("be.visible");
 });

 it("Error message should be displayed if email isn't registered in the system", () => {
   cy.intercept("POST", "/api/v1/auth/email/login").as("login");
   cy.getBySel("email").type("notexistedemail@gmail.com");
   cy.getBySel("password").type("password1");
   cy.getBySel("sign-in-submit").click();
   cy.wait("@login");
   cy.getBySel("email-error").should("be.visible");
 });
});

To automate the process of detecting and updating dependencies, we use the Renovate bot. It helps avoid issues related to using outdated dependencies and allows controlling the dependency update process according to the project's needs.

Conclusion

We refer to the Extensive React Boilerplate as a structured starting point for frontend development. It pairs beautifully with our NestJS boilerplate for the backend, and with them, the development team can get started, minimizing setup time and focusing on developing unique aspects of the project, knowing that fundamentals are already correctly implemented. We also keep track of regular library updates and maintain the project in an up-to-date state. So, welcome to try our bc boilerplates out :)

Full credits for this article to Elena Vlasenko and the main developer of the project Vlad Shchepotin 🇺🇦

MongoDB support for NestJS Boilerplate with hexagonal architecture

Rodion — Tue, 16 Jan 2024 10:49:07 +0000

We created NestJS boilerplate in August 2020 and since then we have worked on its optimisation and improvements. NestJS boilerplate is a project that contains all necessary libraries and solutions like auth, mailing, etc. for fast-starting your project using a classic REST API approach. Right now this boilerplate has 1.8K stars on Github and got recognition and support from the developers community. Recently we also published our new frontend boilerplate on React that is excellently compatible with the backend implementation, so for now, we have a whole bc boilerplate ecosystem.

Motivation to include Mongo support

PostgreSQL support was originally included in the boilerplate because of its reliability, data integrity and an active community. But for projects that require high speed of working with large data sets and high scalability, MongoDB is usually a better choice. So, we wanted to integrate MongoDB support into our project. Also we’ve got a number of requests to include NoSQL DB support from the community members and coworkers that use this boilerplate.

So, now it's done and developers can choose between document-oriented database MongoDB and relational database PostgreSQL.

Now let’s figure out what would be better to use when setting up a new project. Of course, the question is not which database is better, because both databases are excellent, it all depends on the scope and goals of the application. Let’s dive into details.

If you need a relational database that uses complex SQL requests and works with most apps that support relational table structure, it’s better to choose PostgreSQL.
For a scenario where a high level of security and high ACID compliance is required, then PostgreSQL is the best solution.
If you need a reliable tool to handle complex transactions and analytics in applications that work with multi-structured, fast-changing data, then MongoDB is a good choice for your project.
If you're running an application that you'll need to scale and need to be distributed across regions for data locality or data sovereignty, MongoDB's scale-out architecture will automatically meet those needs.

If you need to know more about MongoDB vs PostgreSQL comparison, I recommend reviewing this article.

In order to provide a good level of abstraction and to simplify work with MongoDB we use Mongoose - an object data modeling (ODM) library. It allows developers to define their data models using a schema-based approach and provides a rich set of features that simplify the process of working with MongoDB. In addition to supporting basic CRUD operations and query functions out of the box, Mongoose provides a richer set of features for working with MongoDB, such as middleware functions, virtual properties, query builders, and schema validation. It allows developers to define the structure of their data, including the types of each field, and specify validation rules to ensure data consistency and integrity.

Object Mapping between Node and MongoDB managed via Mongoose

Implementation with hexagonal architecture

To allow an application to uniformly manage batch execution scenarios separately from its end devices and databases, the hexagonal software architecture (aka ports and adapters architecture) introduced by Alistair Cockburn was used. In his article, he emphasizes that there is not much difference between how a user interface and a database interact with an application, since they are both external connections that are interchangeable with similar components and interact with the application in equivalent ways. Therefore, we used this architectural approach in the project, and it allowed us to encapsulate the implementation details of the data source, thus implementing the support of 2 types of databases in the boilerplate.
Let's take a closer look at the implementation. First of all, we create the User entity in the users/domain directory.

export class User {
  id: number | string;
  email: string | null;
  password?: string;
  firstName: string | null;
  lastName: string | null;

  // ...
}

Then we create a port called UserRepository.

export abstract class UserRepository {
  abstract create(
    data: Omit<User, 'id'>,
  ): Promise<User>;
  abstract findOne(fields: EntityCondition<User>): Promise<NullableType<User>>;
}

In users/infrastructure/persistence/relational/repositories we implement UserRepository for working with TypeORM.

@Injectable()
export class UsersRelationalRepository implements UserRepository {
  constructor(
    @InjectRepository(UserEntity)
    private readonly usersRepository: Repository<UserEntity>,
  ) {}

  async create(data: User): Promise<User> {
    const persistenceModel = UserMapper.toPersistence(data);
    const newEntity = await this.usersRepository.save(
      this.usersRepository.create(persistenceModel),
    );
    return UserMapper.toDomain(newEntity);
  }

  async findOne(fields: EntityCondition<User>): Promise<NullableType<User>> {
    const entity = await this.usersRepository.findOne({
      where: fields as FindOptionsWhere<UserEntity>,
    });

    return entity ? UserMapper.toDomain(entity) : null;
  }
}

And we create a module for working with TypeORM in users/infrastructure/persistence/relational.

@Module({
  imports: [TypeOrmModule.forFeature([UserEntity])],
  providers: [
    {
      provide: UserRepository,
      useClass: UsersRelationalRepository,
    },
  ],
  exports: [UserRepository],
})
export class RelationalUserPersistenceModule {}

Now we do the same for Mongoose.

@Injectable()
export class UsersDocumentRepository implements UserRepository {
  constructor(
    @InjectModel(UserSchemaClass.name)
    private readonly usersModel: Model<UserSchemaClass>,
  ) {}

  async create(data: User): Promise<User> {
    const persistenceModel = UserMapper.toPersistence(data);
    const createdUser = new this.usersModel(persistenceModel);
    const userObject = await createdUser.save();
    return UserMapper.toDomain(userObject);
  }

  async findOne(fields: EntityCondition<User>): Promise<NullableType<User>> {
    if (fields.id) {
      const userObject = await this.usersModel.findById(fields.id);
      return userObject ? UserMapper.toDomain(userObject) : null;
    }

    const userObject = await this.usersModel.findOne(fields);
    return userObject ? UserMapper.toDomain(userObject) : null;
  }
}

And module for working with MongoDB.

@Module({
  imports: [
    MongooseModule.forFeature([
      { name: UserSchemaClass.name, schema: UserSchema },
    ]),
  ],
  providers: [
    {
      provide: UserRepository,
      useClass: UsersDocumentRepository,
    },
  ],
  exports: [UserRepository],
})
export class DocumentUserPersistenceModule {}

After that, we connect either the module for working with Mongoose (DocumentUserPersistenceModule) or TypeORM (RelationalUserPersistenceModule) in users/users.module.ts based on the ENV configuration.

const infrastructurePersistenceModule = (databaseConfig() as DatabaseConfig)
  .isDocumentDatabase
  ? DocumentUserPersistenceModule
  : RelationalUserPersistenceModule;

@Module({
  imports: [infrastructurePersistenceModule, FilesModule],
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService, infrastructurePersistenceModule],
})
export class UsersModule {}

And then in the UserService we can access the UserRepository, and nestjs will understand which database to use based on the ENV configuration settings.

@Injectable()
export class UsersService {
  constructor(
    private readonly usersRepository: UserRepository,
  ) {}
}

The full implementation can be found here.

MongoDB schema

Schema was built with best practices for MongoDB for best performance and scalability. Schema design for NoSQL databases is not the same as for relational databases. One of the differences is that in relational we have the option to reduce your schema to normal forms to avoid duplicates, etc. While for NoSQL, we can duplicate data to avoid "joins", due to which the best performance indicator will be achieved during data sampling. Let's take a look at the boilerplate as an example to see what the difference is. The database schema for PostgreSQL looks something like this:

And an example of data table:

Talking about MongoDB, then we can NOT transfer the design experience from PostgreSQL here, that is, create 4 collections users, files (for photos), roles, statuses and store in the user collection links to other collections and during data sampling using aggregation ($lookup) append additional data, as this will affect performance (read more about joins comparison in this article, though 2020 year sounds old, but it is still actual). What should the scheme look like? Everything is very simple: all data must be stored in one collection:

And now when we will fetch users, we will not need to make additional requests for obtaining data about the user's photo, role and status, because all the data is already stored in the user's collection, in fact, due to which productivity will increase.

To learn more about designing MongoDB schemas I recommend reviewing this article.

How to use NestJS Boilerplate with Mongoose

For comfortable development (MongoDB + Mongoose) you have to clone the repository, go to folder my-app/ and copy env-example-document as .env.

cd my-app/
cp env-example-document .env

Change DATABASE_URL=mongodb://mongo:27017 to DATABASE_URL=mongodb://localhost:27017

Run additional container:
docker compose -f docker-compose.document.yaml up -d mongo mongo-express maildev

Install dependency
npm install

Run migrations
npm run migration:run

Run seeds
npm run seed:run:document

Run app in dev mode
npm run start:dev

That's it.

If we talk about the impact of the selected database on the frontend application, in particular the Extensive React boilerplate, which we also maintain up-to-date and it plays well with the currently discussed NestJS boilerplate, so it won't have affect on their interaction.

Whatever database you choose to use - PostgreSQL or MongoDB (they are both great), the choice should depend on the whole project, and in our boilerplate you have that choice) So, welcome to try it if you find it useful, check out our bc boilerplate ecosystem, and don't forget to click the star at the library ⭐.

Full credits for this article to Vlad Shchepotin and Elena Vlasenko 🇺🇦

Will Bun replace Node.js? First try with NestJS

Rodion — Fri, 15 Sep 2023 12:43:50 +0000

Many people recently talked about Bun, so we decided to try it.

Bun is a fast JavaScript all-in-one toolkit that helps to develop, test, run, and bundle JavaScript & TypeScript projects. It claims to be really fast in terms of runtime and development. So it should not only make the app faster but speed up the development process too. Take a look at their video presentation on YouTube.

Our idea was to run our Brocoders Nest.js Boilerplate on Bun and see how it performs. The test was made on MacBook Pro 2GHz, 16Gb memory:

So we tried to install dependencies with npm install and bun. The difference is pretty decent: 32s npm and 5s bun.

But then we tried to run it, there was an error appeared on the screen:

The problem is connected with emitDecoratorMetadata feature that is not supported by Bun yet. There is an issue with it on Github: https://github.com/nestjs/nest/issues/12359#issuecomment-1712712949
So, finally, I would say that Bun is really a perspective thing, but so far, it seems it's not ready for production yet. But we will definitely watch this repository and come back to it later.