diff --git a/packages/docs/docs/guide/configuration.md b/packages/docs/docs/guide/configuration.md index c2571b4..32a35fc 100644 --- a/packages/docs/docs/guide/configuration.md +++ b/packages/docs/docs/guide/configuration.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 1 --- # Configuration diff --git a/packages/docs/docs/guide/pipes/_category_.yml b/packages/docs/docs/guide/pipes/_category_.yml index 7de1e06..b74091a 100644 --- a/packages/docs/docs/guide/pipes/_category_.yml +++ b/packages/docs/docs/guide/pipes/_category_.yml @@ -1,3 +1,3 @@ label: Optimisations -position: 1 +position: 2 collapsed: false diff --git a/packages/docs/docs/guide/pipes/cache-buster.md b/packages/docs/docs/guide/pipes/cache-buster.md deleted file mode 100644 index 75b4d94..0000000 --- a/packages/docs/docs/guide/pipes/cache-buster.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Cache Buster - -AssetPack plugin for generating hashes and appending them to the file names. -Super useful for when assets change and they need to be re-downloaded. - -Note that order matters with AssetPack plugins and its best to have this pipe transform happen at. - -When combining this with `texturePacker` you add the `texturePackerCacheBuster` pipe right after -the `cacheBuster` pipe. `texturePackerCacheBuster` will ensure that the json files internanlly update their -asset names to accommodate the new file names. - -## Example transform - -``` -|- assets - |- mySprite.png - |- myJson.json -``` -transforms to: -``` -|- assets - |- mySprite-dfs3e.png - |- myJson-aw3dsf.json -``` -## Installation - -```sh -npm install --save-dev @assetpack/plugin-cache-buster -``` - -## Basic Usage - -```js -import { cacheBuster } from "@assetpack/plugin-cache-buster"; - -export default { - ... - pipes: { - ... - cacheBuster(), - }, -}; -``` - diff --git a/packages/docs/docs/guide/pipes/cache-buster.mdx b/packages/docs/docs/guide/pipes/cache-buster.mdx new file mode 100644 index 0000000..eb0fd34 --- /dev/null +++ b/packages/docs/docs/guide/pipes/cache-buster.mdx @@ -0,0 +1,59 @@ +--- +sidebar_position: 2 +--- + +import { ImageToggle } from '@site/src/components/ImageToggle'; + +# Cache Buster + +The `cacheBuster` plugin is an essential tool for ensuring that assets are correctly updated when they change. +When the `cacheBuster` plugin is added to the AssetPack configuration file, it generates unique hashes and appends them to file names. +This process ensures that when assets are modified, the updated versions are correctly re-downloaded by the user's browser, bypassing any cached versions. + +## Example + + + +To use the `cacheBuster` plugin, include it in your AssetPack pipeline. +It's crucial to note that the order of plugins in the pipeline affects the final output. For optimal results, +ensure that the `cacheBuster` transformation occurs at the correct stage in your pipeline. + +```ts +// assetpack.config.ts +import { cacheBuster } from "assetpack"; + +export default { + ... + pipes: { + ... + // make sure these pipes are added after plugins that generate files + cacheBuster(), + }, +}; +``` + +## Spine and Texture Packer + +When integrating with the [`texturePacker`](/docs/guides/pipes/texture-packer) plugin or your porject has spine atlas files, +you need to add the `texturePackerCacheBuster` / `spineAtlasCacheBuster` pipes immediately after the `cacheBuster` pipe. + +The `texturePackerCacheBuster` ensures that the JSON files internally update their asset names to reflect the newly hashed file names. +The `spineAtlasCacheBuster` pipe performs a similar function for spine atlas files. + +### Example + +```ts +// assetpack.config.ts +import { cacheBuster, texturePackerCacheBuster, spineAtlasCacheBuster } from "assetpack"; + +export default { + ... + pipes: { + ... + // make sure these pipes are added after plugins that generate files + cacheBuster(), + texturePackerCacheBuster(), + spineAtlasCacheBuster(), + }, +}; +``` diff --git a/packages/docs/docs/guide/pipes/ffmpeg.md b/packages/docs/docs/guide/pipes/ffmpeg.md deleted file mode 100644 index ea1bc11..0000000 --- a/packages/docs/docs/guide/pipes/ffmpeg.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_position: 2 ---- - -# FFmpeg - -You also need to install `ffmpeg` on your system. You can find instructions on how to do that [here](https://www.ffmpeg.org/download.html). - -## Basic Usage - -```js -import { audio } from "@assetpack/plugin-ffmpeg"; - -export default { - ... - pipes: [ - audio: audio(), - ], -}; -``` - -## Advanced Usage - -```js -import { ffmpeg } from "@assetpack/plugin-ffmpeg"; - -export default { - ... - pipes: [ - // ffmpeg plugin takes an input array of extensions and produces an output based on the options - // You can pass any ffmpeg options to the options object - ffmpeg({ - inputs: ['.mp3', '.ogg', '.wav'], - outputs: [ - { - formats: ['.mp3'], - recompress: false, - options: { - audioBitrate: 96, - audioChannels: 1, - audioFrequency: 48000, - } - }, - { - formats: ['.ogg'], - recompress: false, - options: { - audioBitrate: 32, - audioChannels: 1, - audioFrequency: 22050, - } - }, - ] - }), - ], -}; -``` diff --git a/packages/docs/docs/guide/pipes/ffmpeg.mdx b/packages/docs/docs/guide/pipes/ffmpeg.mdx new file mode 100644 index 0000000..b6d7ace --- /dev/null +++ b/packages/docs/docs/guide/pipes/ffmpeg.mdx @@ -0,0 +1,79 @@ +--- +sidebar_position: 2 +--- + +import { ImageToggle } from '@site/src/components/ImageToggle'; + +# Audio & FFmpeg + +The AssetPack library includes powerful plugins for audio conversion and file format manipulation using FFmpeg. These plugins, audio and ffmpeg, provide robust solutions for handling a variety of media file formats. + +## Audio + +The audio plugin converts and compresses audio files (`mp3`, `wav`, and `ogg`) to `mp3` and `ogg` formats. This is particularly useful for ensuring compatibility and optimizing file sizes for web delivery. + +### Example + + + +```ts +// assetpack.config.ts +import { audio } from "assetpack"; + +export default { + ... + pipes: [ + audio: audio(), + ], +}; +``` + +## FFmpeg + +The `ffmpeg` plugin exposes the full FFmpeg API, allowing for the conversion of any file type to any other file type. This provides a high level of customization and control over the conversion process, enabling a wide range of media processing tasks. + +## API + +The plugin takes an input array of file extensions and produces an output based on the options. + +- `inputs`: An array of file extensions to be processed. +- `outputs`: An array of objects containing the output formats and options for each format. + - `formats`: An array of file extensions to be output. + - `recompress`: A boolean value indicating whether the input file should be compressed if the output format is the same as the input format. + - `options`: An object containing the FFmpeg options for the output file. + +### Example + +```ts +// assetpack.config.ts +import { ffmpeg } from "assetpack"; + +export default { + ... + pipes: [ + ffmpeg({ + inputs: ['.mp3', '.ogg', '.wav'], + outputs: [ + { + formats: ['.mp3'], + recompress: false, + options: { + audioBitrate: 96, + audioChannels: 1, + audioFrequency: 48000, + }, + }, + { + formats: ['.ogg'], + recompress: false, + options: { + audioBitrate: 32, + audioChannels: 1, + audioFrequency: 22050, + }, + }, + ], + }), + ], +}; +``` diff --git a/packages/docs/src/components/ImageToggle.tsx b/packages/docs/src/components/ImageToggle.tsx new file mode 100644 index 0000000..e61b2af --- /dev/null +++ b/packages/docs/src/components/ImageToggle.tsx @@ -0,0 +1,138 @@ +import { useState } from 'react'; + +export const Toggle = ({ toggleImage, showImage1 }) => ( +
+
+

