Automatic TypeScript Model Generation With TDS

November 28, 2022

Index

New Tech, New Problems
TDS Model Generation
The Challenge
The Solution
How to Call The Code
End Result
Future Hacks

New Tech, New Problems

Building stable Sitecore sites with NextJS is best done with TypeScript (not plain JS). Front end developers (FEDs) simply need the IDE feedback that TypeScript provides; particularly around null pointers. In my experience, even if you tell FEDs that there are always cases in which almost any field or item or value can be null, there's just too much to remember. TypeScript is a great way to help FEDs remember.

The future landscape of content serialization and model generation is a bit unclear at the moment. The transition to headless and JS feels like a step backwards in some ways because I haven't yet seen a compelling way to generate TypeScript models from Sitecore. For example, serialization is moving towards Sitecore Content Serialization, but it does not yet support model generation.

This is a problem because many of our sites will have hundreds of templates and perhaps even thousands of fields. Manually creating TypeScript models for all of these is too slow.

"What do you need, Neo?"

"Models. Lots of Models."

Matrix

Matrix Code

TDS Model Generation

One of the great features of TDS is that it supports automatic model generation out of the box. It does so using T4 Text Templates (.tt files). T4 is a code generation tool that is built into Visual Studio. It's a bit tedious to work with, but it's a great way to generate code from other code.

TDS Model Generation

With the click of a single button, or the syncing of a single item, TDS will generate for us a glorious monolithic .cs file containing all of our models:

Monolith Model File

From there, ORM tools such as GlassMapper can be used to map Sitecore items to these models.

The Challenge

I wanted a way to hook into the existing TDS model generation process in a way that was fully automatic so developers wouldn't forget to sync. I also wanted to write directly to a .ts file.

Keep in mind that the templates.tt file runs once per template, but I haven't yet found a OOTB way to track where we are in the loop (start and end is crucial here).

The Solution

If you don't already have TDS code generation set up, be sure to check out the TDS guide on code generation.

Make sure that the top of your common.tt file looks like this:

<#@ template language="C#" debug="true" hostspecific="true" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="System.Linq" #>

Further down, add this:

