Introduce a Heft plugin for generating types for static assets.

README.md

@@ -76,6 +76,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/heft-plugins/heft-sass-load-themed-styles-plugin](./heft-plugins/heft-sass-load-themed-styles-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-sass-load-themed-styles-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-sass-load-themed-styles-plugin) | [changelog](./heft-plugins/heft-sass-load-themed-styles-plugin/CHANGELOG.md) | [@rushstack/heft-sass-load-themed-styles-plugin](https://www.npmjs.com/package/@rushstack/heft-sass-load-themed-styles-plugin) |
 | [/heft-plugins/heft-sass-plugin](./heft-plugins/heft-sass-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-sass-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-sass-plugin) | [changelog](./heft-plugins/heft-sass-plugin/CHANGELOG.md) | [@rushstack/heft-sass-plugin](https://www.npmjs.com/package/@rushstack/heft-sass-plugin) |
 | [/heft-plugins/heft-serverless-stack-plugin](./heft-plugins/heft-serverless-stack-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-serverless-stack-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-serverless-stack-plugin) | [changelog](./heft-plugins/heft-serverless-stack-plugin/CHANGELOG.md) | [@rushstack/heft-serverless-stack-plugin](https://www.npmjs.com/package/@rushstack/heft-serverless-stack-plugin) |
+| [/heft-plugins/heft-static-asset-typings-plugin](./heft-plugins/heft-static-asset-typings-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-static-asset-typings-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-static-asset-typings-plugin) | [changelog](./heft-plugins/heft-static-asset-typings-plugin/CHANGELOG.md) | [@rushstack/heft-static-asset-typings-plugin](https://www.npmjs.com/package/@rushstack/heft-static-asset-typings-plugin) |
 | [/heft-plugins/heft-storybook-plugin](./heft-plugins/heft-storybook-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-storybook-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-storybook-plugin) | [changelog](./heft-plugins/heft-storybook-plugin/CHANGELOG.md) | [@rushstack/heft-storybook-plugin](https://www.npmjs.com/package/@rushstack/heft-storybook-plugin) |
 | [/heft-plugins/heft-typescript-plugin](./heft-plugins/heft-typescript-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-typescript-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-typescript-plugin) | [changelog](./heft-plugins/heft-typescript-plugin/CHANGELOG.md) | [@rushstack/heft-typescript-plugin](https://www.npmjs.com/package/@rushstack/heft-typescript-plugin) |
 | [/heft-plugins/heft-vscode-extension-plugin](./heft-plugins/heft-vscode-extension-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-vscode-extension-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-vscode-extension-plugin) | [changelog](./heft-plugins/heft-vscode-extension-plugin/CHANGELOG.md) | [@rushstack/heft-vscode-extension-plugin](https://www.npmjs.com/package/@rushstack/heft-vscode-extension-plugin) |

build-tests-samples/heft-web-rig-app-tutorial/src/ExampleApp.tsx

@@ -4,6 +4,8 @@
 import * as React from 'react';
 import { ToggleSwitch, type IToggleEventArgs } from 'heft-web-rig-library-tutorial';
 
+import exampleImage from './example-image.png';
+
 /**
  * This React component renders the application page.
  */
@@ -24,10 +26,7 @@ export class ExampleApp extends React.Component {
         <ToggleSwitch leftColor={'#800000'} rightColor={'#008000'} onToggle={this._onToggle} />
 
         <p>Here is an example image:</p>
-        <img
-          // eslint-disable-next-line @typescript-eslint/no-require-imports
-          src={require('./example-image.png')}
-        />
+        <img src={exampleImage} />
       </div>
     );
   }

build-tests/heft-node-everything-esm-module-test/config/heft.json

@@ -9,7 +9,18 @@
       "cleanFiles": [{ "includeGlobs": ["dist", "lib-commonjs", "lib", "lib-esm", "lib-esnext", "lib-umd"] }],
 
       "tasksByName": {
+        "text-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-static-asset-typings-plugin",
+            "pluginName": "source-assets-plugin",
+            "options": {
+              "configType": "file",
+              "configFileName": "source-assets.json"
+            }
+          }
+        },
         "typescript": {
+          "taskDependencies": ["text-typings"],
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft-typescript-plugin"
           }

build-tests/heft-node-everything-esm-module-test/config/source-assets.json

@@ -0,0 +1,6 @@
+{
+  "fileExtensions": [".html"],
+  "cjsOutputFolders": ["lib-commonjs"],
+  "esmOutputFolders": ["lib-esm"],
+  "generatedTsFolders": ["temp/text-typings"]
+}

build-tests/heft-node-everything-esm-module-test/etc/heft-node-everything-esm-module-test.api.md

@@ -4,6 +4,9 @@
 
 ```ts
 
+// @public
+export const templateContent: string;
+
 // @public (undocumented)
 export class TestClass {
 }

build-tests/heft-node-everything-esm-module-test/package.json

@@ -17,6 +17,7 @@
     "@rushstack/heft-api-extractor-plugin": "workspace:*",
     "@rushstack/heft-jest-plugin": "workspace:*",
     "@rushstack/heft-lint-plugin": "workspace:*",
+    "@rushstack/heft-static-asset-typings-plugin": "workspace:*",
     "@rushstack/heft-typescript-plugin": "workspace:*",
     "@types/heft-jest": "1.0.1",
     "@types/node": "20.17.19",

build-tests/heft-node-everything-esm-module-test/src/exampleTemplate.html

@@ -0,0 +1 @@
+<p>This is an example template imported as a text asset.</p>

build-tests/heft-node-everything-esm-module-test/src/index.ts

@@ -1,6 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import exampleTemplate from './exampleTemplate.html';
+
+/**
+ * The content of exampleTemplate.html, imported as a text asset.
+ * @public
+ */
+export const templateContent: string = exampleTemplate;
+
 /**
  * @public
  */

build-tests/heft-node-everything-esm-module-test/tsconfig.json

@@ -4,7 +4,7 @@
   "compilerOptions": {
     "outDir": "lib-commonjs",
     "declarationDir": "lib-dts",
-    "rootDir": "src",
+    "rootDirs": ["src", "temp/text-typings"],
 
     "forceConsistentCasingInFileNames": true,
     "jsx": "react",

build-tests/heft-node-everything-test/config/heft.json

@@ -16,7 +16,23 @@
       "cleanFiles": [{ "includeGlobs": ["dist", "lib-commonjs", "lib", "lib-esm", "lib-esnext", "lib-umd"] }],
 
       "tasksByName": {
+        "text-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-static-asset-typings-plugin",
+            "pluginName": "source-assets-plugin",
+            "options": {
+              "configType": "inline",
+              "config": {
+                "fileExtensions": [".html"],
+                "cjsOutputFolders": ["lib-commonjs"],
+                "esmOutputFolders": ["lib-esm"],
+                "generatedTsFolders": ["temp/text-typings"]
+              }
+            }
+          }
+        },
         "typescript": {
+          "taskDependencies": ["text-typings"],
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft-typescript-plugin"
           }

build-tests/heft-node-everything-test/config/jest.config.json

@@ -1,6 +1,9 @@
 {
   "extends": "@rushstack/heft-jest-plugin/includes/jest-shared.config.json",
 
+  "roots": ["<rootDir>/lib-commonjs"],
+  "testMatch": ["<rootDir>/lib-commonjs/**/*.test.{cjs,js}"],
+
   // Enable code coverage for Jest
   "collectCoverage": true,
   "coverageDirectory": "<rootDir>/coverage",

build-tests/heft-node-everything-test/config/rush-project.json

@@ -4,7 +4,7 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["dist", "lib-commonjs", "lib-esm", "lib-umd", "lib-dts"]
+      "outputFolderNames": ["dist", "lib-commonjs", "lib-esm", "lib-umd", "lib-dts", "temp/text-typings"]
     },
     {
       "operationName": "_phase:test",

build-tests/heft-node-everything-test/config/source-assets.json

@@ -0,0 +1,4 @@
+{
+  "fileExtensions": [".html"],
+  "generatedTsFolder": "temp/text-typings"
+}

build-tests/heft-node-everything-test/etc/heft-node-everything-test.api.md

@@ -4,6 +4,9 @@
 
 ```ts
 
+// @public
+export const templateContent: string;
+
 // @public (undocumented)
 export class TestClass {
 }

build-tests/heft-node-everything-test/package.json

@@ -16,6 +16,7 @@
     "@microsoft/api-extractor": "workspace:*",
     "@rushstack/heft": "workspace:*",
     "@rushstack/heft-api-extractor-plugin": "workspace:*",
+    "@rushstack/heft-static-asset-typings-plugin": "workspace:*",
     "@rushstack/heft-jest-plugin": "workspace:*",
     "@rushstack/heft-lint-plugin": "workspace:*",
     "@rushstack/heft-typescript-plugin": "workspace:*",

build-tests/heft-node-everything-test/src/exampleTemplate.html

@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Example Template</title>
+  </head>
+  <body>
+    <p>Hello, world!</p>
+  </body>
+</html>

build-tests/heft-node-everything-test/src/index.ts

@@ -1,6 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import exampleTemplate from './exampleTemplate.html';
+
+/**
+ * The content of exampleTemplate.html, imported as a text asset.
+ * @public
+ */
+export const templateContent: string = exampleTemplate;
+
 /**
  * @public
  */

build-tests/heft-node-everything-test/src/test/ExampleTest.test.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { templateContent } from '../index';
+
 interface IInterface {
   element: string;
 }
@@ -20,4 +22,10 @@ describe('Example Test', () => {
     };
     expect(interfaceInstance).toBeTruthy();
   });
+
+  it('Correctly imports text assets', () => {
+    expect(typeof templateContent).toBe('string');
+    expect(templateContent).toContain('<title>Example Template</title>');
+    expect(templateContent).toContain('Hello, world!');
+  });
 });

build-tests/heft-node-everything-test/tsconfig.json

@@ -5,6 +5,7 @@
     "outDir": "lib-commonjs",
     "declarationDir": "lib-dts",
     "rootDir": "src",
+    "rootDirs": ["src", "temp/text-typings"],
 
     "forceConsistentCasingInFileNames": true,
     "jsx": "react",

build-tests/heft-rspack-everything-test/config/heft.json

@@ -10,7 +10,21 @@
       "cleanFiles": [{ "includeGlobs": ["dist", "lib", "lib-commonjs"] }],
 
       "tasksByName": {
+        "image-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-static-asset-typings-plugin",
+            "pluginName": "resource-assets-plugin",
+            "options": {
+              "configType": "inline",
+              "config": {
+                "fileExtensions": [".png"],
+                "generatedTsFolders": ["temp/image-typings"]
+              }
+            }
+          }
+        },
         "typescript": {
+          "taskDependencies": ["image-typings"],
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft-typescript-plugin"
           }

build-tests/heft-rspack-everything-test/config/rush-project.json

@@ -4,7 +4,7 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["lib-esm", "lib-commonjs", "dist"]
+      "outputFolderNames": ["lib-esm", "lib-commonjs", "dist", "temp/image-typings"]
     },
     {
       "operationName": "_phase:test",

build-tests/heft-rspack-everything-test/package.json

@@ -12,6 +12,7 @@
   },
   "devDependencies": {
     "@rushstack/heft-dev-cert-plugin": "workspace:*",
+    "@rushstack/heft-static-asset-typings-plugin": "workspace:*",
     "@rushstack/heft-jest-plugin": "workspace:*",
     "@rushstack/heft-lint-plugin": "workspace:*",
     "@rushstack/heft-typescript-plugin": "workspace:*",

build-tests/heft-rspack-everything-test/tsconfig.json

@@ -3,9 +3,8 @@
 
   "compilerOptions": {
     "outDir": "lib-esm",
-    "rootDir": "src",
+    "rootDirs": ["src", "temp/image-typings"],
 
-    "allowArbitraryExtensions": true,
     "forceConsistentCasingInFileNames": true,
     "esModuleInterop": true,
     "allowSyntheticDefaultImports": true,

build-tests/heft-webpack4-everything-test/config/heft.json

@@ -10,7 +10,18 @@
       "cleanFiles": [{ "includeGlobs": ["dist", "lib", "lib-commonjs"] }],
 
       "tasksByName": {
+        "image-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-static-asset-typings-plugin",
+            "pluginName": "resource-assets-plugin",
+            "options": {
+              "configType": "file",
+              "configFileName": "resource-assets.json"
+            }
+          }
+        },
         "typescript": {
+          "taskDependencies": ["image-typings"],
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft-typescript-plugin"
           }

build-tests/heft-webpack4-everything-test/config/resource-assets.json

@@ -0,0 +1,4 @@
+{
+  "fileExtensions": [".png"],
+  "generatedTsFolders": ["temp/image-typings"]
+}

build-tests/heft-webpack4-everything-test/config/rush-project.json

@@ -4,7 +4,7 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["lib-esm", "lib-commonjs", "dist"]
+      "outputFolderNames": ["lib-esm", "lib-commonjs", "dist", "temp/image-typings"]
     },
     {
       "operationName": "_phase:test",

build-tests/heft-webpack4-everything-test/package.json

@@ -11,6 +11,7 @@
   },
   "devDependencies": {
     "@rushstack/heft-dev-cert-plugin": "workspace:*",
+    "@rushstack/heft-static-asset-typings-plugin": "workspace:*",
     "@rushstack/heft-jest-plugin": "workspace:*",
     "@rushstack/heft-lint-plugin": "workspace:*",
     "@rushstack/heft-typescript-plugin": "workspace:*",

build-tests/heft-webpack4-everything-test/src/chunks/ChunkClass.ts

@@ -1,14 +1,15 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import image from './image.png';
+
 export class ChunkClass {
   public doStuff(): void {
     // eslint-disable-next-line no-console
     console.log('CHUNK');
   }
 
   public getImageUrl(): string {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    return require('./image.png');
+    return image;
   }
 }

build-tests/heft-webpack4-everything-test/tsconfig.json

@@ -3,9 +3,11 @@
 
   "compilerOptions": {
     "outDir": "lib-esm",
-    "rootDir": "src",
+    "rootDirs": ["src", "temp/image-typings"],
 
     "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
     "jsx": "react",
     "declaration": true,
     "sourceMap": true,

build-tests/heft-webpack5-everything-test/config/heft.json

@@ -10,7 +10,21 @@
       "cleanFiles": [{ "includeGlobs": ["dist", "lib", "lib-commonjs"] }],
 
       "tasksByName": {
+        "image-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-static-asset-typings-plugin",
+            "pluginName": "resource-assets-plugin",
+            "options": {
+              "configType": "inline",
+              "config": {
+                "fileExtensions": [".png"],
+                "generatedTsFolders": ["temp/image-typings"]
+              }
+            }
+          }
+        },
         "typescript": {
+          "taskDependencies": ["image-typings"],
           "taskPlugin": {
             "pluginPackage": "@rushstack/heft-typescript-plugin"
           }

build-tests/heft-webpack5-everything-test/config/rush-project.json

@@ -4,7 +4,7 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["lib-esm", "lib-commonjs", "dist"]
+      "outputFolderNames": ["lib-esm", "lib-commonjs", "dist", "temp/image-typings"]
     },
     {
       "operationName": "_phase:test",

build-tests/heft-webpack5-everything-test/package.json

@@ -13,6 +13,7 @@
   },
   "devDependencies": {
     "@rushstack/heft-dev-cert-plugin": "workspace:*",
+    "@rushstack/heft-static-asset-typings-plugin": "workspace:*",
     "@rushstack/heft-jest-plugin": "workspace:*",
     "@rushstack/heft-lint-plugin": "workspace:*",
     "@rushstack/heft-typescript-plugin": "workspace:*",