Skip to content

Commit

Permalink
Merge pull request #676 from simonihmig/more-docs
Browse files Browse the repository at this point in the history 
Finalize docs
  • Loading branch information
@simonihmig
simonihmig authored Sep 27, 2024
2 parents 5a332c5 + 7ec0fef commit b60b8c1
Show file tree
Hide file tree
Showing 13 changed files with 389 additions and 165 deletions.
23 changes: 23 additions & 0 deletions apps/docs/.vitepress/config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,29 @@ export default defineConfig({
text: 'Image CDNs',
link: '/cdn/',
},

{
text: 'About',
// link: '/usage/concepts',
items: [
{
text: 'Releases',
link: 'https://github.com/simonihmig/responsive-image/releases',
},
{
text: 'Me',
link: '/me',
},
{
text: 'History',
link: '/history',
},
{
text: 'Credits',
link: '/credits',
},
],
},
],

sidebar: [
Expand Down
49 changes: 0 additions & 49 deletions apps/docs/src/api-examples.md
View file

This file was deleted.

26 changes: 16 additions & 10 deletions apps/docs/src/build/vite.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,19 +71,25 @@ setupPlugins({
Besides global settings, you can also pass all the supported configuration options as query parameters when importimng an image:

```js
import logo from './logo.jpg?responsive&w=32,64&quality=95';
import logo from './logo.jpg?&w=32;64&quality=95&responsive';
```

Query params alwas take precedence of global settings passed to `setupPlugins()`.
Query params always take precedence over global settings passed to `setupPlugins()`.

### Configuration options

| option | type | description | default |
| --------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `w` | `Array<number>` | The image widths to be generated. For responsive images this should match the typical device sizes, eventually taking account when the image is not covering the full screen size, like `50vw`. For fixed size images this should be the intended size and twice of it for 2x displays. Pass this as a comma separated list when using query params. | `640, 750, 828, 1080, 1200, 1920, 2048, 3840` |
| `format` | `Array<'original' \| 'png' \| 'jpeg' \| 'webp'\|'avif'>` | The image formats to generate. `original` refers to whatever the original image's type is. Pass this as a comma separated list when using query params. | `['original', 'webp']` |
| `quality` | `number` | The image quality (0 - 100). | 80 |
| `name` | `string` | The template for the generated image files. The placeholders `[name]`, `[ext]` and `[width]` are replaced with real values. | [name]-[width]w.[ext] |
| `lqip` | `{ type: 'color' } \| {type: 'inline'; targetPixels?: number; } \| { type: 'blurhash'; targetPixels?: number; }` | Configuration for [Low Quality Image Placeholders](../usage/lqip.md). For passing this as a query param to your import, you can pass this as a string when you don't need to set anything beyond `type` (e.g. `image.jpg?responsive&lqip=inline`), or as a JSON stringified value (e.g. `image.jpg?responsive&lqip={"type":"blurhash","targetPixels":16}`). |
All the general [image parameters](../usage/local-images.md#image-parameters-reference) for local images can be specified both as global options or as query params, as explained above.

---
On top of that, there are the following Vite specific options, that you can customize the same way. In most cses, the existing defaults should be sufficient though.

#### `name: string`

The template for the generated image files. The placeholders `[name]`, `[ext]` and `[width]` are replaced with real values.

Default: `[name]-[width]w.[ext]`

```js
setsetupPluginsupLoaders({
name: '[name]_[width].[ext]',
});
```
50 changes: 35 additions & 15 deletions apps/docs/src/build/webpack.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ const config = {

### Global configuration

The package comes with reasonable defaults, but if you want to customize these for all image imports globally, then you can pass an optional configuration object to `setupLoaders()`:
The package comes with reasonable defaults, but if you want to customize these for all image imports globally, then you can pass an optional object with [configuration options](#configuration-options) to `setupLoaders()`:

```js
setupLoaders({
Expand All @@ -71,24 +71,44 @@ setupLoaders({

### Query params

Besides global settings, you can also pass all the supported configuration options as query parameters when importimng an image:
Besides global settings, you can also pass all the supported [configuration options](#configuration-options) as query parameters when importing an image:

```js
import logo from './logo.jpg?responsive&w=32,64&quality=95';
import logo from './logo.jpg?&w=32;64&quality=95&responsive';
```

Query params alwas take precedence of global settings passed to `setupLoaders()`.
Query params always take precedence over global settings passed to `setupLoaders()`.

### Configuration options

| option | type | description | default |
| ------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `w` | `Array<number>` | The image widths to be generated. For responsive images this should match the typical device sizes, eventually taking account when the image is not covering the full screen size, like `50vw`. For fixed size images this should be the intended size and twice of it for 2x displays. Pass this as a comma separated list when using query params. | `640, 750, 828, 1080, 1200, 1920, 2048, 3840` |
| `format` | `Array<'original' \| 'png' \| 'jpeg' \| 'webp'\|'avif'>` | The image formats to generate. `original` refers to whatever the original image's type is. Pass this as a comma separated list when using query params. | `['original', 'webp']` |
| `quality` | `number` | The image quality (0 - 100). | 80 |
| `name` | `string` | The template for the generated image files. Certains placeholders like `[ext]` and `[width]` and all the common Webpack placeholders are replaced with real values. | [name]-[width]w-[hash].[ext] |
| `webPath` | `string` | The public URL the emitted files are referenced from. By default, this matches Webpacks public URL and the path generated from `outputPath`. |
| `outputPath` | `string` | The file path where the public image files are emitted to. This is relative to the default folder configured for public asset files in Webpack. | images |
| `lqip` | `{ type: 'color' } \| {type: 'inline'; targetPixels?: number; } \| { type: 'blurhash'; targetPixels?: number; }` | Configuration for [Low Quality Image Placeholders](../usage/lqip.md). For passing this as a query param to your import, you can pass this as a string when you don't need to set anything beyond `type` (e.g. `image.jpg?responsive&lqip=inline`), or as a JSON stringified value (e.g. `image.jpg?responsive&lqip={"type":"blurhash","targetPixels":16}`). |

---
All the general [image parameters](../usage/local-images.md#image-parameters-reference) for local images can be specified both as global options or as query params, as explained above.

On top of that, there are the following webpack specific options, that you can customize the same way. In most cses, the existing defaults should be sufficient though.

#### `name: string`

The template for the generated image files. Certains placeholders like `[ext]` and `[width]` and all the common Webpack placeholders are replaced with real values.

Default: `[name]-[width]w-[hash].[ext]`

```js
setupLoaders({
name: '[name]_[width].[hash].[ext]',
});
```

#### `webPath: string`

The public URL the emitted files are referenced from. By default, this matches Webpacks public URL and the path generated from `outputPath`.

```js
setupLoaders({
webPath: 'https://images.example.com/',
});
```

#### `outputPath: string`

The file path where the public image files are emitted to. This is relative to the default folder configured for public asset files in Webpack.

Default: `images`
11 changes: 11 additions & 0 deletions apps/docs/src/credits.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Credit where credit is due...

I would like to thank the following people for their direct or indirect contributions to this project:

- [Andreas Schacht](https://github.com/andreasschacht) for his fantastic work on the initial version of `ember-responsive-image`, the predecessor of this project.

- [Malte Ubl](https://github.com/cramforce) for his blog post [Maximally optimizing image loading for the web in 2021](https://www.industrialempathy.com/posts/image-optimizations/) that inspired many of the image optimization techniques used here.

- [Lovell Fuller](https://github.com/lovell) for [sharp](https://github.com/lovell/sharp), the library that is powering all image processing of local images.

- [Jonas Kruckenberg](https://github.com/JonasKruckenberg) for [imagetools](https://github.com/JonasKruckenberg/imagetools) to support (query) parameter based image adjustments and effects.
18 changes: 18 additions & 0 deletions apps/docs/src/frameworks/ember.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,3 +163,21 @@ declare module '@glint/environment-ember-loose/registry' {
}
}
```
### Image imports
To make TypeScript understand your image imports, we tag them using a `responsive` query parameter, that has to come _last_!
> [!NOTE]
> We cannot use something like `*.jpg*` that works with queries, as TS only supports a single wildcard.
> See https://github.com/microsoft/TypeScript/issues/38638
Add this declaration to a file, e.g. your app's `types/global.d.ts`:

```ts
declare module '*responsive' {
import { ImageData } from '@responsive-image/ember';
const value: ImageData;
export default value;
}
```
7 changes: 7 additions & 0 deletions apps/docs/src/frameworks/index.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,8 @@
# Frontend frameworks

The [image component](../usage/component.md) and other utilities are provided with framework specific packages:

- [Ember](./ember.md)

> [!NOTE]
> Multi-framework support is still WIP. More supported frameworks will be added here over time...
17 changes: 17 additions & 0 deletions apps/docs/src/history.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# History of the project

This project has its roots in late 2016, when Andreas Schacht, my then co-worker, and [me](./me.md) started to work on `ember-responsive-image`. This came out of the need to render optimized responsive images in our framkework of choice [Ember.js](https://emberjs.com/), for client projects at [kaliber5](https://www.kaliber5.de), the consultancy that I co-founded.

As strong believers in open source software, and as this proved to be useful for others as well, we started the project in the open on GitHub, see the [first commit](https://github.com/simonihmig/responsive-image/commit/1718f0c6d113d21309cb3800338c944d5ba90943). Don't look too closely at the code though, 2016 was different! 😅

Over time it matured and improved. Feature-wise by adding support for e.g. next-gen image formats, Image CDNs or SSR (aka FastBoot in Ember world). Also much of the underlying implementation evolved, moving from invoking `ImageMagick` to using [`sharp`](https://sharp.pixelplumbing.com/), adopting Ember's [Octane](https://blog.emberjs.com/octane-is-here/) patterns (native classes, Glimmer components) and TypeScript.

But at some point it become obvious that we were running into a more fundamental technical problem, when [Embroider](https://github.com/embroider-build/embroider), Ember's next-gen build system, which is building a bridge towards adopting popular ecosystem build tools like webpack or Vite, was going to take over the very Ember-specific build system of Ember CLI. Alongside that came a new [v2 format](https://rfcs.emberjs.com/id/0507-embroider-v2-package-format/) to publish Ember addons. Previously, `ember-responsive-image` had the privilege of using the superpowers that v1 addons gave us, by being able to provide Ember runtime code (the component to render responsive images) _and_ plugging into the (legacy) Ember CLI build (for processing local images) _at the same time_. With the new v2 format, which are basically just static npm packages now that you import _runtime_ code from, this was not possible anymore. So what's next?

As Embroider embraced off-the-shelve build tools like [webpack](https://webpack.js.org/) and later [Vite](https://vitejs.dev/), this project basically had to do the same. Instead of tying our image processing into the legacy build system, we started to offer native [build-plugins](./build/index.md) for what Embroider uses already: webpack and Vite. These are now doing the heavy lifting, albeit in a completely frontend framework agnostic way!

This opened up the way to rethink the scope of this project: instead of being coupled to one specific framework, [Ember](https://emberjs.com/) (which I still love btw and encourage you to check out if you haven't lately!), this project started to move into a multi-framework project. Gone is the `ember-responsive-image` package, say hello to `@responsive-image/ember`, which is now a fully static lightweight v2 addon. Support for other frameworks is planned. Have ideas, or want to contribute? Feel free to raise an [issue](https://github.com/simonihmig/responsive-image/issues), [PR](https://github.com/simonihmig/responsive-image/pulls)'s are certainly very welcome as well! 😀

So stay tuned, the future is hopefully bright!

_PS. none of this would have been possible without the help of other people and building on the shoulders of giants, which I want to give [credit](credits.md) here!_
85 changes: 0 additions & 85 deletions apps/docs/src/markdown-examples.md
View file

This file was deleted.

Loading

0 comments on commit b60b8c1

Please sign in to comment.