Skip to main content

@ttoss/graphql-api-cli

CLI tool that generates GraphQL schemas and TypeScript types from your @ttoss/graphql-api schema composer, enabling seamless integration with Relay and providing type safety for your GraphQL operations.

Installation​

pnpm add -D @ttoss/graphql-api-cli

Core Functionality​

This CLI is essential for GraphQL development workflows using the ttoss ecosystem, providing automated generation of:

  • GraphQL Schema (SDL): Creates schema/schema.graphql file required for Relay introspection queries
  • TypeScript Types: Generates schema/types.ts with strongly-typed interfaces for your GraphQL schema
  • Development Integration: Seamlessly integrates with your build pipeline and development workflow

The tool operates by importing your schemaComposer.ts file, extracting the schema definition, and generating both the SDL schema file and corresponding TypeScript types using GraphQL Code Generator.

Basic Usage​

ttoss-graphql-api build-schema

Add the build script to your package.json for easy integration:

{
  "scripts": {
    "build-schema": "ttoss-graphql-api build-schema"
  }
}

This command:

  1. Reads your src/schemaComposer.ts file
  2. Bundles it using esbuild to resolve all dependencies
  3. Extracts the schema definition using the schemaComposer
  4. Generates schema/schema.graphql in SDL format
  5. Creates schema/types.ts with TypeScript type definitions

Command Options​

Schema Composer Directory (-d, --directory)​

Specify a custom directory for your schemaComposer.ts file:

ttoss-graphql-api build-schema -d src/graphql
ttoss-graphql-api build-schema --directory tests

Default: src

External Dependencies (--external)​

Control which additional dependencies are marked as external during the bundling process:

ttoss-graphql-api build-schema --external graphql-compose,@aws-sdk/client-dynamodb

Default behavior: Automatically excludes all package.json dependencies (except workspace packages and graphql) and appends any specified external dependencies to this list. Workspace dependencies (those with workspace: prefix) are automatically excluded from external handling to prevent bundling issues in monorepo environments. The graphql dependency is always bundled to avoid dynamic require errors.

Integration Examples​

Basic Project Structure​

my-graphql-api/
├── schema/                   # Generated files
│   ├── schema.graphql        # SDL schema
│   └── types.ts              # TypeScript types
├── src/
│   ├── schemaComposer.ts     # Your schema definition
│   └── modules/              # GraphQL modules
└── package.json

Schema Composer Example​

// src/schemaComposer.ts
import { schemaComposer } from '@ttoss/graphql-api';
import './modules/User/composer';
import './modules/Post/composer';

export { schemaComposer };

Advanced Configuration​

For complex projects requiring specific external handling:

# Custom directory with specific externals
ttoss-graphql-api build-schema \
  --directory src/api \
  --external graphql-compose,dataloader,aws-sdk

CI/CD Integration​

{
  "scripts": {
    "build": "pnpm build-schema && pnpm compile",
    "build-schema": "ttoss-graphql-api build-schema",
    "dev": "pnpm build-schema && tsx watch server.ts"
  }
}

Technical Details​

ESM Only: This package is ESM only and requires Node.js with ES modules support.

Bundling Process: Uses esbuild to bundle your schema composer and its dependencies, ensuring all imports are resolved correctly before schema extraction. Automatically excludes all package.json dependencies as external (except workspace packages and graphql), with support for additional external dependencies via the --external option. The graphql package is always bundled to prevent "Dynamic require of 'graphql' is not supported" errors.

Workspace Dependencies: Dependencies with workspace: prefix are automatically excluded from external handling to prevent TypeScript import errors in monorepo environments where workspace packages may export .ts files directly.

Type Generation: Leverages @graphql-codegen/typescript for precise TypeScript type generation with interface declarations and preserved naming conventions.