Logto Package Versions: Implications and Best Practices for Version Management

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 defines the workspace constraints, while individual packages like 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 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 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 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.

// 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.

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:

# 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:

# Deploy all pending alterations

pnpm alteration deploy

# For pre-release versions

pnpm alteration deploy next

Reference the 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:

# 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:

pnpm test:integration

Review individual connector changelogs (e.g., 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 for breaking changes, ensure your Node.js version meets the engines.node constraint in root 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}