@xenorange/esbuild-plugin-faces-resource-loader/dist/index.d.ts

ESBuild plugin for Faces (formerly JSF) resources, intended only for CSS files. Writes resources to an external directory, and replaces the URL with a Faces resource expression.

/**
 * Plugin for esbuild that modifies the URL of imported resources in CSS files
 * to Faces resource expressions.
 *
 * esbuild plugin for Faces resources. Jakarta Faces uses a custom resource loading
 * mechanism via the Faces servlet. When a CSS file wishes to reference e.g. an image
 * or font, it must use a special EL expression to refer to the resource, e.g.
 * `#{resource['library:file/path.txt']}`.
 *
 * This plugin adjust the URL of referenced resources accordingly. This allows authors
 * to use normal relative paths in CSS files, such as `url(../images/image.png)`, and
 * have them automatically adjusted to the Faces resource expression during build time.
 *
 * Usage:
 *
 * ```js
 * import { facesResourceLoaderPlugin } from "@xenorange/esbuild-plugin-faces-resource-loader";
 * esbuild.build({
 *     entryPoints: ["src/index.js"],
 *     bundle: true,
 *     // ...your other settings...
 *     plugins: [
 *         facesResourceLoaderPlugin({
 *             // Resources to which the plugin should apply
 *             extensions: ["png", "gif", "jpg", "jpeg", "svg", "woff", "woff2", "ttf", "eot"],
 *
 *             // Directory for input and output files. Used to construct the relative path
 *             // when copying files to the output directory.
 *             inputDir: "src/main/frontend/src",
 *             outputDir: "target/generated-resources/META-INF/resources/library",
 *
 *             // Base directory of the webapp resources, used to create the resource expression.
 *             resourceBase: "target/generated-resources/META-INF/resources",
 *
 *             // Whether to use the library name in the resource expression.
 *             // true:  #{resource['library:file/path.txt']}
 *             // false: #{resource['library/file/path.txt']}
 *             useLibrary: true,
 *         }),
 *     ],
 * });
 * ```
 *
 * @param {FacesResourceLoaderPluginOptions} options Options for adjusting this plugin.
 * @returns {Plugin} A new plugin that copies resources to the output directory and
 * adjusts the URLs in CSS files to Faces resource expressions.
 */
export function facesResourceLoaderPlugin(options: FacesResourceLoaderPluginOptions): Plugin;
/**
 * Options for the Faces
 * resource loader esbuild plugin.
 */
export type FacesResourceLoaderPluginOptions = {
    /**
     * File extensions of resources to
     * which the plugin should apply, without the leading period (`.`).
     */
    extensions: readonly string[];
    /**
     * Directory for input files. Used find which sub
     * folders to create when copying files to the output directory. This is usually
     * the root of the resources in your source directory. For example,
     * `src/main/frontend/src`. Relative paths are resolved against the [esbuild
     * working directory](https://esbuild.github.io/api/#working-directory).
     */
    inputDir: string;
    /**
     * Directory for output files. Used to find which
     * sub folders to create when copying files to the output directory. This is the
     * root of the resources  in your target directory. For example,
     * `target/generated-resources/META-INF/resources/library`. Relative paths are
     * resolved against the
     * [esbuild working directory](https://esbuild.github.io/api/#working-directory)
     */
    outputDir: string;
    /**
     * Base directory of the webapp resources, used
     * to create the resource expression. For example,
     * `target/generated-resources/META-INF/resources`. Relative paths are resolved
     * against the
     * [esbuild working directory](https://esbuild.github.io/api/#working-directory)
     */
    resourceBase: string;
    /**
     * Whether to use the library name in the
     * resource expression. For example, when set to `true`, it might generate
     * `#{resource['library:file/path.png']}`. When set to `false`, it might
     * generate `#{resource['library/file/path.png']}`.
     */
    useLibrary: boolean;
    /**
     * Alternative output directory when a file is
     * from an NPM modules. See `outputDir` for more details. Defaults to
     * `outputDir`.
     */
    npmOutputDir?: string | undefined;
    /**
     * Prefix for files from NPM modules.
     * When given, this prefix is added before the output file path, after
     * the `npmOutputDir`. Defaults to `vendor`. Set to empty string to disable.
     */
    npmPrefix?: string | undefined;
    /**
     * Suppresses any logging output.
     */
    quiet?: boolean | undefined;
};
import type { Plugin } from "esbuild";