# Logto Package Versions: Implications and Best Practices for Version Management

> Manage Logto package versions effectively in your monorepo to prevent API compatibility failures, missing features, and type errors. Discover best practices for version management.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: best-practices
- Published: 2026-07-06

---

**Using different Logto package versions in a monorepo environment can cause API compatibility failures, missing runtime features, database schema mismatches, and type errors due to tight workspace dependencies.**

Logto is architected as a **monorepo** containing interdependent packages including core, console, connectors, SDKs, and schemas. Because these packages reference each other through workspace protocols and share database schemas, version alignment is critical for system stability. This guide examines the specific implications of version mismatches based on the `logto-io/logto` source code structure.

## Understanding Logto Package Versioning

### Monorepo Structure and Semantic Versioning

Logto follows **semantic versioning** (`MAJOR.MINOR.PATCH`) across all packages. The root [`package.json`](https://github.com/logto-io/logto/blob/main/package.json) defines the workspace constraints, while individual packages like [`packages/core/package.json`](https://github.com/logto-io/logto/blob/main/packages/core/package.json) (currently at version **1.41.0**) declare their own versions and internal dependencies.

In this architecture, **major** version bumps signal breaking changes to functions, endpoints, or types. Minor and patch releases maintain backward compatibility but may introduce behavioral changes such as modified default options or new required parameters.

### Workspace Dependencies

Packages reference siblings using the **workspace protocol** (`"workspace:^"`). For example, [`packages/core/package.json`](https://github.com/logto-io/logto/blob/main/packages/core/package.json) depends on `@logto/connector-kit` and `@logto/js` through workspace links. This means installing a mismatched version of `@logto/core` while retaining older connector kits can cause compile-time type mismatches or runtime errors due to evolved internal contracts.

## Key Implications of Mixed Logto Package Versions

### API Compatibility and Breaking Changes

When the core package increments a major version, underlying APIs may change signatures or behavior. The [`packages/core/CHANGELOG.md`](https://github.com/logto-io/logto/blob/main/packages/core/CHANGELOG.md) documents these changes—for instance, the custom JWT feature introduced in `v1.41.0` added new methods to the core API. Applications using older core versions will lack these capabilities, while code expecting newer APIs will fail against older packages.

### Feature Availability Gaps

New features are gated behind specific versions. **Custom JWT** support, for example, is only available in OSS versions from `1.41.0` onward according to the core changelog. The console UI may check the core version at runtime and enable or disable controls accordingly, meaning version mismatches between core and console packages can result in broken user interfaces or missing functionality.

### Database Migration Mismatches

The `packages/schemas` package ships version-specific migration scripts in `packages/schemas/alterations/`. When the server runs a newer core version, it expects the database to have applied corresponding alteration scripts. Skipping these migrations—such as by upgrading core without running the alteration deploy—causes startup failures or missing column errors.

### Runtime and Dependency Alignment

Certain releases bump the required Node.js version. Commit `2961d355d` introduced a requirement for Node `^22.14.0`, documented in the root [`package.json`](https://github.com/logto-io/logto/blob/main/package.json) engines field. Running an older Node runtime with a newer Logto package aborts the build process immediately.

Additionally, connectors like `@logto/connector-twilio-sms` may change request formats across versions. The Twilio SMS connector updated its webhook payload handling in a minor bump, which breaks integrations if the consuming application expects the legacy shape.

## Version-Specific Considerations

### Core Server Versions

The core server (`@logto/core`) drives the entire system. When upgrading from `1.40.0` to `1.41.0`, you gain access to the custom JWT API but must ensure all dependent packages update simultaneously.

```typescript
// Version 1.40.0 - customJwt does not exist
import { createLogto } from '@logto/core';

const logto = createLogto({
  endpoint: 'https://example.com',
  appId: 'my-app-id',
  // customJwt is undefined here
});

// Version 1.41.0 - customJwt feature available
const logtoNew = createLogto({
  endpoint: 'https://example.com',
  appId: 'my-app-id',
});

logtoNew.customJwt({
  claim: 'role',
  value: 'admin',
});

```

### Connector Package Updates

Connectors follow independent versioning but depend on core contracts. Upgrading `@logto/connector-twilio-sms` to `^2.0.0` may introduce new optional parameters like `fallbackUrl` that weren't available in previous minors.

```typescript
import { TwilioSmsConnector } from '@logto/connector-twilio-sms';

const connector = new TwilioSmsConnector({
  accountSid: process.env.TWILIO_SID!,
  authToken: process.env.TWILIO_TOKEN!,
  from: '+1234567890',
});

// New in minor version: fallbackUrl option
connector.sendSms('+1987654321', 'Your code is 123456', { 
  fallbackUrl: 'https://myapp.com/fallback' 
});

```

### CLI and Tooling Compatibility

The Logto CLI (`@logto/cli`) and translation tools (`@logto/translate`) are version-locked to core. Using an older CLI with a newer core results in mismatched command-line flags or missing sub-commands. Always verify CLI version alignment before running administrative tasks.

## Practical Implementation Guide

### Upgrading All Packages Together

Because of workspace dependencies, cherry-picking individual packages risks type mismatches. Update the entire monorepo using your package manager:

```bash

# Update all workspace packages to the latest tag

pnpm install

```

### Running Database Alterations

After any core version bump, apply pending migrations to align the database schema:

```bash

# Deploy all pending alterations

pnpm alteration deploy

# For pre-release versions

pnpm alteration deploy next

```

Reference the [`packages/schemas/alterations/README.md`](https://github.com/logto-io/logto/blob/main/packages/schemas/alterations/README.md) for the version-based naming scheme used by migration files.

### Validating Node Runtime

Ensure your environment meets the engine constraints specified in root [`package.json`](https://github.com/logto-io/logto/blob/main/package.json):

```bash

# Check current Node version

node --version

# Must satisfy ^22.14.0 for recent releases

```

### Testing Connector Integrations

After upgrading connector packages, run the integration test suite to verify external API contracts:

```bash
pnpm test:integration

```

Review individual connector changelogs (e.g., [`packages/connectors/connector-twilio-sms/CHANGELOG.md`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-twilio-sms/CHANGELOG.md)) for breaking changes in external service integrations.

## Summary

- **Logto package versions** must align across the monorepo due to workspace dependencies using `"workspace:^"` protocols.
- Major version bumps introduce breaking API changes, while minor versions may gate features like **custom JWT** (available from core `1.41.0`).
- Database alterations in `packages/schemas/alterations/` must be deployed after core upgrades to prevent startup failures.
- Node.js version requirements (e.g., `^22.14.0`) are enforced at build time and must match the package expectations.
- Connectors evolve independently but depend on core contracts, requiring integration testing after updates.
- Always upgrade all Logto packages together rather than individually, and verify CLI version compatibility.

## Frequently Asked Questions

### What happens if I mix Logto package versions in my project?

Mixing Logto package versions causes compile-time type errors and runtime failures due to workspace dependency mismatches. The core package expects specific versions of `@logto/connector-kit` and `@logto/js` interfaces. When versions diverge, functions may accept different parameters or return incompatible shapes, resulting in immediate application crashes or silent data corruption.

### How do I safely upgrade Logto to a new version?

Safely upgrade by updating the entire monorepo workspace simultaneously using `pnpm install` after checking out the new tag. Review [`packages/core/CHANGELOG.md`](https://github.com/logto-io/logto/blob/main/packages/core/CHANGELOG.md) for breaking changes, ensure your Node.js version meets the `engines.node` constraint in root [`package.json`](https://github.com/logto-io/logto/blob/main/package.json), and run `pnpm alteration deploy` to apply database migrations. Finally, execute `pnpm test:integration` to verify connector functionality.

### Why is the custom JWT feature missing after upgrading my connector?

The custom JWT feature is implemented in the core package (`@logto/core`), not connectors, and requires version `1.41.0` or higher. If you updated connectors but not core, or if your console package is older than your core version, the feature remains unavailable. The console UI checks the core version to determine feature visibility, so all packages must align to expose new functionality.

### Can I skip database alterations when upgrading Logto packages?

No, skipping database alterations causes startup failures. The core server in `packages/core` expects the database schema to match its version, with specific columns and tables created by scripts in `packages/schemas/alterations/`. When you upgrade core without running `pnpm alteration deploy`, the server encounters missing tables or columns and aborts the initialization process.