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

Before removing a store, consider these alternatives:

• Could the store be moved to a different parent instead?
• Are there any dependent stores that need to be moved first?

To remove a store, you need to manually clean up several files:

1. Remove Configuration Files
   a. Delete the store's entry from alokai.config.json:

   {
     "stores": {
       "my-brand-us": {  // <- Remove this entire object
         "deployment": {
           "framework": "nextjs",
           "projectName": "my-project",
           "cloudRegion": "europe-west1"
         },
         "localPorts": {
           "middleware": 4001,
           "nextjs": 3001,
           "nuxt": 3334
         }
       }
     }
   }
   

   
   b. Remove tasks from turbo.json:

   {
     "tasks": {
       // Remove all tasks for the store
       "storefront-middleware-my-brand-us#build": { ... },
       "storefront-unified-nextjs-my-brand-us#build": { ... },
       "playwright-my-brand-us#test:integration:ui": { ... }
     }
   }
   

2. Delete Store Files

# Remove the store directory
rm -rf apps/stores/my-brand-us

3. Clean Build Cache

# Remove Turbo cache
rm -rf .turbo

Make Sure To:

1. Move any dependent stores to new parents before removal
2. Update any cross-store references in your codebase
3. Remove store dependencies from package.json