Introducing Massimo

Today marks a significant milestone in the evolution of type-safe API development. What began as @platformatic/client in our v0.19.0 release has grown into something much bigger—a production-proven, enterprise-grade solution now powering companies like Spendesk, who are not only using Massimo in production but actively contributing to its development.

We're thrilled to introduce Massimo (formerly @platformatic/client)—not just a new name, but the next evolution of type-safe API client generation. This relaunch also marks Massimo's independence as standalone packages without the @platformatic scope.

Why "Massimo"?

The name is inspired by Massimo Troisi, the beloved Italian actor from the film "Il Postino" (The Postman). Just as the postman in the movie delivered messages and connected people, Massimo delivers API connections and bridges the gap between services, making communication between applications as effortless and poetic as Troisi's unforgettable performance.

From Prototype to Production

Since its initial release, what started as a developer tool has evolved into an enterprise-grade solution. Massimo has been battle-tested in production environments, with companies like Spendesk relying on it to enhance their frontend and backend development efficiency. This real-world usage has driven continuous improvements, community contributions, and the robust feature set you see today.

Complete Feature Overview

Massimo is a powerful API SDK client and CLI tool for creating fully-typed clients for remote OpenAPI or GraphQL APIs. Here's everything you need to know about its comprehensive, production-proven feature set:

🏗️ Dual Architecture: Library + Generator

Massimo provides two complementary approaches to API client development:

1. Code Generator (massimo-cli)

• Generates standalone, dependency-free client code at build time
• Creates TypeScript/JavaScript files you can commit to your repository
• Perfect for teams who want full control and transparency over their API client code
• Ideal for frontend applications where bundle size matters

2. Runtime Library (massimo)

• Dynamic client creation from schemas at runtime
• Uses the same TypeScript generation engine internally for type safety
• Perfect for server-side applications and rapid prototyping
• Handles schema updates automatically without manual regeneration

The Key Connection: The generator doesn't just create standalone files - it's also the type-safety engine that powers the runtime library. When you use the runtime library, it uses the same code generation logic internally to ensure your API calls are fully typed, even when created dynamically.

This dual approach means you can choose the right strategy for your use case:

• Frontend apps: Use the generator for zero-dependency, optimized bundles
• Backend services: Use the library for dynamic, runtime client creation with generated type safety
• Hybrid projects: Mix both approaches as needed

Both approaches use the same underlying type generation system, ensuring consistency and type safety across your entire application stack.

🚀 Core Features

OpenAPI & GraphQL Support

• Generate typed clients from OpenAPI 3.x specifications with full TypeScript support
• Create GraphQL clients from schemas with automatic type generation
• Support for any backend that exposes OpenAPI or GraphQL endpoints

Type-Safe Development

• Full TypeScript-first development experience
• Automatically generated TypeScript types for complete type safety
• Request and response type validation with detailed error messages
• Support for complex OpenAPI schemas including nested objects and arrays

Framework Integration

• Works seamlessly with any JavaScript framework (Node.js, React, Vue, Angular)
• First-class Fastify plugin for server-side integration
• Browser-compatible clients using native fetch API
• Support for both server and client environments

🛠️ CLI Tool Features

The massimo-cli provides extensive command-line functionality:

Client Generation Options

# Install CLI
npm install -g massimo-cli

# Generate OpenAPI client
massimo http://api.example.com/openapi.json --name myclient

# Generate GraphQL client  
massimo http://api.example.com/graphql --name myclient --type graphql

# Frontend-compatible client
massimo http://api.example.com/openapi.json --frontend --language ts --name myclient

# Types only generation
massimo http://api.example.com/openapi.json --types-only --name myclient

Advanced CLI Options

• --frontend - Generate browser-compatible clients using fetch
• --language js|ts - Choose JavaScript or TypeScript output
• --full-response - Return complete response objects instead of just body
• --full-request - Wrap parameters in body, headers, query structure
• --validate-response - Enable response validation against schema
• --optional-headers - Mark specific headers as optional
• --typescript - Generate TypeScript plugin files
• --with-credentials - Frontend client only: adds credentials: 'include' to fetch calls (learn more about credentials)

📦 Client Library Features

The massimo core library offers programmatic API access:

OpenAPI Client Builder

import { buildOpenAPIClient } from "massimo";

const client = await buildOpenAPIClient({
  url: 'https://api.example.com/openapi.json',
  headers: { Authorization: 'Bearer token' },
  validateResponse: true,
  fullResponse: false,
  throwOnError: true
});

GraphQL Client Builder

import { buildGraphQLClient } from "massimo";

const client = await buildGraphQLClient({
  url: 'https://api.example.com/graphql',
  headers: { Authorization: 'Bearer token' }
});

const result = await client.graphql({
  query: 'mutation { createUser(input: { name: "John" }) { id } }',
  variables: { name: "John" }
});

🔧 Authentication & Security Features

Dynamic Headers

• Support for dynamic header generation via getHeaders function
• Request-specific authentication token handling
• Context-aware header modification

Fastify Plugin Authentication

app.configureMyClient({
  async getHeaders(req, reply) {
    return {
      Authorization: `Bearer ${req.user.token}`,
      'X-User-ID': req.user.id
    };
  }
});

