# Version Compatibility Matrix

Current framework and tool versions supported by Forge platform.

> **🚀 Upgrading?** See [Migration Guides](../learn/migration/forge-v2-to-v3.md)

---

## 🎯 Version Support

| Component          | Forge 2.1.x | Forge 3.0    | Breaking? |
| ------------------ | ----------- | ------------ | --------- |
| **.NET**           | 8.0, 9.0    | 10.0         | ⚠️ YES     |
| **Aspire**         | 9.5.x       | 13.5.3       | ⚠️ YES     |
| **Authentication** | Okta        | Okta + Entra | ⚠️ YES     |
| **Node.js**        | 20.x, 22.x  | 22.x, 24.x   | No        |
| **TypeScript**     | 5.9+        | 5.9+         | No        |
| **Terraform**      | 1.0+        | 1.0+ baseline; see module exceptions below | No        |

---

## 📋 Framework Details

### .NET

| Version   | Type                                        | Forge 2.1.x | Forge 3.0 | Support Ends |
| --------- | ------------------------------------------- | ----------- | --------- | ------------ |
| .NET 8.0  | <span class="version-badge new">LTS</span>  | ✅           | ❌         | Nov 2026     |
| .NET 9.0  | <span class="version-badge beta">STS</span> | ✅           | ❌         | May 2026     |
| .NET 10.0 | <span class="version-badge new">LTS</span>  | ❌           | ✅         | Nov 2027     |

**Configuration:**

```xml
<TargetFramework>net10.0</TargetFramework>
```

**MCP SDK packages:**

| Package | Version | Notes |
| ------- | ------- | ----- |
| `ModelContextProtocol` | `2.1.0` | Target protocol `2026-07-28`; `ProtocolVersion` left unset for dual-era negotiation. See [ADR 0014](decisions/0014-adopt-mcp-2026-07-28-and-explicit-conversation-ids.md). |
| `ModelContextProtocol.AspNetCore` | `2.1.0` | Same protocol and negotiation choice for Smithy's HTTP endpoint. See [ADR 0014](decisions/0014-adopt-mcp-2026-07-28-and-explicit-conversation-ids.md). |

### Node.js

| Version                                         | Forge 2.1.x | Forge 3.0 | Support Ends |
| ----------------------------------------------- | ----------- | --------- | ------------ |
| 20.x <span class="version-badge new">LTS</span> | ✅           | ❌         | Apr 2026     |
| 22.x <span class="version-badge new">LTS</span> | ✅           | ✅         | Apr 2027     |
| 24.x                                            | ❌           | ✅         | Oct 2027     |

### Aspire

| Version | Forge 2.1.x | Forge 3.0 |
| ------- | ----------- | --------- |
| 9.5.x   | ✅           | ❌         |
| 13.5.3  | ❌           | ✅         |

The Forge v2 to v3 migration requires Aspire CLI 13.1 or later; Forge 3.0 templates currently use 13.5.3.

### SAIF CLI

Forge 3.0 requires SAIF CLI 3.0 or later. [Updating the SAIF CLI](../learn/install-saif-cli.md#updating-saif-cli) covers how to update it.

### Terraform

| Version | Forge 2.1.x | Forge 3.0 |
| ------- | ----------- | --------- |
| 1.x     | ✅           | ✅         |

**Required Version Constraint:**

```hcl
required_version = ">= 1.0.0, < 2.0.0"
```

The `saif-dynatrace-config` project template is a documented exception to this
platform-wide Terraform baseline and requires Terraform `>= 1.9.0, < 2.0.0`
in both its bootstrap and infrastructure configurations.

The `saif-resources/modules/servicebus-queue` module requires `>= 1.3.0, < 2.0.0`. Check the selected module's `providers.tf` as well as the platform baseline; see the [Service Bus queue module reference](terraform/saif-resources/servicebus-queue.md).

### Terraform Providers

| Provider | Forge 2.1.x        | Forge 3.0          | Notes                             |
| -------- | ------------------ | ------------------ | --------------------------------- |
| AzureRM  | `>= 4.0, < 5.0`    | `>= 4.0, < 5.0`    | Azure Resource Manager            |
| AzureAD  | `>= 3.0, < 4.0`    | `>= 3.0, < 4.0`    | Entra ID (Azure AD)               |
| Okta     | `>= 4.10.0, < 5.0` | `>= 4.10.0, < 5.0` | External tenant only in Forge 3.0 |
| TFE      | `>= 0.58.1, < 1.0` | `>= 0.58.1, < 1.0` | Terraform Cloud/Enterprise        |
| Random   | `>= 3.0, < 4.0`    | `>= 3.0, < 4.0`    | Random resource generation        |
| Time     | `>= 0.40.0`        | `>= 0.40.0`        | Time-based resources              |
| azapi    | `>= 2.0, < 3.0`    | `>= 2.0, < 3.0`    | Front Door existence pre-checks (#845), required by consumers of `saif-resources/modules/environment` |

**Standard Provider Configuration:**

```hcl
terraform {
  required_version = ">= 1.0.0, < 2.0.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 4.0, < 5.0"
    }
    azuread = {
      source  = "hashicorp/azuread"
      version = ">= 3.0, < 4.0"
    }
  }
}
```

### TypeSpec

| Version   | Forge 2.1.x and below | Forge 3.0          | Notes                    |
| --------- | ---------------------- | ------------------ | ------------------------ |
| 1.3.0+    | ✅ Required             | ✅ Required         | Compiler minimum         |
| Libraries | 0.75.0 - 1.5.0         | 0.85.0 - 1.15.0     | Various library versions |

> **Note:** `@saif/platform-typespec` ships as its own npm package with an independent semver line (currently 3.x) that does not correspond to the Forge 2.1.x / Forge 3.0 platform release-line numbers used elsewhere on this page. See the [`@saif/platform-typespec` reference](platform-typespec.md) for what the package provides, and [the Kiota `status` troubleshooting guide](../troubleshoot/kiota-generated-client-status-does-not-exist.md) for version-specific defect guidance.

**Key Packages:**

```json
{
  "@typespec/compiler": "^1.15.0",
  "@typespec/http": "1.15.0",
  "@typespec/rest": "0.85.0",
  "@typespec/openapi3": "1.15.0",
  "@typespec/versioning": "0.85.0",
  "@saif/platform-typespec": "^3.9.3"
}
```

See the [`@saif/platform-typespec` reference](platform-typespec.md) for the conventions this library adds on top of raw TypeSpec.

---

## 📚 Migration Guides

- **[Forge 3.0 Migration](../learn/migration/forge-v2-to-v3.md)** - .NET 10, Aspire 13, Entra ID, Terraform restructuring

---

## 📚 Resources

**Documentation:**

- [Forge Overview](../index.md)
- [Migration Guides](../learn/migration/forge-v2-to-v3.md)
- Release Notes - See the **Release Notes** section in the navigation menu

---

**Last Updated:** December 20, 2025