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.

Base Applications

The project starts with the following base applications in the apps directory:

• playwright - contains the integration tests for the Storefront application.
• 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.

Store Structure

By default, the project starts with a single store called default in the apps/stores directory:

apps/
├── storefront-unified-nextjs/     # Base shared code
├── storefront-unified-nuxt/       # Base shared code
├── storefront-middleware/         # Base middleware
└── stores/
    └── default/                   # Your initial store
        ├── storefront-unified-nextjs/
        ├── storefront-unified-nuxt/
        └── storefront-middleware/

This structure is ready to scale as your business grows. Using Alokai's file-based inheritance system, you can expand to manage multiple brands or stores efficiently. Here's an example of how the structure could evolve:

apps/
├── storefront-unified-nextjs/     # Base shared code
├── storefront-unified-nuxt/       # Base shared code
├── storefront-middleware/         # Base middleware
└── stores/
    ├── fashion-brand/            # Template store
    │   ├── storefront-unified-nextjs/  # Shared fashion brand customizations
    │   └── stores/
    │       ├── fashion-us-store/       # Deployable store
    │       └── fashion-eu-store/       # Deployable store
    └── sports-brand/             # Template store
        ├── storefront-unified-nextjs/  # Shared sports brand customizations
        └── stores/
            ├── sports-us-store/        # Deployable store
            └── sports-eu-store/        # Deployable store

When scaling, you can create two types of stores:

• Template Stores: (e.g., fashion-brand, sports-brand) Used to share code between their child stores, never deployed
• Deployable Stores: (e.g., fashion-us-store, fashion-eu-store) The actual stores that get built and deployed

See More:

• Managing Stores Guide - Learn how to create, configure, and manage multiple stores
• File-based Inheritance - Understand how the inheritance system works

Build Output

When building the stores, the system composes them into the .out directory:

.out/
├── fashion-us-store/
│   ├── storefront-unified-nextjs/   # Composed Next.js app
│   ├── storefront-middleware/       # Composed middleware
│   └── playwright/                 # Composed tests
└── sports-us-store/
    ├── storefront-unified-nextjs/   # Composed Next.js app
    ├── storefront-middleware/       # Composed middleware
    └── playwright/                 # Composed tests

Template stores are not built into the .out directory as they only serve as templates for their descendant stores.

Application Structure

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

apps/
 └── storefront-unified-nextjs/
     ├── app/
     │   ├── [locale]/
     │       ├── (auth)/            # Auth group pages
     │           ├── components/    # Scoped components
     │           ├── page.tsx       # Page component
     │       ├── (cms)/             # CMS group pages
     │       ├── ...
     │       └── layout.tsx         # Root layout component
     │   └── ...                    # Metadata files, e.g. robots.txt, favicon.ico, etc.
     ├── components/                # Project reusable components
     │   ├── cms/                   # CMS related components
     │       ├── wrappers/          # Render components function
     │       └── page/              # CMS page components
     │   ├── navigation/            # Components related to app segments or pages
     │       ├── footer.tsx         # One of the many components
     │       ├── ...
     │   ├── ui/                    # StorefrontUI block components
     │   ├── add-to-cart-button.tsx # Reusable component
     │   └── ...
     ├── config/                    # Project configuration
     │   ├── image-loaders/         # Next.js image loaders configuration
     │       ├── cloudinary/        # Cloudinary image loader configuration
     │       └── default.config.js  # Default image loader configuration
     │   ├── constants.ts           # Project constants
     │   ├── navigation.ts          # i18n routing configuration
     │   ├── fonts.ts               # Fonts configuration
     │   └── ...                    # Static app data
     ├── helpers/                   # Various helper functions
     ├── hooks/                     # Custom hooks
     ├── lang/                      # i18n translations
     ├── public/                    # Public assets
     ├── sdk/                       # Alokai SDK configuration
     ├── types/                     # Custom TypeScript types
     ├── i18n.ts                    # Next.js i18n configuration
     ├── middleware.ts              # Next.js middleware configuration
     ├── next.config.mjs            # Next.js app configuration
     ├── package.json               # Project dependencies
     ├── tailwind.config.js         # Tailwind configuration
     ├── tsconfig.json              # TypeScript 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.

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.

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.