@jackdbd/zod-to-doc

Zod to Doc

Inject your Zod schemas into your docs.

• About
• Installation
• Docs
• Examples
  • Usage as a CLI
    • Car table
  • Usage as a library
    • Car tire table
• Troubleshooting
• Dependencies
• License

About

I was looking for a way to keep my documentation updated with my Zod schemas. To my surprise, I couldn't find any tool that would output a string representation of a Zod schema. So I decided to write my own. You can use this tool either as a library or as a CLI.

Installation

npm install --save-dev @jackdbd/zod-to-doc

Docs

Docs generated by TypeDoc

📖 API Docs

This project uses API Extractor and api-documenter markdown to generate a bunch of markdown files and a .d.ts rollup file containing all type definitions consolidated into a single file. I don't find this .d.ts rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.

See Generating API docs if you want to know more.

Examples

Here are some tables generated using a couple of Zod schemas exported by fixtures/schemas.mjs.

Usage as a CLI

Zod to Doc can be used as a CLI. For example, if you run this command and have the correct placeholder in your document (see this README.md in raw mode):

ztd --module ./fixtures/schemas.mjs \
  --schema car \
  --placeholder car-table \
  --title '#### Car table'

You get this output:

Car table

Key	Default	Description
manufacturer	undefined	Car manufacturer
model	undefined	Car model
tires	undefined	Array of 4 elements
year	undefined	Year in which the car was manufactured

Usage as a library

Zod to Doc can also be used as a library. For example, the readme.ts file in this repository uses markdownTableFromZodSchema to replace a mustache-style placeholder with this markdown table:

Car tire table

Key	Default	Description
manufacturer	undefined	Car tire manufacturer
pressure	30	Car tire pressure in PSI

Troubleshooting

This package uses the debug library for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

# print all logging statements
export DEBUG=ztd:*

Dependencies

Package	Version
ansi-colors	^4.1.3
debug	^4.3.4
yargs	^17.7.2
zod	^3.22.4

License

© 2024 Giacomo Debidda // MIT License

Changelog

1.1.0 (2024-04-25)

Features

• render any z.union() as strings (e95b108)