Security Options

• Custom header configuration for protected endpoints
• Support for various authentication schemes (Bearer, API Key, etc.)
• CORS credentials handling for browser clients

🌐 Two Client Types: Server vs Frontend

Massimo generates two fundamentally different types of clients depending on your target environment:

Server-Side Clients (Node.js/Fastify)

Built on Undici for maximum performance and Node.js compatibility:

# Generate server-side client (default)
massimo http://api.example.com/openapi.json --name myclient

Key Features:

• Uses Undici HTTP client for optimal Node.js performance
• Built-in connection pooling and HTTP/2 support
• Advanced timeout controls (body timeout, headers timeout)
• Custom dispatchers and agents for fine-tuned control
• Full telemetry and tracing integration
• Designed for high-throughput server applications

// Server-side client usage
import myClient from './myclient/myclient.js';

const client = await myClient({
  url: 'https://api.example.com',
  bodyTimeout: 30000,
  headersTimeout: 10000,
  dispatcher: customAgent // Custom Undici agent
});

// Works seamlessly in Fastify
app.get('/users', async (request) => {
  return request.myclient.getUsers(); // Automatic telemetry propagation
});

Frontend Clients (Browser/Fetch)

Zero dependencies - uses native browser fetch():

# Generate frontend client
massimo http://api.example.com/openapi.json --frontend --name myclient

Key Features:

• No external dependencies - pure JavaScript/TypeScript
• Uses native browser fetch() API
• Optimized bundle size for frontend applications
• Support for CORS credentials and browser security policies
• Works in any JavaScript environment with fetch support

// Frontend client - two usage patterns available

// Pattern 1: Named operations with global state
import { setBaseUrl, getMovies, setDefaultHeaders } from './api.js';

setBaseUrl('https://api.example.com');
setDefaultHeaders({ Authorization: 'Bearer token' });
const movies = await getMovies({}); // Uses global config

// Pattern 2: Factory approach (isolated instances)
import build from './api.js';

const client = build('https://api.example.com', {
  headers: { Authorization: 'Bearer token' }
});
const movies = await client.getMovies({}); // Self-contained

Bundle Impact:

• Server client: Includes Undici (~200KB) for performance
• Frontend client: Zero dependencies - only your generated code (~5-10KB)

This architectural difference means you can use the same OpenAPI spec to generate both a high-performance server client for your backend services AND a lightweight, dependency-free client for your frontend applications!

🏗️ Advanced Features

Operation Mapping

• Access to OpenAPI operation ID mappings via symbol properties
• Method and path inspection for debugging and tooling

Request/Response Customization

• Custom query parameter parsing
• Request body and header modification
• Full response object access when needed
• Response validation against OpenAPI schemas

Telemetry & Monitoring

• Automatic telemetry propagation in Fastify environments
• Request tracing and performance monitoring
• Built-in error handling with detailed error codes

Error Handling Comprehensive error system with specific error codes:

• PLT_MASSIMO_OPTIONS_URL_REQUIRED - Missing URL in client options
• PLT_MASSIMO_FORM_DATA_REQUIRED - FormData required for multipart requests
• PLT_MASSIMO_MISSING_PARAMS_REQUIRED - Missing required path parameters
• PLT_MASSIMO_INVALID_RESPONSE_SCHEMA - Response validation failure
• And more detailed error scenarios for robust error handling

🏢 Enterprise Adoption & Community

Production Usage Companies like Spendesk are using Massimo to power their production applications, demonstrating its reliability and enterprise readiness. The feedback and contributions from these production deployments have been instrumental in shaping Massimo's evolution.

Community Contributions Massimo benefits from active community involvement, with enterprise users contributing back improvements, bug fixes, and feature requests based on real-world usage patterns.

🔄 Upgrading from @platformatic/client

Package Names

• @platformatic/client → massimo
• @platformatic/client-cli → massimo-cli

CLI Command

• npx @platformatic/client-cli → npx massimo-cli or massimo

Import Statements

// Before
import { buildOpenAPIClient } from '@platformatic/client';
import pltClient from '@platformatic/client/fastify-plugin';

// After  
import { buildOpenAPIClient } from 'massimo';
import pltClient from 'massimo/fastify-plugin';

All existing APIs remain the same - this evolution maintains full backward compatibility!

🚀 Production Ready

Battle-Tested Features

• Used in production environments with proven reliability
• Built-in retry logic and error recovery mechanisms
• Performance optimized for high-throughput applications
• Comprehensive test coverage with end-to-end testing

Development Experience

• Hot-reload support in development environments
• Detailed debugging information and logging
• Integration with popular development tools
• Extensive documentation and examples

Get Started Today

Install Massimo and start generating typed API clients:

# Install CLI globally
npm install -g massimo-cli

# Generate your first client
massimo http://api.example.com/openapi.json --name myclient

# Or use the library directly
npm install massimo

The same powerful features you loved in @platformatic/client are now available as standalone Massimo packages, with continued development and new features coming soon!

Documentation & Resources

• Official Documentation - Complete guides and API reference
• Getting Started Guide
• CLI Reference
• Frontend Client Guide
• Programmatic API
• GitHub Repository

Join our Discord community for support and to connect with other developers using Massimo!