ts-gyb

ts-gyb is a multi-purpose code generation tool based on TypeScript interfaces. It was initially designed for generating boilerplate interfacing code between web and mobile platforms in hybrid apps. With custom templates, it can generate code for any use from TypeScript.

GYB: Generate Your Boilerplate. Inspired byswift/gyb.py.

Features

• Generate production ready and well documented code from TypeScript code
• Support most of TypeScript syntax
• Fully customizable template makes the generated code fit perfectly into any project

Installation

To use ts-gyb with an existing project managed by npm, it is recommended to install ts-gyb as a dev dependency:

npm install --save-dev ts-gyb

You can also install ts-gyb globally:

npm install --global ts-gyb

Get Started

1. Define TypeScript interfaces

To generate code for a TypeScript interface, add the JSDoc tag@shouldExport trueto documentation of the interface.

/**
* @shouldExport true
*/
interfaceEditorSelection{
getSelectionPath():SelectionPath|null;

// Function can have only one argument and it must be an object
setSelection(args:{selectionPath:SelectionPath}):void;

// Destructuring assignment is allowed
setSelectionAtElement({id,removeElement}:{id:string,removeElement?:boolean}):void;
}

ts-gyb only handles method members likemethodName(): ReturnType;.If a method needs to take in parameters, it must define one object argument. The type of this object can either be an interface or an object literal. For more information on how to write interfaces for ts-gyb, please refer toTypeScript Interface Guide.

2. Provide templates

ts-gyb generates code frommustachetemplates. At least two templates are needed:

• Module template:used to generate a file for every TypeScript interface
• Custom type template:used to generate the file that hosts all TypeScript types found in method parameters or return types

For generating boilerplate interfacing code between web and mobile platforms, a good starting point is theexample templates.You can copy the templates to your project and modify them according to your project's needs.

Please refer toTemplate Guidefor all available variables, andmustache Manualfor mustache template syntax.

3. Create a configuration file

Create a json configuration file in your project:

{
"parsing":{
"targets":{
"default":{
"source":["path/to/interfaces.ts"],
"tsconfigPath":"path/to/tsconfigPath"
}
}
},
"rendering":{
"swift":{
"renders":[
{
"target":"default",
"templates":"path/to/module-interface.mustache",
"outputPath":"path/to/output/directory"
}
],
"namedTypesTemplatePath":"path/to/named-types.mustache",
"namedTypesOutputPath":"path/to/output/directory/SharedTypes.swift"
}
}
}

All paths are relative to the configuration file. For all supported options in the configuration file, please refer toConfiguration Reference.

4. Run ts-gyb

npx ts-gyb --config path/to/config.json

Or if ts-gyb is installed globally:

ts-gyb --config path/to/config.json

Generated code can be found at the output directory specified in the configuration file.

Demos

mini-editorcontains an iOS and an Android rich text editing app. Their editors are powered by the same TypeScript web project.

The web part provides some rich text formatting operations that can be invoked from native code (Kotlin/Swift). The operations are defined inIEditor.ts.ts-gyb generatesEditorBridge.swiftfrom that TypeScript interface.

Documentation

• TypeScript Interface Guide
• Template Guide
• Configuration Reference

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visithttps://cla.opensource.microsoft.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoftwith any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.