tessl/npm-grunt-ts

Comprehensive Grunt plugin for TypeScript compilation with advanced development workflow features

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

HTML Template Processing

Name: tessl/npm-grunt-ts
Author: tessl

HTML to TypeScript conversion functionality that transforms HTML files into TypeScript variables, useful for template engines and build-time template compilation.

Capabilities

HTML to TypeScript Conversion

Converts HTML files to TypeScript variables with customizable module and variable naming patterns.

/**
 * Compiles an HTML file to a TypeScript variable
 * @param filename - Path to HTML file to convert
 * @param options - Conversion options for naming and output
 * @returns Path to generated TypeScript file
 */
function compileHTML(filename: string, options: IHtml2TSOptions): string;

interface IHtml2TSOptions {
  /** Template function for generating module names */
  moduleFunction: Function;
  /** Template function for generating variable names */
  varFunction: Function;
  /** Custom output template (overrides default) */
  htmlOutputTemplate?: string;
  /** Output directory for generated TypeScript files */
  htmlOutDir?: string;
  /** Flatten directory structure in output */
  flatten?: boolean;
  /** End-of-line character to use */
  eol?: string;
}

HTML Task Configuration

Configure HTML processing within TypeScript compilation targets.

interface HTMLProcessingConfig {
  /** HTML file glob patterns to process */
  html?: string[];
  /** Output directory for generated TypeScript files */
  htmlOutDir?: string;
  /** Flatten generated files to single directory */
  htmlOutDirFlatten?: boolean;
  /** Template for module names (supports <%= filename %> placeholder) */
  htmlModuleTemplate?: string;
  /** Template for variable names (supports <%= filename %> placeholder) */
  htmlVarTemplate?: string;
  /** Custom TypeScript output template */
  htmlOutputTemplate?: string;
}

Basic Usage Example:

grunt.initConfig({
  ts: {
    default: {
      src: ["src/**/*.ts"],
      html: ["templates/**/*.html"],
      options: {
        htmlModuleTemplate: 'Templates.<%= filename %>',
        htmlVarTemplate: 'content'
      }
    }
  }
});

Module and Variable Templates

Customize how HTML files are converted to TypeScript modules and variables.

// Template placeholders available:
interface TemplateContext {
  filename: string; // Base filename without extension
  // Additional context may be available depending on template
}

// Default templates
const defaultTemplates = {
  htmlModuleTemplate: '<%= filename %>', // Generates: MyTemplate  
  htmlVarTemplate: '<%= filename %>',    // Generates: MyTemplate
  htmlOutputTemplate: `/* tslint:disable:max-line-length */
module <%= modulename %> {
  export var <%= varname %> = '<%= content %>';
}`
};

Advanced Template Example:

ts: {
  templates: {
    src: ["src/**/*.ts"],
    html: ["views/**/*.html", "partials/**/*.html"],
    options: {
      htmlModuleTemplate: 'Views.<%= filename %>',
      htmlVarTemplate: 'template',
      htmlOutDir: 'generated/templates/',
      htmlOutDirFlatten: true
    }
  }
}

This converts views/user/profile.html to:

/* tslint:disable:max-line-length */
module Views.profile {
  export var template = '<div class="profile">...</div>';
}

Custom Output Templates

Override the default TypeScript generation template for specialized use cases.

interface CustomTemplateOptions {
  /** Custom TypeScript output template with placeholders */
  htmlOutputTemplate: string;
}

// Available placeholders in htmlOutputTemplate:
interface OutputTemplateContext {
  modulename: string; // Result of htmlModuleTemplate
  varname: string;    // Result of htmlVarTemplate  
  content: string;    // Escaped HTML content
}

External Module Example:

ts: {
  external: {
    html: ["templates/**/*.html"],
    options: {
      htmlModuleTemplate: 'html',
      htmlVarTemplate: 'markup',
      htmlOutputTemplate: `/* tslint:disable:max-line-length */
export module <%= modulename %> {
  export var <%= varname %> = '<%= content %>';
}`
    }
  }
}

HTML Processing Options

Control HTML content processing and escaping behavior.

interface HTMLContentProcessing {
  /** Character used for string quoting (default: single quote) */
  quoteChar?: string;
  /** Replacement for newlines in HTML content (default: empty string) */
  nlReplace?: string;
  /** Whether to remove BOM from UTF-8 files */
  stripBOM?: boolean;
  /** Convert dashed filenames to camelCase for module names */
  toCamel?: boolean;
}

// Internal processing functions
function escapeContent(content: string, quoteChar?: string): string;
function toCamel(str: string): string;
function stripBOM(str: string): string;

Directory Structure Control

Manage output directory structure for generated TypeScript files.

interface DirectoryControl {
  /** Root directory for generated TypeScript files */
  htmlOutDir?: string;
  /** 
   * Flatten directory structure - all generated files go to htmlOutDir root
   * Without flatten: templates/user/profile.html -> generated/templates/user/profile.html.ts
   * With flatten: templates/user/profile.html -> generated/profile.html.ts
   */
  htmlOutDirFlatten?: boolean;
}

Directory Structure Examples:

// Preserve directory structure
ts: {
  preserve: {
    html: ["views/**/*.html"],
    options: {
      htmlOutDir: "generated/",
      htmlOutDirFlatten: false
    }
  }
}
// Result: views/user/profile.html -> generated/views/user/profile.html.ts

// Flatten to single directory
ts: {
  flatten: {
    html: ["views/**/*.html"],  
    options: {
      htmlOutDir: "generated/",
      htmlOutDirFlatten: true
    }
  }
}
// Result: views/user/profile.html -> generated/profile.html.ts

HTML-Only Processing

Process HTML files without compiling the resulting TypeScript.

interface HTMLOnlyConfig {
  /** Empty source array when only processing HTML */
  src: [];
  /** HTML files to process */
  html: string[];
  /** Disable TypeScript compilation */
  options: {
    compile: false;
  };
}

Usage Example:

ts: {
  htmlOnly: {
    src: [], // Empty - no TypeScript files to compile
    html: ["templates/**/*.html"],
    options: {
      compile: false, // Don't compile the generated .ts files
      htmlModuleTemplate: 'Templates.<%= filename %>',
      htmlOutDir: 'src/generated/'
    }
  }
}

Integration with TypeScript Compilation

HTML processing integrates seamlessly with TypeScript compilation workflow.

// Processing order:
// 1. HTML files are converted to TypeScript
// 2. Generated TypeScript files are added to compilation if they match src globs
// 3. TypeScript compilation proceeds with original + generated files
// 4. Reference files and transforms are processed
// 5. Final compilation occurs

interface IntegrationBehavior {
  /** Generated HTML TypeScript files are automatically included if they match src patterns */
  autoInclude: boolean;
  /** HTML processing occurs before reference file generation */
  processingOrder: "html-first";
  /** Generated files can be excluded from src globs using negation patterns */
  excludeGenerated: string; // e.g., "!generated/**"
}

Complete Integration Example:

ts: {
  fullBuild: {
    src: ["src/**/*.ts", "generated/**/*.ts"], // Include generated HTML files
    html: ["templates/**/*.html"],
    reference: "src/references.ts",
    outDir: "built/",
    options: {
      target: "es5",
      module: "amd",
      htmlModuleTemplate: 'Templates.<%= filename %>',
      htmlOutDir: "generated/templates/"
    }
  }
}

This configuration: