tessl/npm-ts-json-schema-generator

Generate JSON schema from your TypeScript sources with extensive customization options

—

Pending

Overview

Eval results

Files

CLI Usage

Name: tessl/npm-ts-json-schema-generator
Author: tessl

Command-line interface with comprehensive options for batch processing, automation, and integration into build pipelines.

Capabilities

Basic CLI Usage

Run the schema generator directly with npx or as an installed binary.

# Run with npx (no installation required)
npx ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'

# Install and run locally
npm install ts-json-schema-generator
./node_modules/.bin/ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'

# Global installation
npm install -g ts-json-schema-generator
ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'

Core CLI Options

Essential options for specifying input sources and target types.

# Required options
-p, --path <path>      # Source file path or glob pattern
-t, --type <name>      # Type name to generate schema for

# Configuration options  
-f, --tsconfig <path>  # Custom tsconfig.json path
-i, --id <name>        # $id for generated schema
-o, --out <file>       # Output file (default: stdout)

Basic Examples:

# Generate schema for specific type
ts-json-schema-generator --path 'src/api.ts' --type 'ApiResponse'

# Generate schemas for all exported types
ts-json-schema-generator --path 'src/**/*.ts' --type '*'

# Use custom tsconfig and output to file
ts-json-schema-generator \
  --path 'src/**/*.ts' \
  --type 'User' \
  --tsconfig './tsconfig.schema.json' \
  --out 'schemas/user.json'

# Add schema ID
ts-json-schema-generator \
  --path 'src/types.ts' \
  --type 'Product' \
  --id 'https://example.com/schemas/product'

Type Exposure Options

Control which types are included in the generated schema.

-e, --expose <expose>  # Type exposing (choices: "all", "none", "export", default: "export")

Exposure Examples:

# Only exported types (default)
ts-json-schema-generator --path 'src/**/*.ts' --type '*' --expose export

# All types including internal ones
ts-json-schema-generator --path 'src/**/*.ts' --type '*' --expose all

# No type definitions in schema
ts-json-schema-generator --path 'src/api.ts' --type 'Response' --expose none

JSDoc Processing Options

Configure how JSDoc annotations are processed and included in schemas.

-j, --jsDoc <extended>        # Read JsDoc annotations (choices: "none", "basic", "extended", default: "extended")
--markdown-description        # Generate `markdownDescription` in addition to `description`

JSDoc Examples:

# Full JSDoc processing (default)
ts-json-schema-generator --path 'src/api.ts' --type 'User' --jsDoc extended

# Basic JSDoc only
ts-json-schema-generator --path 'src/api.ts' --type 'User' --jsDoc basic

# No JSDoc processing
ts-json-schema-generator --path 'src/api.ts' --type 'User' --jsDoc none

# Include markdown descriptions
ts-json-schema-generator \
  --path 'src/api.ts' \
  --type 'User' \
  --jsDoc extended \
  --markdown-description

Schema Format Options

Control the output format and structure of generated schemas.

--minify                      # Minify generated schema (default: false)
--unstable                    # Do not sort properties
--strict-tuples               # Do not allow additional items on tuples
--no-top-ref                  # Do not create a top-level $ref definition
--additional-properties       # Allow additional properties for objects with no index signature (default: false)

Format Examples:

# Minified output
ts-json-schema-generator --path 'src/api.ts' --type 'User' --minify

# Unsorted properties (preserve source order)  
ts-json-schema-generator --path 'src/api.ts' --type 'User' --unstable

# Strict tuple handling
ts-json-schema-generator --path 'src/types.ts' --type 'Coordinates' --strict-tuples

# No top-level reference
ts-json-schema-generator --path 'src/api.ts' --type 'User' --no-top-ref

# Allow additional properties
ts-json-schema-generator --path 'src/api.ts' --type 'User' --additional-properties

Performance Options

Options to improve generation speed for large codebases.

--no-type-check               # Skip type checks to improve performance

Performance Examples:

# Fast generation (skip type checking)
ts-json-schema-generator \
  --path 'src/**/*.ts' \
  --type '*' \
  --no-type-check

# Full type safety (default)
ts-json-schema-generator \
  --path 'src/**/*.ts' \
  --type '*'

