Development - Managing the stores

This guide covers the core operations for managing stores in Alokai multistore projects through the Alokai CLI.

What You'll Learn

• How to create new stores using the CLI
• Understanding and modifying store configurations
• Moving stores within your project hierarchy
• Safely removing stores and handling cleanup

Why This Matters

When working with multiple brands and regions, keeping clean and maintainable repository is one of the most important characteristics that ensure you can keep releasing fast and with a high confidence. The Alokai CLI provides the tools you need to create, configure, and manage stores while keeping your codebase clean and structured.

Let's explore how to manage your stores effectively.

Adding a New Store

The store add command guides you through creating a new store and sets up all necessary configurations:

yarn store add

Store Creation Flow

The CLI will ask several questions to configure your store:

1. Store ID
   • Unique identifier for your store
   • Used in alokai.config.json, turbo.json, and store directory
   • Example: my-brand-us
2. Parent Store
   • Choose if this store inherits from existing store
   • Or choose root to inherit from base apps
3. Store Type
   • Choose if store should be deployable or not. Template stores are not deployable.
4. Console Project (for deployable stores only)
   • The project name in Alokai Console
   • If you're not sure, just skip it for now
   • Can be updated later in alokai.config.json
5. Cloud Region (for deployable stores only)
   • Deployment region for your store
   • If you're not sure, just skip it for now
   • Can be updated later in alokai.config.json

What the Command Does

When you create a new store, the CLI:

1. Updates Configuration Files
   • Creates app-specific config files (.prettierrc.mjs, eslint.config.mjs, etc.)
   • For deployable stores:
     • Adds store entry to alokai.config.json
     • Updates turbo.json with build tasks and dependencies
2. Creates Store Directory Structure
   • Sets up store directory with all required apps

alokai.config.json Updates

For deployable stores, the CLI adds a new entry with default settings. All of these settings can be modified at any time:

{
  "$schema": "./.alokai/alokaiConfigSchema.json",
  "stores": {
    "my-brand-us": {
      "deployment": {
        "framework": "nextjs", // Which frontend framework to deploy
        "projectName": "my-project", // Your project in Alokai Console
        "cloudRegion": "europe-west1" // Where to deploy
      },
      "localPorts": {
        "middleware": 4001, // Port for local middleware
        "nextjs": 3001, // Port for Next.js development
        "nuxt": 3334 // Port for Nuxt development
      },
      "localDomain": "my-brand-us.local" // Domain for local development, when using `with-local-domains` flag
    }
  }
}

Important Things to Know:

• Template stores are not added to alokai.config.json as they're not meant to be deployed
• All settings can be modified later by editing this file
• Remember to restart your development server after making changes

turbo.json Updates

The CLI adds build tasks and dependencies to turbo.json. These tasks ensure proper build order and caching:

{
  "tasks": {
    "storefront-middleware-my-brand-us#build": {
      "dependsOn": ["^build"],
      "inputs": ["**"],
      "outputs": ["lib/**"]
    },
    "storefront-unified-nextjs-my-brand-us#build": {
      "dependsOn": ["^build", "storefront-middleware-my-brand-us#build"],
      "inputs": ["**"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "playwright-my-brand-us#test:integration:ui": {
      "dependsOn": [],
      "cache": false
    }
  }
}

Each task is named using the pattern {app-name}-{store-id}#{task-name}. The tasks ensure:

1. Middleware Build (storefront-middleware-my-brand-us#build)
   • Builds the middleware application first
   • Generates TypeScript types needed by the frontend
   • Caches the compiled output in lib/
2. Frontend Build (storefront-unified-nextjs-my-brand-us#build)
   • Waits for middleware to build (needs its types)
   • Builds the Next.js application
   • Caches the .next output (except cache directory)
3. Integration Tests (playwright-my-brand-us#test:integration:ui)
   • Not cached as tests should run fresh each time

Generated Store Structure

The CLI creates this directory structure for your store:

apps/stores/my-brand-us/
├── storefront-unified-nextjs/    # Next.js app overrides
├── storefront-unified-nuxt/      # Nuxt app overrides
└── storefront-middleware/        # Middleware overrides
└── playwright/                   # Playwright tests

Moving Stores

The store move command helps reorganize your store hierarchy:

yarn store move

Move Process

1. Select the store to move
2. Choose the new parent:

• Choose one of the existing stores as the new parent
• Or choose root to inherit from base apps

What Happens During a Move

When moving a store:

1. Store configuration is updated in alokai.config.json
2. tsconfig.json is regenerated to inherit from the new parent
3. Store directory structure remains unchanged

// apps/stores/my-brand-us/storefront-unified-nextjs/app/page.tsx
import CustomHeader from "@/components/custom-header";

# Old parent had the component
apps/stores/fashion-brand/storefront-unified-nextjs/components/custom-header.tsx

# But new parent doesn't have it
apps/stores/sports-brand/storefront-unified-nextjs/components/custom-header.tsx  # Missing!

Best Practices for Moving Stores

1. Plan the Move
   • Figure out current store dependencies
   • Plan testing strategy for affected stores
2. Testing After Move
   • Build and test the moved store
   • Test stores that inherited from the moved store
   • Verify all customizations still work

Removing Stores

The store remove command helps you remove a store from your project:

yarn store remove <store_id>

Before removing a store

Before removing a store, consider the following:

• Could the store be moved to a different parent instead? If yes, use the store move command.
• Could the store be renamed instead? If yes, use the store rename command.
• Are there any inheriting stores that you want to keep? If yes, move them to a new parent first using the store move command.

What happens during a removal

When you remove a store, the CLI:

1. Deletes the store's and all inheriting stores' entries from alokai.config.json,
2. Removes the store's and all inheriting stores' tasks from turbo.json,
3. Deletes the store's and all inheriting stores' files from the apps/**/stores directory,
4. Cleans Turbo Build Cache.

After removing a store

After the store remove command finishes successfully, there are still some things you should do manually:

1. Update any cross-store references in your codebase,
2. Remove dependencies of the deleted store from /apps/playwright/package.json and /apps/storefront-*/package.json files.