package
A Heft plugin that generates TypeScript typings for static asset files such as images and text files.
npm install @rushstack/heft-static-asset-typings-pluginGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
This Heft plugin generates TypeScript .d.ts typings for static asset files, enabling type-safe
import statements for non-TypeScript files. It provides two task plugins:
resource-assets-plugin - Generates .d.ts typings for resource files such as images (.png,
.jpg, .svg, etc.) and fonts. These are opaque binary blobs whose content is not meaningful to
JavaScript; the generated typing simply exports a default string representing the asset URL
(e.g. as resolved by a bundler's asset loader).
source-assets-plugin - Generates .d.ts typings and JavaScript module output for source
files (.html, .css, .txt, .md, etc.) whose textual content is consumed at runtime. The
generated JS modules read the file and re-export its content as a default string, making these
assets importable as ES modules.
The terminology follows the webpack convention where resource assets are emitted as separate files referenced by URL, while source assets are inlined as strings.
Both plugins support incremental and watch-mode builds.
Add the plugin as a devDependency of your project:
rush add -p @rushstack/heft-static-asset-typings-plugin --devLoad the appropriate plugin(s) in your project's config/heft.json:
Inline configuration - specify options directly in heft.json:
{
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
"phasesByName": {
"build": {
"tasksByName": {
"image-typings": {
"taskPlugin": {
"pluginPackage": "@rushstack/heft-static-asset-typings-plugin",
"pluginName": "resource-assets-plugin",
"options": {
Both plugins support two configuration modes via the configType option:
configType: "inline")Provide configuration directly in heft.json under options.config:
resource-assets-plugin inline config| Option | Type | Default | Description |
|---|---|---|---|
fileExtensions | string[] | - | (required) File extensions to generate typings for. |
generatedTsFolders | string[] | ["temp/static-asset-ts"] | Folders where generated .d.ts files are written. The first entry should be listed in rootDirs so TypeScript can resolve the asset imports during type-checking. Additional entries are typically your project's published typings folder(s). |
sourceFolderPath | string | "src" | Source folder to scan for asset files. |
source-assets-plugin inline configIncludes all the above, plus:
| Option | Type | Default | Description |
|---|---|---|---|
cjsOutputFolders | string[] | - | (required) Output folders for generated CommonJS .js modules. |
esmOutputFolders | string[] | [] | Output folders for generated ESM .js modules. |
configType: "file")Load configuration from a riggable JSON config file in the project's config/ folder:
| Option | Type | Description |
|---|---|---|
configFileName | string | (required) Name of the JSON config file in the config/ folder. |
The config file supports the same properties as inline mode (see tables above). Config files can be provided by a rig, making file mode ideal for shared build configurations.
Heft is part of the Rush Stack family of projects.
odspnpm
odspnpm@microsoft.com
File configuration - load settings from a riggable config file:
{
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
"phasesByName": {
"build": {
"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"]
// ...
}
}
}
}
}And create a config/resource-assets.json file (which can be provided by a rig):
{
"fileExtensions": [".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico", ".webp", ".avif"],
"generatedTsFolders": ["temp/image-typings"]
}Inline configuration:
{
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
"phasesByName": {
"build": {
"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"]
// ...
}
}
}
}
}File configuration:
{
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
"phasesByName": {
"build": {
"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"]
// ...
}
}
}
}
}And create a config/source-assets.json file (which can be provided by a rig):
{
"fileExtensions": [".html"],
"cjsOutputFolders": ["lib-commonjs"],
"esmOutputFolders": ["lib-esm"],
"generatedTsFolders": ["temp/text-typings"]
}Add the generated typings folder to your tsconfig.json rootDirs so that
TypeScript can resolve the declarations:
{
"compilerOptions": {
"rootDirs": ["src", "temp/image-typings"]
}
}Estimated unpacked size across 40 packages.
7.7 MB
Includes dependencies.
4 direct dependencies.
0.24.8
0.24.8
0.20.18
0.20.18
5.25.2
0.17.10
0.17.10