# Expand Dependencies

The `sfp dependency:expand` command enriches your project's dependency declarations by automatically adding all transitive dependencies to your `sfdx-project.json`. This ensures that each package explicitly declares all its dependencies, both direct and indirect, making the dependency graph complete and explicit.

### What It Does

When you run `sfp dependency:expand`, it:

1. **Analyzes all packages** in your project to identify their direct dependencies
2. **Resolves transitive dependencies** by recursively finding dependencies of dependencies
3. **Updates each package** to include both direct and transitive dependencies
4. **Maintains proper ordering** ensuring dependencies are listed in topological order
5. **Preserves external dependencies** defined in your project configuration

### Why Use Expand

Expanding dependencies is useful for:

* **Explicit dependency management**: Makes all dependencies visible in the project configuration
* **Build optimization**: Helps build tools understand the complete dependency graph
* **Troubleshooting**: Easier to identify dependency-related issues when all dependencies are explicit
* **CI/CD pipelines**: Ensures all required dependencies are known upfront

### Usage

```bash
# Create an expanded version of the project configuration
sfp dependency:expand

# Overwrite the existing sfdx-project.json with expanded dependencies
sfp dependency:expand --overwrite
```

### Flags

| Flag                           | Description                                                                    | Required |
| ------------------------------ | ------------------------------------------------------------------------------ | -------- |
| `-o`, `--overwrite`            | Overwrites the existing sfdx-project.json file with the expanded configuration | No       |
| `-v`, `--targetdevhubusername` | Username or alias of the target Dev Hub org                                    | Yes      |
| `--loglevel`                   | Logging level (trace, debug, info, warn, error, fatal)                         | No       |

### Behavior

* Without `--overwrite`, creates a new file at `./project-config/sfdx-project.exp.json`
* With `--overwrite`, backs up existing `sfdx-project.json` to `./project-config/sfdx-project.json.bak` and overwrites the original
* Adds all transitive dependencies to each package's dependency list
* Maintains topological ordering of dependencies
* Handles version conflicts by selecting the highest version required

### Example: Before and After

#### Before Expansion

```json
{
  "packageDirectories": [
    {
      "path": "packages/feature-a",
      "package": "feature-a",
      "dependencies": [
        { "package": "core-package" }
      ]
    },
    {
      "path": "packages/feature-b",
      "package": "feature-b",
      "dependencies": [
        { "package": "feature-a" }
      ]
    },
    {
      "path": "packages/core-package",
      "package": "core-package",
      "dependencies": [
        { "package": "base-package" }
      ]
    },
    {
      "path": "packages/base-package",
      "package": "base-package",
      "dependencies": []
    }
  ]
}
```

#### After Expansion

```json
{
  "packageDirectories": [
    {
      "path": "packages/feature-a",
      "package": "feature-a",
      "dependencies": [
        { "package": "base-package" },     // Transitive dependency added
        { "package": "core-package" }       // Direct dependency
      ]
    },
    {
      "path": "packages/feature-b",
      "package": "feature-b",
      "dependencies": [
        { "package": "base-package" },     // Transitive dependency added
        { "package": "core-package" },     // Transitive dependency added
        { "package": "feature-a" }         // Direct dependency
      ]
    },
    {
      "path": "packages/core-package",
      "package": "core-package",
      "dependencies": [
        { "package": "base-package" }      // Direct dependency
      ]
    },
    {
      "path": "packages/base-package",
      "package": "base-package",
      "dependencies": []
    }
  ]
}
```

### Relationship with Shrink

The `expand` and `shrink` commands are complementary:

* **Expand**: Adds all transitive dependencies, making them explicit
* **Shrink**: Removes redundant transitive dependencies, keeping only direct ones

Typical workflow:

1. Use `expand` during development to understand full dependency graphs
2. Use `shrink` before committing to maintain clean, minimal dependency declarations

### Version Conflict Resolution

When multiple packages require different versions of the same dependency, `expand` automatically selects the highest version that satisfies all requirements. For example:

* Package A requires `core@1.0.0`
* Package B requires `core@1.2.0`
* Result: Both will get `core@1.2.0`

### External Dependencies

External dependencies (managed packages from other Dev Hubs) defined in your `externalDependencyMap` are:

* Automatically included in the expansion process
* Preserved with their version specifications
* Added to packages that transitively depend on them

### Notes

* The command validates all dependencies exist in the project
* Circular dependencies are detected and reported as errors
* External dependencies must be properly configured in the `plugins.sfp.externalDependencyMap` section
* The expanded configuration can become large for projects with many packages

### See Also

* [Shrink Dependencies](https://docs.flxbl.io/flxbl/sfp/development/dependency-management/shrink-dependencies) - Remove redundant transitive dependencies
* [Explain Dependencies](https://docs.flxbl.io/flxbl/sfp/development/dependency-management/explain-dependencies) - Understand package dependencies


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/development/dependency-management/expand-dependencies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.