public static string AppendTypeScriptModelToFile(SitecoreTemplate template, string relativePathToTsModelFile)
{
  var destPath = relativePathToTsModelFile;
  List<string> outputLines = new List<string>();
  DateTime lastModTime = File.GetLastWriteTime(destPath);
  TimeSpan timeSinceLastMod = DateTime.Now - lastModTime;
  // Here is where we get a bit cheeky and take a simple heuristic approach to determining if the loop is just starting
  if (timeSinceLastMod.TotalSeconds >= 45)
  {
    // Clear the file and append header
    System.IO.File.WriteAllText(destPath, string.Empty);
    outputLines.Add("/* eslint-disable */");
    outputLines.Add("/* This file is automatically generated. Manual changes will be overwritten. */");
    outputLines.Add("import { Field, ImageField, Item, LinkField } from '@sitecore-jss/sitecore-jss-nextjs';");
    outputLines.Add("");
    System.IO.File.AppendAllLines(destPath, outputLines);
    outputLines = new List<string>();
  }
  var namespaceParts = template.Namespace.Split('.');
  var indent = new string(' ', namespaceParts.Length * 2);
  for (int i = 0; i < namespaceParts.Length; i++)
  {
    var namespaceName = CleanName(namespaceParts[i]); 
    outputLines.Add(new string(' ', i * 2) + ((i == 0) ? "export namespace " : "export namespace ") + namespaceName + " {");
  }
  outputLines.Add(indent + "/**");
  var templateDescription = GetValue(template.SitecoreFields, "__Short description");
  if (!string.IsNullOrEmpty(templateDescription))
  {
    outputLines.Add(indent + $" * {templateDescription}");
    outputLines.Add(indent + " *");
  }
  outputLines.Add(indent + $" * @interface '{template.Name}'");
  outputLines.Add(indent + $" * @templatepath '{template.Path}'");
  var templateIdStr = template.ID.ToString("B").ToUpperInvariant();
  outputLines.Add(indent + $" * @templateid '{templateIdStr}'");
  outputLines.Add(indent + " */");
  outputLines.Add(indent + $"export interface {GetInterfaceName(template)}{AppendBaseInterfacesTypeScript(template)}"  + " {");
  foreach(SitecoreField field in GetFieldsForTemplate(template, false))
  {
    var fieldId = field.ID.ToString("B").ToUpperInvariant();
    var fieldTypeTS = GetFieldTypeTypeScript(field, true).Replace("|* UNKNOWN *|", "/* UNKNOWN */");
    outputLines.Add(indent + $"  /**");
    outputLines.Add(indent + $"    * @field '{field.Name}'");
    outputLines.Add(indent + $"    * @fieldtype '{field.Type}'");
    outputLines.Add(indent + $"    * @fieldid '{fieldId}'");
    outputLines.Add(indent + $"    */");
    outputLines.Add(indent + $"  {GetPropertyNameTypeScript(field)}: {fieldTypeTS};");
  }
  outputLines.Add(indent + "};");
  outputLines.Add(indent + "/**");
  if (!string.IsNullOrEmpty(templateDescription))
  {
    outputLines.Add(indent + $" * {templateDescription}");
    outputLines.Add(indent + " *");
  }
  outputLines.Add(indent + $" * @type '{template.Name}'");
  outputLines.Add(indent + $" * @templatepath '{template.Path}'");
  outputLines.Add(indent + $" * @templateid '{templateIdStr}'");
  outputLines.Add(indent + $" */");
  outputLines.Add(indent + $"export type {GetTypeName(template)} = " + "{");
  // Pay special attention to the "?" here. This is what will flag possible null ref errors in TypeScript.
  outputLines.Add(indent + $"  id?: string;");
  outputLines.Add(indent + $"  url?: string;");
  outputLines.Add(indent + $"  fields: " + "{");
  foreach(SitecoreField field in GetFieldsForTemplate(template, true))
  {
    var fieldId = field.ID.ToString("B").ToUpperInvariant();
    var fieldTypeTS = GetFieldTypeTypeScript(field, true).Replace("|* UNKNOWN *|", "/* UNKNOWN */");
    outputLines.Add(indent + $"    /**");
    outputLines.Add(indent + $"     * @field '{field.Name}'");
    outputLines.Add(indent + $"     * @fieldtype '{field.Type}'");
    outputLines.Add(indent + $"     * @fieldid '{fieldId}'");
    outputLines.Add(indent + $"     */");
    outputLines.Add(indent + $"    {GetPropertyNameTypeScript(field)}: {fieldTypeTS};");
  }
  outputLines.Add(indent + "  };");
  outputLines.Add(indent + "};");
  for (int i = namespaceParts.Length - 1; i >= 0; i--)
  {
    outputLines.Add(new string(' ', i * 2) + "}");
  }
  System.IO.File.AppendAllLines(destPath, outputLines);
  return string.Empty;
}
#>

How to Call The Code

In your templates.tt file, ensure the header of your file contains:

<#@ template language="C#" debug="true" hostspecific="true" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="HedgehogDevelopment.SitecoreProject.VSIP.CodeGeneration.Models" #>
<#@ parameter name="Model" type="HedgehogDevelopment.SitecoreProject.VSIP.CodeGeneration.Models.SitecoreItem" #>
<#@ parameter name="DefaultNamespace" type="System.String" #>
<#@ include file="Common.tt" #>

If you've set up TDS code generation properly, you will already have plenty of logic in this file. At the bottom of the file, here is how you would make the call to the method we set up in common.tt:

<#
var currentPath = Host.ResolvePath(string.Empty);
var relativePathToTsModelFile = Path.Combine(currentPath, @"..\..\relative\path\to\your\model.ts");
AppendTypeScriptModelToFile(template, relativePathToTsModelFile);
#>

End Result

The output model.ts file will look something like this:

