Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/johannschopplich/kirby-hashed-assets

🛷 File name hashes support for css() and js() helpers. Without rewrite rules!
https://github.com/johannschopplich/kirby-hashed-assets

assets hashes kirby kirby-plugin manifest

Last synced: 7 days ago
JSON representation

🛷 File name hashes support for css() and js() helpers. Without rewrite rules!

Host: GitHub
URL: https://github.com/johannschopplich/kirby-hashed-assets
Owner: johannschopplich
License: mit
Created: 2020-12-25T09:33:32.000Z (almost 4 years ago)
Default Branch: main
Last Pushed: 2023-09-28T15:41:13.000Z (about 1 year ago)
Last Synced: 2024-10-30T01:26:23.197Z (18 days ago)
Topics: assets, hashes, kirby, kirby-plugin, manifest
Language: PHP
Homepage:
Size: 289 KB
Stars: 23
Watchers: 3
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Kirby Hashed Assets

Enhances Kirby's `css()` and `js()` helpers to support hashed filenames. Pass your normal paths (e.g. `…main.js`) – the plugin will lookup hashed assets and transform the path automatically (e.g. `…main.20201226.js`). That way you can even keep asset paths identical in development and production environment!

## Key Features

- 🛷 Cache bust assets without query strings
- 🎢 **No need** for web server rewrite rules!
- ⛸ Supports `manifest.json`
- 🎿 Supports manually hashed file names
- ☃️ Create preload links with `hashedUrl()` helper

## Projects Using the Hashed Assets Plugin

- [plainkit-hashed-assets](https://github.com/johannschopplich/plainkit-hashed-assets) – a simple demonstration based on Kirby's plain kit
- [realtroll.de](https://github.com/johannschopplich/realtroll.de) – a clean website using this plugin for asset hashing

## Requirements

- PHP 8.0+
- Kirby 3.7+

## Installation

### Download

Download and copy this repository to `/site/plugins/kirby-hashed-assets`.

### Git Submodule

```bash
git submodule add https://github.com/johannschopplich/kirby-hashed-assets.git site/plugins/kirby-hashed-assets
```

### Composer

```bash
composer require johannschopplich/kirby-hashed-assets
```

## Usage

### Automatic Hashing With `manifest.json`

For file hashing this plugin uses the [hashup](https://github.com/johannschopplich/hashup) npm package.

`hashup` is a tiny CLI tool with two objectives in mind for your freshly build assets:

1. Rename or rather hash (hence the name) the assets.
2. Generate a `manifest.json` for them.

You don't even have to install it to your `devDependencies`, since `npx` will fetch it once on the fly. Add hashup to your build pipeline by adding it your `package.json` scripts (recommended), for example:

```js
{
"scripts": {
"clean": "rm -rf public/assets/{css,js}",
"build": "npm run clean && <...> && npx -y hashup"
}
}
```

Now, pass asset paths to Kirby's asset helpers like you normally do:

```php
= js('assets/js/main.js') ?>
// `
```

If a corresponding hashed file is found in the `manifest.json`, it will be used and rendered.

For template-specific assets, use `@template` (instead of `@auto`):

```php
= js('@template') ?>
// ``
```

> [!WARNING]
> If no template file exists, `https://example.com/@template` will be echoed. This will lead to HTTP errors and blocked content since the requested file doesn't exist and the error page's HTML will be returned.

If you are unsure if a template file exists, use the following helpers:

- `cssTpl()`
- `jsTpl()`

They will echo a link tag, respectively script tag, only if a template file for current page's template is present.

### Manual Hashing

For smaller websites you may prefer no build chain at all, but still want to utilize some form of asset hashing. In this use-case you can rename your files manually.

Take an imaginary `main.js` for example. Just include it like you normally would in one of your snippets:

```php
= js('assets/js/main.js') ?>
```

Now rename the file in the format of `main.{hash}.js`. You may use the current date, e.g.: `main.20201226.js`, which will output:

```html

```

Voilà, without changing the asset path the hashed file will be found and rendered in your template!

### Hashed Filenames for Preloading Links

You can use the global `hashedUrl()` helper to lookup a file like you normally would with the `css()` or `js()` helpers. While the latter return a link or respectively script tag, the `hashedUrl()` helper will only return a URL which you can use in any context.

```php

//
```

Since all evergreen browsers finally support JavaScript modules natively, you may prefer preloading modules:

```php

//
```

## License