RFC: Standardizing `.typst-version` files

Proposal

I propose establishing a standard for .typst-version files to explicitly specify the version of the Typst compiler used in Typst projects. This file would be placed in the project's root directory and would simply contain the expected version of the Typst compiler (e.g., 0.13.0) as a text file.

Background

.*-version files, represented by .node-version, .python-version, .ruby-version, and others, have become de facto standards for specifying tool and runtime versions on a per-project basis. These files are supported by version management tools like asdf, mise, and Renovate, and are placed in a project's root directory to ensure developers work in consistent environments.

The Importance of Build Reproducibility in Comparison to LaTeX

One of LaTeX's greatest strengths is its long-term compatibility. Documents created over 30 years ago can often still be built with modern LaTeX systems. This backward compatibility is a crucial characteristic for documents requiring long-term preservation, such as academic papers and books.

Typst has emerged as a modern typesetting system aiming to be an alternative to LaTeX, but it is in a rapid development phase with frequent breaking changes to its syntax. While breaking changes are unavoidable given its pre-1.0 version status, there is growing demand for typesetting with Typst rather than LaTeX while maintaining reproducibility.

In this context, it is important to have a mechanism that explicitly records the version of the Typst compiler used to create a document and enables compilation with specific versions when necessary to ensure future document reproducibility.

Implementation Flexibility

This proposal does not necessarily require the Typst compiler to have built-in version management functionality. The initial goal is to establish a standard file format that third-party tools can utilize. In the future, the Typst compiler itself could potentially add features to read this file, display warnings, or prompt switches to appropriate versions.

Conclusion

The standardization of .typst-version files represents an important step toward Typst's long-term success and document sustainability. Document reproducibility over time is particularly important for users considering migration from LaTeX, and this standardization will help address those needs.

Additionally, I believe this is not the only approach to version specification. I welcome your feedback to refine and improve this proposal.

cf.

• https://github.com/typst/typst/issues/4896
• https://github.com/typst/typst/issues/5157

Start by reading the related issues #4896 and #5157 and the discussion on this RFC. Determine whether the project should standardize the file format and how third-party tools would consume it; done means the proposal has a settled scope and an agreed implementation path.