THG Commerce THG
Altitude
Blog GitHub Go to Platform
Introducing Astro Integration v2.0

Introducing Astro Integration v2.0

July 21, 2025
Victor Elgersma
#astro #integration #v2 #release

We’re excited to announce the release of Astro Integration v2.0—a major update that simplifies configuration, improves single tenancy support, and streamlines the developer experience. This release includes several breaking changes, so read on to understand what’s new and how to upgrade.

What’s New in v2.0

Simplified Configuration API

The biggest change in v2.0 is how you configure the integration. We’ve moved from a direct parameter approach to a more flexible options object:

Before (v1):

// astro.config.mjs
import tenants from "./config";
export default defineConfig({
  integrations: [
    altitudeMiddleware(tenants, { enabled: true, graphql: gqlIndex }), // ❌ Direct parameters
  ],
  output: "server",
  // remaining config
});

After (v2):

// astro.config.mjs
import tenants from "./config";
export default defineConfig({
  integrations: [
    altitudeMiddleware({
      // ✅ Options object
      config: tenants, // ✅ Config property
      api: { enabled: true, graphql: gqlIndex },
    }),
  ],
  output: "server",
  // ... remaining config
});

This new approach makes the API more flexible and future-proof.

Streamlined Domain Configuration

We’ve simplified how domains are configured across your tenant configs. The old nested object structure was unnecessary and we have replaced it with an array:

Before (v1):

// config/powerman.js
domains: {
  default: "www.example.com",        // ❌ complex object
  variants: ["www.example.com", "www.example.fr"]
}
// ... remaining keys remain the same

After (v2):

// config/powerman.js
domains: ["www.example.com", "www.example.fr"]; // ✅ array
// ... remaining keys remain the same

When migrating, just make sure that the value for domains.default is the first item in the new domains array.

Decoupled Tenancy and i18n

We’ve completely separated tenancy and internationalization concerns, giving you much more flexibility to run the integration in the following 4 configurations.

  • Single tenant + i18n: Add the i18n key to your build config—no multitenancy required
  • Single tenant only: Simple setup with no header-switching or complex configuration
  • Multi-tenant + i18n: All tenants must have the i18n key
  • Multi-tenant only: Clean tenant separation without i18n overhead

Fixed Single Tenancy Mode

Single tenancy mode was broken in v1.x and has been completely rebuilt in v2.0:

  • Actually works: Single tenancy mode now functions properly (it was non-functional in v1.x)
  • Simplified setup: No i18n configuration required for basic single-tenant sites
  • Better performance: Rewrites only occur for i18n-enabled tenants, not all tenants
  • No workarounds needed: Clean, straightforward configuration without header manipulation

Optional KV Configuration

The top-level KV key is now optional, giving you more flexibility in how you structure your configuration files.

Breaking Changes

⚠️ Important: v2.0 includes several breaking changes that require code updates:

1. Configuration Structure

All configurations must now be passed as an options object (see examples above).

2. Domain References

If you reference domains.variants in your middleware or other code, update it to domains.

// Update this:
locals?.altitude?.runtime?.config?.domains?.variants.includes(...)

// To this:
locals?.altitude?.runtime?.config?.domains?.includes(...)

3. Removed Features

  • Cookie routing has been removed. This feature was deprecated because it was only used by the account repository, which has since migrated to resolving locales directly from the Host request header in production (x-altitude-instance header in local development).
  • Deprecated altitude global context variables: Several global context keys like preferredLocale, and localeCookie are no longer bound to context.altitude.

4. i18n Requirements

  • locales<Object>.domain is now a required property when using i18n. In v1.x, locales could be determined from cookies or URL paths. v2.0 now requires that each localized site has an associated global top-level domain (gTLD). This is now enforced through schema validation, so you will get a build-time error if this key is missing.

Migration Guide

Upgrading to v2.0 is straightforward but requires a few manual steps. Follow our comprehensive migration guide for detailed steps on updating your astro.config.mjs and tenant configurations.

Getting Started with v2.0

If you’re new to the Altitude Astro Integration, v2.0 is the perfect time to get started. Our getting started guide covers both single tenancy and multi-tenancy setups with clear examples.

What’s Next?

We’re already working on exciting new features for future releases. Stay tuned for updates on enhanced i18n capabilities, performance improvements, and fully-fledged path-based i18n support.

Back to all posts