AngularJS Template Plugin for ESBuild and Vite

Includes your AngularJS templates into your JavaScript bundle. Pre-loads the AngularJS template cache to remove initial load times of templates.

This plugin processes HTML templates and registers them with AngularJS's $templateCache, allowing you to use templateUrl in your directives and components seamlessly.

Primary support: ESBuild plugin for modern Angular projects using @angular-builders/custom-esbuild
Legacy support: Vite plugin for backward compatibility

Install

npm install vite-ngtemplate-loader --save-dev

Usage

ESBuild Configuration (Recommended)

For Angular projects using @angular-builders/custom-esbuild, add the plugin to your esbuild.config.js or esbuild.config.cjs:

const ngTemplatePlugin = require('vite-ngtemplate-loader').default;

module.exports = [
  ngTemplatePlugin({
    module: 'myApp' // Optional: specify your AngularJS module name (defaults to 'ng')
  })
];

Vite Configuration (Legacy)

For Vite projects, add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import { vitePlugin } from 'vite-ngtemplate-loader';

export default defineConfig({
  plugins: [
    vitePlugin({
      module: 'myApp' // Optional: specify your AngularJS module name (defaults to 'ng')
    })
  ]
});

Using in Your Code

Import HTML templates directly in your TypeScript/JavaScript files:

import templatePath from './my-template.html';

app.directive('myDirective', function() {
    return {
        restrict: 'E',
        templateUrl: templatePath
    }
});

The plugin automatically:

1. Processes .html files when they're imported
2. Registers the template content with $templateCache
3. Returns the template path for use with templateUrl

Generated JavaScript

When you import an HTML file, the plugin generates JavaScript code like:

// AngularJS template cache registration for my-template.html
var templateContent = "<div>Your HTML content</div>";
var templatePath = 'my-template.html';
window.angular.module('myApp').run(['$templateCache', function(c) { 
  c.put(templatePath, templateContent); 
}]);
export default templatePath;

Configuration Options

module (optional)

Specify the AngularJS module name where templates should be registered.

ngTemplatePlugin({
  module: 'myApp' // defaults to 'ng'
})

Setup Requirements

Angular on Window Object

Make sure Angular is available on the window object. In your main entry file:

import * as angular from 'angular';

// Make Angular available globally
window.angular = angular;

TypeScript Declaration

For TypeScript support, add this to your type declarations:

declare module '*.html' {
  const path: string;
  export default path;
}

Example Projects

ESBuild Example (Angular + AngularJS Hybrid)

See the example-ng-upgrade/ directory for a modern hybrid app example with:

• Angular + AngularJS hybrid application using UpgradeModule
• @angular-builders/custom-esbuild configuration
• ESBuild plugin integration
• Both inline templates and templateUrl demonstration

To run the ESBuild example:

cd example-ng-upgrade
yarn install
yarn start

Vite Example (Legacy)

See the example/ directory for a Vite-based example with:

• AngularJS 1.x application
• TypeScript support
• Vite configuration
• Template loading demonstration

To run the Vite example:

cd example
yarn install
yarn dev

Migration from webpack ngtemplate-loader

This plugin replaces the webpack ngtemplate-loader for modern build tools. Key differences:

• Configuration: Use ESBuild/Vite plugin configuration instead of webpack loader options
• Import syntax: Import HTML files directly instead of using require with loaders
• Module system: Uses ES modules instead of CommonJS
• Simplified setup: No need for complex loader chains

Before (webpack)

var templateUrl = require('ngtemplate!html!./test.html');

After (ESBuild/Vite)

import templateUrl from './test.html';

API Reference

ESBuild Plugin

import ngTemplatePlugin from 'vite-ngtemplate-loader';
// or
import { ngTemplatePlugin } from 'vite-ngtemplate-loader/esbuild';

Vite Plugin

import { vitePlugin } from 'vite-ngtemplate-loader/vite';

Development

Building the Package

To build the TypeScript source to JavaScript:

yarn build        # Build once
yarn dev          # Build and watch for changes

This compiles the TypeScript files in src/ to JavaScript in dist/ with type declarations.

Running Tests

yarn test         # Run tests once
yarn test:watch   # Run tests in watch mode
yarn test:coverage # Run tests with coverage report
yarn test:ci      # Run tests for CI (no watch, with coverage)

Testing with Example Project

cd example
yarn install
yarn dev          # Start development server
yarn build        # Build for production

Publishing to NPM

Prerequisites

1. Update Version: Update the version in package.json
2. Update Name: Change package name if publishing as a different package
3. Build: Ensure the package builds successfully
4. Test: Run all tests to ensure quality

Publishing Steps

# 1. Clean and build
yarn build

# 2. Run tests to ensure everything works
yarn test

# 3. Test the example to verify functionality  
cd example && yarn build && cd ..

# 4. Publish to NPM (requires npm login)
npm publish

Package Configuration

The package is configured with:

• Main entry: dist/index.js (compiled JavaScript)
• Type definitions: dist/index.d.ts (TypeScript declarations)
• Published files: Only dist/ directory and legacy index.js
• Peer dependencies: Vite 4.x or 5.x (for Vite plugin)

Version Management

Follow semantic versioning:

• Patch (x.x.X): Bug fixes, no breaking changes
• Minor (x.X.x): New features, backward compatible
• Major (X.x.x): Breaking changes

# Update version
yarn version patch    # 2.1.0 -> 2.1.1
yarn version minor    # 2.1.0 -> 2.2.0  
yarn version major    # 2.1.0 -> 3.0.0

Minimal Implementation

This is a minimal implementation focused on core functionality:

• HTML template processing
• Template cache registration
• Basic module name configuration
• TypeScript compatibility

Advanced features from the original webpack loader (like relativeTo, prefix, path manipulation) are not yet implemented but may be added in future versions.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add/update tests as needed
5. Ensure all tests pass
6. Update documentation if needed
7. Submit a pull request

License

MIT (http://www.opensource.org/licenses/mit-license.php)