Tech Stack

This documentation outlines the technical stack used in the Storefront application. It aims to provide a comprehensive understanding of the technologies, project structure, tools, and best practices that power our application to ensure consistency, maintainability, and facilitate onboarding for new developers.

Project Structure

This project is built using Turborepo, a powerful development tool that enables efficient monorepo management and simplifies the process of building and maintaining complex software systems. By leveraging Turborepo's features, this project has achieved a scalable and modular architecture, allowing for easy collaboration among multiple teams and ensuring consistent development practices across the codebase.

For detailed information on how to get started, configure, and use this project built with Turborepo, please refer to the official documentation.

Storefront configuration

Storefront may be shipped with different ecommerce platforms and frameworks. In this documentation we describe the project structure for Storefront configured with Unified Data Layer, multiple ecommerce platforms (SAP Commerce Cloud, Commercetools, BigCommerce) and multiple frameworks (Next.js, Nuxt).

Depending on your configuration you will have the following main folders inside apps directory:

storefront-middleware - contains the middleware application that is responsible for handling all the requests from the Storefront application and communicating with the backend services.
storefront-unified-nextjs - contains the Storefront application built with Next.js (React) framework.
storefront-unified-nuxt - contains the Storefront application built with Nuxt (Vue) framework.

Storefront Middleware

The server application is the core of a Alokai application. It facilitates connections to services such as eCommerce platforms, CMS, or payment providers.


apps/
 └── storefront-middleware/
     ├── api/                         # Directory for extensions endpoints
     │   ├── extension-name           # Example extension directory
     │   │   ├── endpoint.ts          # Example endpoint file
     │   │   └── index.ts             # Barrel file
     ├── integrations/                # Ecommerce platform configuration
     │   ├── sapcc                    # Directory of SAPCC integration (example)
     │   │   ├── extensions           # Extensions directory
     │   │   │   ├── unified.ts       # UDL extension
     │   │   │   ├── multistore.ts    # Multistore extension
     │   │   │   ├── index.ts         # Barrel file
     │   │   ├── config.ts            # Integration configuration file
     │   │   ├── index.ts             # Barrel file
     │   │   └── types.ts             # Types needed for frontend app
     ├── src/
     │   └── index.ts                 # Middleware server entry file
     ├── .env                         # Environment variables
     ├── middleware.config.ts         # Middleware configuration
     ├── nodemon.json                 # Nodemon configuration
     ├── package.json                 # Project dependencies
     ├── tsconfig.json                # TypeScript configuration
     └── types.ts                     # Re-export types for the frontend app

The most important files of the Storefront Middleware app are:

api/ - directory to define custom API methods, and then register them as Middleware extensions in integrations directory.
integrations/ - contains the configuration files for the integrations.
src/index.ts - Express server entry point that handles all requests to the third-party platforms from the SDK
middleware.config.ts - Alokai Middleware configuration
types.ts - file that should re-export all types needed for the frontend app, including the types defined in the api/ and integrations/ directories.

For more info about the Middleware, including how to extend it, refer to the documentation.

Web Applications

Based on your configuration, you will receive either Next.js, Nuxt, or both web applications.

Frameworks

In order to keep this document short and to the point, we will only cover the most important files and directories for both applications.

Other framework specific files you can find in the respective framework documentation for Next.js and Nuxt.

Next.js

The web application follows a Next.js Pages Router file structure:


apps/
 └── storefront-unified-nextjs/
     ├── ...
     ├── components/                # Project Components
     │   ├── Footer/                # One of the many UI components
     │   ├── ...
     │   ├── ui/                    # StorefrontUI block components
     │   └── cms/                   # CMS related components
     │       ├── wrappers/          # Render components function
     │       └── page/              # CMS page components
     ├── config/                    # Project configuration
     │   ├── image-loaders/         # Next.js image loaders configuration
     │       ├── cloudinary/        # Cloudinary image loader configuration
     │       └── default.config.js  # Default image loader configuration
     │   ├── seo.ts                 # SEO configuration
     │   ├── route.ts               # Routes configuration
     │   └── pwa-cache.js           # PWA caching configuration
     ├── helpers/                   # Various helper functions
     ├── hooks/                     # Custom hooks
     ├── layouts/                   # Layouts
     ├── pages/                     # Pages
     │   ├── _app.tsx               # Custom App component
     │   ├── _document.tsx          # Custom Document component
     │   ├── [[...slug]].tsx        # Home page
     │   └── ...                    # Other pages
     ├── public/                    # Public assets
     ├── sdk/                       # Alokai SDK configuration
     ├── static/                    # Various static data
     ├── styles/                    # Project CSS configuration
     ├── types/                     # Custom TypeScript types
     ├── package.json               # Project dependencies
     ├── next-i18next.config.ts     # Next.js i18n configuration
     ├── next.config.js             # Next.js configuration
     ├── tsconfig.json              # TypeScript configuration
     ├── tailwind.config.js         # Tailwind configuration
     └── ...

Nuxt

The web application follows a Nuxt project file structure:


apps/
 └── storefront-unified-nuxt/
     ├── ...
     ├── assets/                    # Project CSS configuration
     ├── components/                # Project Components
     │   ├── Heading/               # One of the many UI components
     │   ├── ...
     │   ├── ui/                    # StorefrontUI block components
     │   └── cms/                   # CMS related components
     │       ├── wrappers/          # Render components function
     │       └── page/              # CMS page components
     ├── composables/               # Custom composables
     ├── lang/                      # Translations
     ├── layouts/                   # Layouts
     ├── helpers/                   # Various helper functions
     ├── middleware/                # Custom middleware
     │   └── auth.ts                # Auth middleware
     ├── mocks/                     # Mock data
     ├── modules/                   # Custom Nuxt modules
     │   └── cloudinary/            # Cloudinary module
     ├── pages/                     # Pages
     │   ├── [...slug].vue          # Home page
     │   └── ...                    # Other pages
     ├── plugins/                   # Custom plugins
     ├── public/                    # Public assets
     ├── sdk/                       # Alokai SDK configuration
     ├── server/                    # Custom server endpoints
     ├── utils/                     # Various utility functions
     ├── package.json               # Project dependencies
     ├── nuxt.config.ts             # Nuxt configuration
     ├── i18n.config.ts             # Next.js i18n configuration
     ├── app.vue                    # Nuxt App component
     ├── tsconfig.json              # TypeScript configuration
     ├── tailwind.config.js         # Tailwind configuration
     └── ...

Technologies

Storefront, while being a very flexible and customizable solution, is built on top of a set of opinionated technologies that are used consistently across the entire codebase. This section aims to give a brief overview of the technologies implemented in the project and their roles.

Opinionated Framework

Alokai is an opinionated framework; however, its underlying technologies are flexible. You can always replace the technologies used in the project with your preferred alternatives.

The default tech stack offers a consistent development experience throughout the entire codebase, ensuring that the project follows best practices and utilizes cutting-edge technologies.

The technologies used in the Storefront application can be categorized into two main groups:

General Technologies - technologies utilized in both Next.js and Nuxt applications.
Framework-Specific Technologies - technologies exclusive to either Next.js or Nuxt applications.

Moreover, these technologies can be classified into two types:

Core Technology - technologies that are used across the entire codebase and are essential for the project to function properly.
Recommended Technology - technologies that are used in the project but are not essential for the project to function properly. They are used to provide additional functionality and can be easily swapped out with your own preferred technologies.

Technologies Overview

Only the main technologies are listed here. For all dependencies, please refer to the package.json file in the respective application.

Technology	Category	Type	Purpose	Source
TypeScript	general	*core*	End to end type safety	TypeScript
Next.js	next	*core*	React.js Meta framework	Next.js
Nuxt	nuxt	*core*	Vue.js Meta framework	Nuxt
Express.js	general	*core*	Node.js web application framework	Express
Storefront UI	general	*core*	UI Components library	Storefront UI
Tailwind	general	*core*	CSS framework	Tailwind
Turborepo	general	*core*	Monorepo management tool	Turborepo
TanStack Query	next	*core*	Asynchronous state management and fetch library	TanStack Query
i18next	next	*core*	Internationalization for JavaScript applications	i18n
i18n Nuxt	nuxt	*core*	Internationalization for Nuxt applications	i18n Nuxt
Jest	next	recommended	Testing framework	Jest
Vitest	nuxt	recommended	Testing framework	Vitest
Commitizen	general	recommended	Release management tool	Commitizen
Husky	general	recommended	Pre-commit hooks	Husky
ESLint	general	recommended	Linter	ESLint
Lint-staged	general	recommended	Linter for staged files	Lint-staged
Prettier	general	recommended	Code formatting	Prettier
Commitlint	general	recommended	Commit message linter	Commitlint
Renovate	general	recommended	Dependency management tool	Renovate
nvm	general	recommended	Node.js version manager	nvm
Yarn	general	recommended	Package manager	Yarn

Why are we recommending to use these technologies?

The Alokai team has extensive experience building large-scale eCommerce applications. We've tried and tested many different technologies and frameworks, and we've found that the technologies listed above are the best fit for building scalable and maintainable eCommerce applications.

It's worth noting that, while we believe these technologies are ideal for your team and project, technology constantly evolves with new alternatives emerging. Thus, we remain open to suggestions and continuously evaluate new technologies to enhance your development experience.

Swapping out technologies

We recommend the technologies listed above for your project. However, we recognize that every team has its preferences and requirements. So, we've ensured that you can easily replace the technologies used in the project with those you prefer.

Technologies marked as recommended can be readily replaced or removed from the project. They aren't essential for the project to function and are in place to offer additional functionality, testing, or development experience.

Swapping out core technologies

Alokai aims to be as flexible as possible, so even core technologies can be replaced with ones you prefer.

But be cautious: replacing core technologies is a complex process requiring a deep understanding of the project's architecture and the technologies used. Therefore, we advise against swapping out core technologies unless you're entirely sure of your decision.