Advanced Options

Specialized options for custom schema generation needs.

--functions <functions>              # How to handle functions (choices: "fail", "comment", "hide", default: "comment")
--no-ref-encode                      # Do not encode references
--validation-keywords [value]        # Provide additional validation keywords to include (default: [])

Advanced Examples:

# Hide function types
ts-json-schema-generator --path 'src/api.ts' --type 'Config' --functions hide

# Fail on function types
ts-json-schema-generator --path 'src/api.ts' --type 'Config' --functions fail

# Don't encode references
ts-json-schema-generator --path 'src/api.ts' --type 'User' --no-ref-encode

# Include custom validation keywords
ts-json-schema-generator \
  --path 'src/api.ts' \
  --type 'User' \
  --validation-keywords format \
  --validation-keywords pattern

Help and Version

Get CLI help and version information.

-V, --version                 # Output the version number
-h, --help                    # Display help for command

Complete CLI Examples

Real-world usage scenarios combining multiple options.

API Schema Generation:

ts-json-schema-generator \
  --path 'src/api/**/*.ts' \
  --type '*' \
  --tsconfig './tsconfig.json' \
  --jsDoc extended \
  --markdown-description \
  --out 'dist/api-schemas.json' \
  --id 'https://api.example.com/schemas' \
  --additional-properties \
  --validation-keywords format \
  --validation-keywords pattern

Fast Development Build:

ts-json-schema-generator \
  --path 'src/types.ts' \
  --type 'UserProfile' \
  --no-type-check \
  --minify \
  --functions hide \
  --out 'temp/user-schema.json'

Strict Production Build:

ts-json-schema-generator \
  --path 'src/**/*.ts' \
  --type '*' \
  --tsconfig './tsconfig.prod.json' \
  --expose export \
  --jsDoc extended \
  --strict-tuples \
  --functions fail \
  --out 'dist/schemas/complete.json'

Path Pattern Guidelines

Best practices for path patterns and file selection.

# Single file
--path 'src/types.ts'

# All TypeScript files in directory  
--path 'src/*.ts'

# Recursive directory search
--path 'src/**/*.ts'

# Multiple patterns (use multiple --path options or shell expansion)
--path 'src/**/*.ts' --path 'lib/**/*.ts'

# Quote patterns to prevent shell expansion
--path 'src/**/*.ts'  # Good
--path src/**/*.ts    # Bad - shell will expand before passing to CLI

Output Handling

Control where generated schemas are written.

# Write to stdout (default)
ts-json-schema-generator --path 'src/api.ts' --type 'User'

# Write to file
ts-json-schema-generator --path 'src/api.ts' --type 'User' --out 'user.schema.json'

# Create output directories automatically
ts-json-schema-generator --path 'src/api.ts' --type 'User' --out 'schemas/api/user.json'

Error Handling

CLI error handling and exit codes.

# Exit code 0: Success
# Exit code 1: Error (type errors, file not found, etc.)

# Capture errors in scripts
if ! ts-json-schema-generator --path 'src/api.ts' --type 'User'; then
  echo "Schema generation failed"
  exit 1
fi

Integration Examples

Common integration patterns for build tools and CI/CD.

npm scripts:

{
  "scripts": {
    "build:schemas": "ts-json-schema-generator --path 'src/**/*.ts' --type '*' --out 'dist/schemas.json'",
    "dev:schemas": "ts-json-schema-generator --path 'src/**/*.ts' --type '*' --no-type-check --out 'temp/schemas.json'"
  }
}

Makefile:

schemas:
	ts-json-schema-generator \
		--path 'src/**/*.ts' \
		--type '*' \
		--tsconfig './tsconfig.json' \
		--out 'dist/schemas.json'

.PHONY: schemas

GitHub Actions:

- name: Generate schemas
  run: |
    npx ts-json-schema-generator \
      --path 'src/**/*.ts' \
      --type '*' \
      --out 'dist/schemas.json'

Install with Tessl CLI

npx tessl i tessl/npm-ts-json-schema-generator

docs

program-management.md

schema-generation.md

type-formatting.md

tile.json