4.local-environment.md

title	layout
Using a local environment	default

Development - Using a local environment

This guide explains how to set up and run your local development environment for Alokai multistore projects, building on the concepts of file-based inheritance.

Root Scripts

Let's start with the foundation of your development workflow. Alokai provides essential scripts that will help you develop, test, and deploy your stores efficiently. These scripts are available in your project root's package.json and form the basis of your daily development tasks:

• dev: Your go-to command for development - starts all your stores in development mode with hot-reload
• build: Prepares your stores for production with optimized builds
• start: Runs your production build locally to verify everything works as expected
• test:integration:pw: Ensures your stores work correctly by running integration tests
• store: An alias for the ./node_modules/.bin/alokai-cli store. You can use it to run any alokai-cli store command.

:::info Scripts are shortcuts for alokai-cli commands All of these commands use the @alokai/cli underneath. For instance, the dev command is just a shortcut for ./node_modules/.bin/alokai-cli store dev --all --verbose. :::

:::warning Using Alokai CLI All store management operations must be performed through the Alokai CLI. Native Next.js/Nuxt commands will not work correctly with the multistore setup, as they don't handle the inheritance and configuration requirements of Alokai stores. :::

Starting Local Development

The most common way to start development is using the yarn scripts from the root level:

# Start development mode for all stores
yarn dev

# Start development for a specific store
yarn alokai store dev --store-id=my-store
# Alternatively, you may use: ./node_modules/.bin/alokai-cli store dev --store-id=my-store

The dev command watches for changes in:

• The current store's files
• Parent stores in the inheritance chain
• Base applications (apps/storefront-unified-nextjs, etc.)

When a file changes, the CLI automatically:

1. Detects which stores are affected by the change
2. Moves the affected files to the .out directory, so the app's framework can hot-reload the changes

::alert{type="info"} The applications will run on ports specified in the alokai.config.json file. For example:

{
  "stores": {
    "default": {
      "localPorts": {
        "middleware": 4000,
        "nextjs": 3000,
        "nuxt": 3333
      }
    }
  }
}

Each store can have its own port configuration to avoid conflicts when running multiple stores simultaneously. ::

Using Local Domains

Alokai uses Caddy as a reverse proxy to handle local domains. The Caddyfile is automatically generated based on the alokai.config.json file and the localDomain property for each store.

Prerequisites

• Caddy server installed
• Local domains configured in your hosts file. For example:
  • If you have a store with localDomain set to default.local, add 127.0.0.1 default.local to your hosts file

Starting with local domains

Start all stores with their local domains:

yarn alokai store dev --all --with-local-domains

:::tip HTTPS Caddy automatically generates self-signed SSL certificates for local domains. You can read more about it in the Caddy documentation. :::

Building for Production

To test the production build locally:

1. Build all deployable stores:

yarn build

2. Start the production server:

yarn start

Note that template stores are not built into the .out directory, as they only serve as templates for their descendant stores.

Running Integration Tests

Integration tests run against the composed stores, respecting the file inheritance chain:

yarn test:integration:pw

You can also run tests in Playwright's UI mode for better debugging experience:

yarn alokai store test --store-id=my-store --ui

:::warning The --ui flag only works when testing a single store. Make sure to specify the store using the --store-id flag. :::

For more information on integration tests, refer to the Integration Tests guide.

Common Issues and Solutions

Cache Problems

If you experience unexpected behavior with file inheritance or turbo cache. For example:

• You modify a component in your store, but the changes are not reflected in the browser
• The .out directory still contains old versions of your files after making changes

Here's how to fix it:

# Clear Turbo cache
rm -rf .turbo/cache

# Clear composed store outputs
rm -rf .out/*

# Rebuild all stores
yarn build

::alert{type="warning"} The .out directory contains the composed stores and is in .gitignore. If you experience inheritance issues, try clearing this directory and rebuilding. ::

Development Best Practices

1. Use Store-Specific Development When working on a single store, use the --store-id flag to improve build times:

yarn alokai store dev --store-id=my-store

2. Test Inheritance Chain When modifying shared code, test all affected stores:

# See which stores are affected by current changes
yarn alokai store changed

# Build and test affected stores
yarn alokai store build --store-id=affected-store-id-1,affected-store-id-2

:::tip In the Continuous Integration and Continuous Deployment pipelines, the affected stores are built and tested automatically. You can read more about it in the CD Pipeline guide. :::

1. Debugging Inheritance Use the --verbose flag to see detailed file resolution:

yarn alokai store build --store-id=my-store --verbose

You can also use the DEBUG=* environment variable to get even more logs:

DEBUG=* yarn alokai store build --store-id=my-store

1. Inspect Store Composition Examine how stores are composed in the .out directory:

yarn alokai store build --store-id=my-store --compose-only

This will skip the build and only compose the store into the .out directory.

::card{title="Next: Development - Writing an integration tests with Playwright" icon="tabler:number-3-small" }

#description Learn how to create and run integration tests using Playwright in your Alokai multistore project.

#cta :::docs-arrow-link{to="/guides/multistore/tooling-and-concepts/integration-tests"} Next ::: ::