/* eslint-disable */
/* This file is automatically generated. Manual changes will be overwritten. */
import { Field, ImageField, Item, LinkField } from '@sitecore-jss/sitecore-jss-nextjs';
export namespace Website {
  export namespace Foundation {
    export namespace LocalDatasource {
      /**
       * @interface 'Rendering Options'
       * @templatepath '/sitecore/templates/System/Layout/Sections/Rendering Options'
       * @templateid '{D1592226-3898-4CE2-B190-090FD5F84A4C}'
       */
      export interface IRenderingOptions {
        /**
          * @field 'Datasource Location'
          * @fieldtype 'Datasource'
          * @fieldid '{B5B27AF1-25EF-405C-87CE-369B3A004016}'
          */
        datasourceLocation: Field<string> /* UNKNOWN */;
        /**
          * @field 'Detect Content'
          * @fieldtype 'Checkbox'
          * @fieldid '{56A91E93-0B26-44E4-B44F-135FF7879B5B}'
          */
        detectContent: Field<boolean>;
        /**
          * @field 'JSONPath Queries'
          * @fieldtype 'Name Value List'
          * @fieldid '{99A3F0DF-D3BF-4CF5-A919-3D1B09356ADB}'
          */
        jsonPathQueries: Field<string>;
        /**
          * @field 'Supports Local Datasource'
          * @fieldtype 'Checkbox'
          * @fieldid '{017DF358-AC81-4ABF-9801-3617B4667396}'
          */
        supportsLocalDatasource: Field<boolean>;
      };
      /**
       * @type 'Rendering Options'
       * @templatepath '/sitecore/templates/System/Layout/Sections/Rendering Options'
       * @templateid '{D1592226-3898-4CE2-B190-090FD5F84A4C}'
       */
      export type RenderingOptions = {
        id?: string;
        url?: string;
        fields: {
          /**
           * @field 'Datasource Location'
           * @fieldtype 'Datasource'
           * @fieldid '{B5B27AF1-25EF-405C-87CE-369B3A004016}'
           */
          datasourceLocation: Field<string> /* UNKNOWN */;
          /**
           * @field 'Detect Content'
           * @fieldtype 'Checkbox'
           * @fieldid '{56A91E93-0B26-44E4-B44F-135FF7879B5B}'
           */
          detectContent: Field<boolean>;
          /**
           * @field 'JSONPath Queries'
           * @fieldtype 'Name Value List'
           * @fieldid '{99A3F0DF-D3BF-4CF5-A919-3D1B09356ADB}'
           */
          jsonPathQueries: Field<string>;
          /**
           * @field 'Supports Local Datasource'
           * @fieldtype 'Checkbox'
           * @fieldid '{017DF358-AC81-4ABF-9801-3617B4667396}'
           */
          supportsLocalDatasource: Field<boolean>;
        };
      };
    }
  }
}

There you have it; a viable method for automating TS model generation. Now that the ground has been broken, there are many ways that this can be customized / optimized.

Future Hacks

There are also some creative things you can do beyond this. For example, you can run command line commands from .tt files in case you want to do any other kind of post processing after the models have been generated.

The solution below is incomplete, but it's a start:

public static string RunArbitraryCommand()
{
  // Note that if you call this from templates.tt, this will be called MANY times, so you'll want to implement a cheeky solution like what was done in the common.tt file.
  var command = "npm run custom:thing";
  var currentPath = Host.ResolvePath(string.Empty);
  var workingDirectory = Path.Combine(currentPath, @"..\..\relative\path\to\your\package.json");
  var processStartInfo = new ProcessStartInfo()
  {
    FileName = "cmd",
    UseShellExecute = false,
    RedirectStandardOutput = true,
    RedirectStandardInput = true,
    WorkingDirectory = workingDirectory
  };
  var process = Process.Start(processStartInfo);
  if (process == null)
  {
    throw new Exception("Process should not be null.");
  }
  process.StandardInput.WriteLine($"{command} & exit");
  process.WaitForExit();
  var output = process.StandardOutput.ReadToEnd();
    return string.Empty;
}
If you have any comments or suggestions, feel free to reach out.
Keep on innovating,
MG