├── .editorconfig
├── .eslintignore
├── .eslintrc.cjs
├── .git-blame-ignore-revs
├── .gitignore
├── .prettierrc.cjs
├── .vscode
├── extensions.json
└── settings.json
├── Docs.md
├── LICENSE
├── README.md
├── index.ts
├── package.json
├── pnpm-lock.yaml
├── src
├── Image.astro
├── main.ts
└── placeholder.ts
└── tsconfig.json
/.editorconfig:
--------------------------------------------------------------------------------
1 | root = true
2 |
3 | [*]
4 | charset = utf-8
5 | end_of_line = lf
6 | indent_size = 2
7 | indent_style = tab
8 | insert_final_newline = true
9 | trim_trailing_whitespace = false
10 |
11 | [{*.md,*.json,*.toml,*.yml,}]
12 | indent_style = space
13 |
--------------------------------------------------------------------------------
/.eslintignore:
--------------------------------------------------------------------------------
1 | test/*.js
2 |
--------------------------------------------------------------------------------
/.eslintrc.cjs:
--------------------------------------------------------------------------------
1 | /** @type import("@types/eslint").Linter.Config */
2 | module.exports = {
3 | env: {
4 | node: true,
5 | },
6 | parser: '@typescript-eslint/parser',
7 | plugins: ['@typescript-eslint', 'prettier'],
8 | extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended'],
9 | rules: {
10 | // We don't want to leak logging into our user's console unless it's an error
11 | 'no-console': ['error', { allow: ['warn', 'error'] }],
12 | },
13 | };
14 |
--------------------------------------------------------------------------------
/.git-blame-ignore-revs:
--------------------------------------------------------------------------------
1 | # Format using astro-community/component-template settings
2 | c588953ba923fa33672ceb1d6f28ec7e9e46c6c7
3 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 |
3 | npm-debug.log*
4 | yarn-debug.log*
5 | yarn-error.log*
6 | .pnpm-debug.log*
7 |
8 | .DS_Store
9 |
--------------------------------------------------------------------------------
/.prettierrc.cjs:
--------------------------------------------------------------------------------
1 | /** @type import("@types/prettier").Options */
2 | module.exports = {
3 | printWidth: 180,
4 | semi: true,
5 | singleQuote: true,
6 | tabWidth: 2,
7 | trailingComma: 'es5',
8 | plugins: ['./node_modules/prettier-plugin-astro'],
9 | overrides: [
10 | {
11 | files: '*.astro',
12 | options: {
13 | parser: 'astro',
14 | },
15 | },
16 | {
17 | files: ['*.json', '*.md', '*.toml', '*.yml'],
18 | options: {
19 | useTabs: false,
20 | },
21 | },
22 | ],
23 | };
24 |
--------------------------------------------------------------------------------
/.vscode/extensions.json:
--------------------------------------------------------------------------------
1 | {
2 | "recommendations": ["astro-build.astro-vscode", "dbaeumer.vscode-eslint", "esbenp.prettier-vscode", "editorconfig.editorconfig"]
3 | }
4 |
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 | "editor.formatOnSave": true,
3 | "editor.codeActionsOnSave": {
4 | "source.fixAll": true
5 | },
6 | "cSpell.words": ["Astro"],
7 | "prettier.documentSelectors": ["**/*.astro"],
8 | "markdownlint.config": {
9 | "MD024": false // Remove warning on headers with same title as this happens a lot in our doc
10 | }
11 | }
12 |
--------------------------------------------------------------------------------
/Docs.md:
--------------------------------------------------------------------------------
1 | # Docs
2 |
3 | ## JS usage
4 |
5 | ### `generateImage`
6 |
7 | The `generateImage` returns an object containing the different formats generated (see main README for example) and takes the following parameters:
8 |
9 | #### src
10 |
11 | The path to the image, this is relative to your project root
12 |
13 | #### options
14 |
15 | An object containing options that `eleventy-img` will use for generating your image. See [eleventy-img's documentation](https://www.11ty.dev/docs/plugins/image/) for a list of accepted parameters
16 |
17 | By default:
18 |
19 | ```js
20 | {
21 | outputDir: "public/assets/images",
22 | urlPath: "/assets/images",
23 | }
24 | ```
25 |
26 | ### `generatePlaceholder`
27 |
28 | The `generatePlaceholder` function returns an object containing the different properties you might need to show the placeholder, example:
29 |
30 | ```js
31 | {
32 | dataURI: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAkAAAAHCAIAAABV+fA3AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAz0lEQVQImQHEADv/AJ7Ho7PYwTt5UhdkNjmLSUOPUCB4MSFzMkGMNACixqksb04WUy4wdz9cnFxPnksbaS0HTCo3hDUAnLmcRnFLQ289ZpZXn7Z9MpA+OYU9EFstVZpHAJ3GaqnPbJXFW5iyZNzLqZWvco+9YHeqVlKXSACu1myt13Cc1GW6ynnFrIjK4ouSzFZ/vlNsskgAytqD1d6Q3+Kevsl/xb951+OXyt6FstVytNRzAIS0S4i2S5u8TK3NXrPOZ57CYqLGXWiqOoi4Rz9UYMGpm241AAAAAElFTkSuQmCC';
33 | width: 640;
34 | height: 514;
35 | quality: 60;
36 | }
37 | ```
38 |
39 | and takes the following parameters:
40 |
41 | #### src
42 |
43 | The path to the image to generate your placeholder from, this is relative to your project root
44 |
45 | #### options
46 |
47 | An object containing options used to generate the placeholder
48 |
49 | By default:
50 |
51 | ```js
52 | {
53 | quality: 60,
54 | outputDir: "src/assets/placeholders",
55 | }
56 | ```
57 |
58 | ##### About the outputDir
59 |
60 | It should be noted that unlike images, placeholders should be in `src` and not in `public` as they're never accessed directly by the user but only at build time. It could also be in a `cache` folder somewhere as it's only for cache purpose that it's written to disk
61 |
62 | ##### Caution about quality
63 |
64 | Please note that `quality` might not work like you think it does, it does not define the image blurriness or anything like that but the amount of pixel your final image will be made of, that means that if you have a square image and you put a value less than 4, you'll only have corners of a blurry image showing
65 |
66 | The default value should accommodate more or less all kind of images but you might need to set an higher value for certain formats
67 |
68 | ## Component usage
69 |
70 | The `Image` component return the complete HTML needed to show the image and its placeholder on your website and takes the following parameters:
71 |
72 | ### src
73 |
74 | See [generateImage#src](#src)
75 |
76 | ### options
77 |
78 | See [generateImage#options](#options). However, it should be noted that the default settings also include the following in addition to the previously mentioned ones:
79 |
80 | ```js
81 | {
82 | widths: [null],
83 | formats: ["avif", "webp", "png"],
84 | sharpWebpOptions: {
85 | quality: quality, // See #quality below for explanation
86 | },
87 | sharpAvifOptions: {
88 | quality: quality, // Same
89 | },
90 | }
91 | ```
92 |
93 | ### alt
94 |
95 | Add an alt text to your image, by `eleventy-img`'s rules, this is not optional. Accessibility is important
96 |
97 | ### caption
98 |
99 | Since the component generate a `figure`, this option allows for the addition of a `figcaption`
100 |
101 | ### sizes
102 |
103 | See [the MDN page](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) on `sizes`
104 |
105 | ### classes
106 |
107 | CSS classes to add to the `figure` element
108 |
109 | ### quality
110 |
111 | Set the quality of the generated images, by default `90`
112 |
113 | ### placeholderOptions
114 |
115 | See [generatePlaceholder#options](#options-1)
116 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Erika "Princesseuh"
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Astro + eleventy-img
2 |
3 | > **Warning**
4 | > This project is not supported anymore. Please use the official [`astro:assets`](https://docs.astro.build/en/guides/assets/) instead.
5 |
6 | A tiny script and component intended to be used with [Astro](https://astro.build/) for generating images with [eleventy-img](https://github.com/11ty/eleventy-img). It also supports creating blurry placeholders for said images
7 |
8 | It was mostly made for my own website and I do not intend to really support this outside of my own needs. For more generalist solutions, check out the official [@astrojs/image](https://docs.astro.build/en/guides/integrations-guide/image/) integration or [astro-imagetools](https://github.com/RafidMuhymin/astro-imagetools).
9 |
10 | **This package is intended to be used in Astro's static mode and does NOT support Server-Side Rendering.**
11 |
12 | ## Installation
13 |
14 | ```shell
15 | npm install astro-eleventy-img
16 | ```
17 |
18 | ## Usage
19 |
20 | The best way to use this in my opinion is to use it to generate images in the `public` folder. That way, they're copied directly to the result website. This is the default behavior.
21 |
22 | ### Javascript Usage
23 |
24 | #### Generating images
25 |
26 | ```astro
27 | ---
28 | import { generateImage } from 'astro-eleventy-img';
29 |
30 | const myImage = await generateImage('src/assets/my_image.png', {
31 | // The options here are passed directly to eleventy-img
32 | widths: [300],
33 | formats: ['webp', 'avif'],
34 | });
35 | ---
36 |
37 |
38 | ```
39 |
40 | `generateImage` returns an object containing all the formats generated and metadata you can use in your HTML, so myImage is equal to:
41 |
42 | ```js
43 | {
44 | webp: [
45 | {
46 | format: 'webp',
47 | width: 300,
48 | height: 240,
49 | url: '/assets/images/RfSNa8TCUW-300.webp',
50 | sourceType: 'image/webp',
51 | srcset: '/assets/images/RfSNa8TCUW-300.webp 300w',
52 | filename: 'RfSNa8TCUW-300.webp',
53 | outputPath: 'public/assets/images/RfSNa8TCUW-300.webp'
54 | }
55 | ],
56 | avif: [
57 | {
58 | format: 'avif',
59 | width: 300,
60 | height: 240,
61 | url: '/assets/images/RfSNa8TCUW-300.avif',
62 | sourceType: 'image/avif',
63 | srcset: '/assets/images/RfSNa8TCUW-300.avif 300w',
64 | filename: 'RfSNa8TCUW-300.avif',
65 | outputPath: 'public/assets/images/RfSNa8TCUW-300.avif'
66 | }
67 | ]
68 | }
69 | ```
70 |
71 | The following files will be generated in the `public/assets/images` folder:
72 |
73 | ```shell
74 | RfSNa8TCUW-300.webp
75 | RfSNa8TCUW-300.avif
76 | ```
77 |
78 | #### Generating placeholders
79 |
80 | ```astro
81 | ---
82 | import { generatePlaceholder } from 'astro-eleventy-img';
83 |
84 | const myPlaceholder = generatePlaceholder('src/assets/my_image.png');
85 | ---
86 |
87 |
88 | ```
89 |
90 | `generatePlaceholder` return an object containing all the properties needed for showing the image. So `myPlaceholder` in this example is equal to:
91 |
92 | ```js
93 | {
94 | dataURI: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAkAAAAHCAIAAABV+fA3AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAz0lEQVQImQHEADv/AJ7Ho7PYwTt5UhdkNjmLSUOPUCB4MSFzMkGMNACixqksb04WUy4wdz9cnFxPnksbaS0HTCo3hDUAnLmcRnFLQ289ZpZXn7Z9MpA+OYU9EFstVZpHAJ3GaqnPbJXFW5iyZNzLqZWvco+9YHeqVlKXSACu1myt13Cc1GW6ynnFrIjK4ouSzFZ/vlNsskgAytqD1d6Q3+Kevsl/xb951+OXyt6FstVytNRzAIS0S4i2S5u8TK3NXrPOZ57CYqLGXWiqOoi4Rz9UYMGpm241AAAAAElFTkSuQmCC';
95 | width: 640;
96 | height: 514;
97 | quality: 60;
98 | }
99 | ```
100 |
101 | ### Component Usage
102 |
103 | Alternatively, it can also be used through a provided component to automatically generate the proper HTML for including the image and its placeholder:
104 |
105 | ```astro
106 | ---
107 | import { Image } from 'astro-eleventy-img';
108 | ---
109 |
110 |
111 | ```
112 |
113 | will generate the following HTML:
114 |
115 | ```html
116 |
117 |
118 |
119 |
120 |
133 |
134 |
135 |