@playform/compress

The Compress Astro integration provides several compression utilities for your statically generated builds and pre-rendered routes.

Supported formats:

• CSS: via csso and lightningcss
• HTML: via html-minifier-terser
• Image: via sharp
• JavaScript: via terser
• SVG: via svgo
• JSON

IMPORTANT

Use Compress last in your integration list to ensure it can optimize the output of other integrations.

Note: Compress does not compress network requests; it only optimizes your static build files and pre-rendered routes.

You can install the @playform/compress integration using the Astro CLI or by manual installation.

Using astro add (Recommended)

Run the following command in your project directory and follow the prompts to automatically install dependencies and update your astro.config.* file:

npx astro add @playform/compress

(Or use yarn astro add @playform/compress or pnpx astro add @playform/compress depending on your package manager.)

Manual Installation

1. Install the package as a development dependency:

   npm install -D -E @playform/compress

2. Add the integration to your astro.config.* file:

   export default {
     integrations: [(await import("@playform/compress")).default()],
   };

Use the Exclude option to prevent specific files from being compressed. The Exclude property accepts an array containing:

• Strings: Exact file name matches.
• Regular Expressions: Pattern-based matches.
• Functions: Custom logic that takes a File: string argument and returns a boolean.

export default {
	integrations: [
		(await import("@playform/compress")).default({
			Exclude: [
				"File.png",
				(File: string) =>
					File === "./Target/Favicon/Image/safari-pinned-tab.svg",
			],
		}),
	],
};

Adjust the level of detail in the console output using the Logger parameter.

• The default value is 2.
• Set Logger: 0 to disable debug messages and reduce log noise.

export default {
	integrations: [
		(await import("@playform/compress")).default({
			Logger: 0,
		}),
	],
};

By default, the utility compresses the Astro outDir. You can customize which directories are processed using the Path option.

Single or Multiple Paths

Pass a string or an array of strings to specify one or more directories to compress.

Input-Output Mapping

To compress files from one directory into a different target directory, use a Map or an array containing a Map. This allows you to define specific source-to-destination relationships.

You can mix standard paths and maps within a single Path array.

// Multiple paths
Path: ["./dist", "./Compress"]

// Input-Output Mapping using a Map
Path: new Map([["./Source", "./Target"]])

// Mixed: Compress one directory, and map another to a different target
Path: [
	"./Target",
	new Map([["./Target", "./TargetCompress"]]),
]

The @playform/compress plugin supports the following file types, each utilizing specific underlying tools:

For Images, the plugin uses sharp. It automatically detects if an image is animated (like webp or gif) to set appropriate flags.

If you encounter a build error where a requested module from @astrojs/internal-helpers is missing an export (e.g., collapseDuplicateLeadingSlashes), it is likely due to a version mismatch caused by a pinned dependency in an integration.

You can resolve this by adding an overrides block to your project's package.json to force the correct version of the internal helper.

{
	"overrides": {
		"@astrojs/internal-helpers": "0.8.0"
	}
}

The Interface provides a programmatic way to invoke the compression process. It accepts an array of file patterns to compress and an optional pattern for the output directory or destination. The function returns a Promise<void> that resolves when the compression task is complete.

// The interface signature:
// (File: Pattern[], Compress?: Pattern): Promise<void>;

The following symbols are exported from the integration entrypoint:

• Default: The default configuration object used when options are not provided.
• Merge: A utility function for merging configuration objects.
• Search: A constant used to indicate that the cache search should target the build directory.
• System: The system-relative path context.
• _Action: The internal action object used during the compression lifecycle.
• default: The main plugin function used for integration.