> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unleash-commerce.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Use local versions of unleash-commerce-core and unleash-commerce-admin in your Laravel app

You may need to change or test behavior in one of the Unleash Commerce packages, such as Core or Admin, while working on your Laravel application.
This page explains how to run your app against local package checkouts so you can iterate, verify, and ship those package changes safely.

## Prerequisites

<Info>
  * A Laravel application using `ddev`
  * Local checkouts of `unleash-commerce-core` and `unleash-commerce-admin`
</Info>

### Recommended workspace structure

Keep your application and packages as siblings:

<Tree>
  <Tree.Folder name="workspace" defaultOpen>
    <Tree.Folder name="your-laravel-app" defaultOpen>
      <Tree.File name="composer.json" />

      <Tree.File name="composer.local.json" />

      <Tree.Folder name=".ddev" defaultOpen>
        <Tree.File name="docker-compose.packages.yaml" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="packages" defaultOpen>
      <Tree.Folder name="unleash-commerce-core" />

      <Tree.Folder name="unleash-commerce-admin" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

## Using the starter kit (recommended)

The [starter kit](https://github.com/esign/unleash-commerce-starter-kit) already includes local package support out of the box (ddev volume mount + Composer merge setup).
To opt in to local package development, you only need these steps:

1. Copy the local Composer overrides file:

```bash theme={null}
cp composer.local.json.example composer.local.json
```

2. Update the package dependencies:

```bash theme={null}
ddev composer update esign/unleash-commerce-core esign/unleash-commerce-admin
```

<Note>
  If you hit a Composer repository-priority error while using local path repositories, check `composer.local.json`.
  In this setup, Core is aliased to satisfy Admin's current Core requirement:

  ```json theme={null}
  {
    "require": {
      "esign/unleash-commerce-core": "dev-master as 0.1.1",
      "esign/unleash-commerce-admin": "dev-master"
    }
  }
  ```

  This can still happen even when using ranges like `^0.1.1` if the path repository is canonical and exposes only a `dev-*` version that does not match the requested constraint.
  Keep the alias in sync with Admin's Core constraint when that constraint changes.
</Note>

<Warning>
  Do not commit a `composer.lock` that includes local path references (for example `/packages/...`).
  Those references are local-only and will break installs in CI, staging, and production.
  See [Make package changes available beyond local development](#make-package-changes-available-beyond-local-development) for safe alternatives.
</Warning>

### Make package changes available beyond local development

When you want to validate your package changes outside your local machine (for example in CI, staging, or production), switch from local path references to a Git-based package version.

First, if you enabled local overrides through `composer.local.json`, remove that file:

```bash theme={null}
rm composer.local.json
```

You have two options:

1. **Use a feature branch**

```bash theme={null}
ddev composer require esign/unleash-commerce-core:dev-feature/my-change
ddev composer require esign/unleash-commerce-admin:dev-feature/my-change
```

2. **Use a tagged release**

```bash theme={null}
ddev composer require esign/unleash-commerce-core:^0.1.3
ddev composer require esign/unleash-commerce-admin:^0.1.4
```

After switching, run `ddev composer update esign/unleash-commerce-core esign/unleash-commerce-admin` and commit the resulting `composer.lock`.

## Not using the starter kit?

If your project is not based on the starter kit, follow the full setup below.

### Configure ddev volume mounting

Because `ddev` cannot follow symlinks that point outside the container, expose your `packages` directory inside the container.

Create `.ddev/docker-compose.packages.yaml` in your Laravel app:

```yaml theme={null}
services:
  web:
    volumes:
      - "../../packages:/packages"
```

Then restart `ddev`:

```bash theme={null}
ddev restart
```

### Register local path repositories

Update your Laravel app `composer.json` with path repositories:

```json theme={null}
{
  "repositories": {
    "esign/unleash-commerce-core": {
      "type": "path",
      "url": "/packages/unleash-commerce-core",
      "options": {
        "symlink": true
      }
    },
    "esign/unleash-commerce-admin": {
      "type": "path",
      "url": "/packages/unleash-commerce-admin",
      "options": {
        "symlink": true
      }
    }
  },
  "minimum-stability": "dev",
  "prefer-stable": true
}
```

### Require local package versions

Install both packages from your local checkouts:

```bash theme={null}
ddev composer update esign/unleash-commerce-core esign/unleash-commerce-admin
```

If you are setting up `unleash-commerce-admin` itself for local package development, you can also run:

```bash theme={null}
bash setup.sh
```

## IDE support (VS Code + Intelephense)

Because path-repository symlinks are created inside the `ddev` container (and not on your local filesystem), your IDE may not detect classes from the Core or Admin packages.
Add the package source paths explicitly to restore indexing and autocomplete.

In your Laravel application project, create or update `.vscode/settings.json` and configure both package source paths:

<CodeGroup>
  ```json VS Code (your-laravel-app/.vscode/settings.json) theme={null}
  {
    "intelephense.environment.includePaths": [
      "/path/to/your/packages/unleash-commerce-core/src",
      "/path/to/your/packages/unleash-commerce-admin/src"
    ]
  }
  ```

  ```json Cursor (your-laravel-app/.vscode/settings.json) theme={null}
  {
    "intelephense.environment.includePaths": [
      "/path/to/your/packages/unleash-commerce-core/src",
      "/path/to/your/packages/unleash-commerce-admin/src"
    ]
  }
  ```
</CodeGroup>

## Next steps

After installation, continue with package-specific setup:

* Core setup and install command: [Core introduction](/guides/core/introduction)
* Admin setup and customization: [Admin introduction](/guides/admin/introduction)