{showImage1 ? 'Original' : 'Processed'}

+
+
+
+
+
+); + +export const ImageToggle = ({ image, height }) => +{ + const [showImage1, setShowImage1] = useState(true); + + const toggleImage = () => + { + setShowImage1(!showImage1); + }; + + height ??= 600; + const image1 = `/assetpack/screenshots/${image}.png`; + const image2 = `/assetpack/screenshots/${image}-pro.png`; + + return ( +
+ +
+
+
+ Input Image +
+
+
+
+ Processed Image +
+
+
+
+ ); +}; diff --git a/packages/docs/src/css/custom.css b/packages/docs/src/css/custom.css index f714a5f..1d14be1 100644 --- a/packages/docs/src/css/custom.css +++ b/packages/docs/src/css/custom.css @@ -67,6 +67,22 @@ } } -/* hr { +.image-toggle-container { + display: flex; + flex-direction: column; + align-items: center; + width: 100%; + padding-bottom: 20px; + } -}5f5f5f */ + .image-wrapper { + position: relative; + pointer-events: none; + width: 100%; + } + + .toggle-image { + transition: opacity 0.5s ease-in-out; + position: absolute; + width: 100%; + } diff --git a/packages/docs/static/screenshots/audio/audio-pro.png b/packages/docs/static/screenshots/audio/audio-pro.png new file mode 100644 index 0000000..584a05a Binary files /dev/null and b/packages/docs/static/screenshots/audio/audio-pro.png differ diff --git a/packages/docs/static/screenshots/audio/audio.png b/packages/docs/static/screenshots/audio/audio.png new file mode 100644 index 0000000..009741b Binary files /dev/null and b/packages/docs/static/screenshots/audio/audio.png differ diff --git a/packages/docs/static/screenshots/cache/cache-buster-pro.png b/packages/docs/static/screenshots/cache/cache-buster-pro.png new file mode 100644 index 0000000..9c93e43 Binary files /dev/null and b/packages/docs/static/screenshots/cache/cache-buster-pro.png differ diff --git a/packages/docs/static/screenshots/cache/cache-buster.png b/packages/docs/static/screenshots/cache/cache-buster.png new file mode 100644 index 0000000..7b7a27c Binary files /dev/null and b/packages/docs/static/screenshots/cache/cache-buster.png differ