From 4460a433b249aafbf526a17ad840c0a6bd7930c4 Mon Sep 17 00:00:00 2001 From: Lucas Dohmen Date: Sun, 26 Jan 2025 23:06:29 +0100 Subject: [PATCH] Use ESM in the configuration examples --- src/css.md | 51 +++++++--------- src/faq.md | 18 +++--- src/images.md | 118 ++++++++++++++++--------------------- src/index.md | 16 ++++-- src/js.md | 144 ++++++++++++++++++++-------------------------- src/manifest.md | 26 ++++----- src/philosophy.md | 7 ++- src/sass.md | 40 ++++++------- src/static.md | 52 ++++++++--------- src/watching.md | 6 +- 10 files changed, 208 insertions(+), 270 deletions(-) diff --git a/src/css.md b/src/css.md index 7ff8388..8462750 100644 --- a/src/css.md +++ b/src/css.md @@ -10,13 +10,10 @@ faucet-pipeline-css offers bundling for files written in CSS. To enable this **beta module** you need to add the following lines to your faucet.config.js: -``` -module.exports = { - // ... - plugins: [ - require("faucet-pipeline-css") - ] -} +```js +export const plugins = [ + require("faucet-pipeline-css") +]; ``` The configuration is an array of bundles you want to create. Each entry of the @@ -25,15 +22,13 @@ compiled, and `target` is the file that should be created (the path is, of course, modified a little when you use fingerprinting): ```js -module.exports = { - css: [{ - source: "./example.css", - target: "./output/example.css" - }, { - source: "./example2.css", - target: "./output/subfolder/example2.css" - }] -}; +export const css = [{ + source: "./example.css", + target: "./output/example.css" +}, { + source: "./example2.css", + target: "./output/subfolder/example2.css" +}]; ``` To support fingerprinting of images and fonts, use `faucet-pipeline-static` to @@ -61,13 +56,11 @@ If you don't want to prefix your CSS even though you have a Browserslist configuration, you can deactivate it per bundle: ```js -module.exports = { - css: [{ - source: "./example.scss", - target: "./output/example.css", - browserslist: false - }] -}; +export const css = [{ + source: "./example.scss", + target: "./output/example.css", + browserslist: false +}]; ``` If you use groups in your Browserslist, faucet-pipeline uses the `default` group @@ -75,13 +68,11 @@ by default. If you want to choose a different one, you can, for example, set it "legacy" like this: ```js -module.exports = { - css: [{ - source: "./example.scss", - target: "./output/example.css", - browserslist: "legacy" - }] -}; +export const css = [{ + source: "./example.scss", + target: "./output/example.css", + browserslist: "legacy" +}]; ``` ## Compacting diff --git a/src/faq.md b/src/faq.md index 7a3f3fb..fb34510 100644 --- a/src/faq.md +++ b/src/faq.md @@ -11,16 +11,14 @@ This typically happens when importing a module that has already been bundled or otherwise provides a distribution. The solution is to skip transpilation there: ```javascript -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - esnext: { - // ... - exclude: ["jquery"] - } - }] -} +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + esnext: { + // ... + exclude: ["jquery"] + } +}]; ``` (This is necessary because faucet assumes we're consuming ES6 modules by diff --git a/src/images.md b/src/images.md index 62bca9e..ecf6773 100644 --- a/src/images.md +++ b/src/images.md @@ -13,12 +13,10 @@ folder, and `target` is the target folder. The resulting configuration might look something like this: ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images" - }] -}; +export const images = [{ + source: "./images", + target: "./public/images" +}]; ``` This will copy the images in the supported formats by default. The files will @@ -36,13 +34,11 @@ i.e. those for which the function returns `true` – will be copied. In this example, we only optimize `.svg` files: ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - filter: file => file.endsWith(".svg") - }] -} +export const images = [{ + source: "./images", + target: "./public/images", + filter: file => file.endsWith(".svg") +}]; ``` ## Configuring the quality @@ -50,13 +46,11 @@ module.exports = { You can also provide a quality as a value between 1 and 100. ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - quality: 60 - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + quality: 60 +}]; ``` This will configure the quality of all lossy formats (all formats except PNG and @@ -67,13 +61,11 @@ SVG). The quality is set to a 50 (AVIF/WebP) or 80 (PNG/JPG) by default. You can output the image in one of the supported formats. ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - format: "webp" - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + format: "webp" +}]; ``` Note that SVGs can be converted to all other formats. But converting a vector @@ -84,13 +76,11 @@ image format to SVG will result in an error. You can add a suffix to the output name: ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - suffix: "-optimized" - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + suffix: "-optimized" +}]; ``` This will output a file named `foo.png` as `foo-optimized.png`. This is @@ -103,14 +93,12 @@ To scale the images, you can provide a scaling factor. To create a version half the size, with the suffix `-small` you can use the following configuration: ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - scale: 0.5, - suffix: "-small" - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + scale: 0.5, + suffix: "-small" +}]; ``` You can also provide a target width and/or height. By default, the pipeline @@ -120,15 +108,13 @@ create files with the suffix `-thumbnail` with a maximum width of 300 and a maximum height of 300, keeping the ratio. ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - width: 300, - height: 300, - suffix: "-thumbnail" - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + width: 300, + height: 300, + suffix: "-thumbnail" +}]; ``` You can also resize without keeping the ratio -- the resulting image will have @@ -136,16 +122,14 @@ the exact dimension you specify. The image will be cropped vertically or horizontally so that no empty space remains. ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - width: 300, - height: 300, - crop: true, - suffix: "-square" - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + width: 300, + height: 300, + crop: true, + suffix: "-square" +}]; ``` ## Autorotate @@ -154,11 +138,9 @@ You can configure the pipeline to rotate images automatically according to their EXIF data: ```js -module.exports = { - images: [{ - source: "./images", - target: "./public/images", - autorotate: true - }] -}; +export const images = [{ + source: "./images", + target: "./public/images", + autorotate: true +}]; ``` diff --git a/src/index.md b/src/index.md index 12f7ae3..51ec950 100644 --- a/src/index.md +++ b/src/index.md @@ -14,23 +14,29 @@ details. Creating a CSS bundle from [Sass](http://sass-lang.com) modules: ```javascript +export const sass = [{ source: "./styles/index.scss", target: "./dist/bundle.css" +}]; ``` Bundling and transpiling JavaScript: ```javascript +export const js = [{ source: "./src/index.js", target: "./dist/bundle.js", esnext: true // activates ES6 transpiler +}]; ``` Fingerprinting arbitrary files, like fonts and images: ```javascript +export const static = [{ source: "./assets", target: "./dist/assets" +}]; ``` @@ -48,12 +54,10 @@ Configuration resides in `faucet.config.js` – in this case, we want to bundle our JavaScript:: ```javascript -module.exports = { - js: [{ - source: "./src/index.js", - target: "./dist/bundle.js" - }] -}; +export const js = [{ + source: "./src/index.js", + target: "./dist/bundle.js" +}]; ``` Let's create two source files within the `src` directory, `index.js` and diff --git a/src/js.md b/src/js.md index a9d835d..731073d 100644 --- a/src/js.md +++ b/src/js.md @@ -16,13 +16,11 @@ bundle to output a different module format like ESM (your choices are: `iife`, `esm`, `umd`, `amd`, and `commonjs`): ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - format: "esm" - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + format: "esm" +}]; ``` If you chose a module format that does not support importing/exporting natively @@ -35,15 +33,13 @@ variable - you can declare that library to be "external": faucet: ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - externals: { - jquery: "jQuery" - } - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + externals: { + jquery: "jQuery" + } +}]; ``` With this configuration, importing `from "jquery"` will be rewritten to @@ -70,17 +66,15 @@ faucet-js offers three options to reduce a bundle's file size: More extreme reductions can be activated via the bundle's `compact` setting: ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.min.js", - compact: "minify" - }, { - source: "./index.js", - target: "./dist/bundle.mangled.js", - compact: "mangle" - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.min.js", + compact: "minify" +}, { + source: "./index.js", + target: "./dist/bundle.mangled.js", + compact: "mangle" +}]; ``` `minify` will additionally remove all non-significant whitespace, `mangle` @@ -99,27 +93,23 @@ file](https://github.com/ai/browserslist/) to specify which browsers you want to support. This is an example configuration: ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - esnext: true - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + esnext: true +}]; ``` You can also deactivate the automatic browserslist detection: ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - esnext: { - browserslist: false - } - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + esnext: { + browserslist: false + } +}]; ``` If your browserslist is configured for multiple @@ -127,36 +117,32 @@ If your browserslist is configured for multiple you can choose which one to use for each bundle: ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - esnext: { - browserslist: "default" - } - }, { - source: "./index.js", - target: "./dist/legacy.js", - esnext: { - browserslist: "legacy" - } - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + esnext: { + browserslist: "default" + } +}, { + source: "./index.js", + target: "./dist/legacy.js", + esnext: { + browserslist: "legacy" + } +}]; ``` You can also exclude modules of the bundle you don't want to transpile with `exclude`. This is useful for dependencies that are already transpiled: ```js -module.exports = { - js: [{ - source: "./index.js", - target: "./dist/bundle.js", - esnext: { - exclude: ["jquery"] - } - }] -}; +export const js = [{ + source: "./index.js", + target: "./dist/bundle.js", + esnext: { + exclude: ["jquery"] + } +}]; ``` @@ -167,13 +153,11 @@ You also need to set `typescript` to true for the bundles that should be compiled with TypeScript: ```js -module.exports = { - js: [{ - source: "./src/index.ts", - target: "./dist/bundle.js", - typescript: true - }] -}; +export const js = [{ + source: "./src/index.ts", + target: "./dist/bundle.js", + typescript: true +}]; ``` Everything described above will still work in the same way (all configuration @@ -186,13 +170,11 @@ To use JSX, you need to install the `faucet-pipeline-jsx` package. You also need to set `jsx` to true for the bundles that should be compiled with JSX: ```js -module.exports = { - js: [{ - source: "./src/index.ts", - target: "./dist/bundle.js", - jsx: true - }] -}; +export const js = [{ + source: "./src/index.ts", + target: "./dist/bundle.js", + jsx: true +}]; ``` Everything described above will still work in the same way (all configuration diff --git a/src/manifest.md b/src/manifest.md index df50a9a..abb8087 100644 --- a/src/manifest.md +++ b/src/manifest.md @@ -36,12 +36,10 @@ The manifest generation is activated when you put the `manifest` key in your configuration with an object at least containing a `file` option with a path to where you want your manifest to go. -``` -module.exports = { - manifest: { - target: "./path/to/manifest.json" - } -} +```javascript +export const manifest = { + target: "./path/to/manifest.json" +}; ``` By default, the generated manifest will have... @@ -63,15 +61,13 @@ value relative to a different folder (in some frameworks, that would be Example: -``` -module.exports = { - manifest: { - target: "./path/to/manifest.json", - key: "short", - baseURI: "/assets/", - webRoot: "./target" - } -} +```javascript +export const manifest = { + target: "./path/to/manifest.json", + key: "short", + baseURI: "/assets/", + webRoot: "./target" +}; ``` ## Advanced Configuration diff --git a/src/philosophy.md b/src/philosophy.md index c6b20c8..ea2258e 100644 --- a/src/philosophy.md +++ b/src/philosophy.md @@ -49,6 +49,7 @@ actually writing the code. Thus we can easily recommend it to friends and colleagues and get them started in less than a minute. Of course, faucet wouldn’t be possible without relying on fantastic work by many -people; we merely provide a bit of glue code on top. The work on this project is -sponsored by [INNOQ](https://www.innoq.com) & [fejo.dk](https://www.fejo.dk). It -is used both in production and internal applications by both companies. +people; we merely provide a bit of glue code on top. Part of the work on this +project was sponsored by [INNOQ](https://www.innoq.com) and +[fejo.dk](https://www.fejo.dk). It is used both in production and internal +applications by both companies. diff --git a/src/sass.md b/src/sass.md index 9878a24..7152b22 100644 --- a/src/sass.md +++ b/src/sass.md @@ -11,15 +11,13 @@ compiled, and `target` is the file that should be created (the path is, of course, modified a little when you use fingerprinting): ```js -module.exports = { - sass: [{ - source: "./example.scss", - target: "./output/example.css" - }, { - source: "./example2.scss", - target: "./output/subfolder/example2.css" - }] -}; +export const sass = [{ + source: "./example.scss", + target: "./output/example.css" +}, { + source: "./example2.scss", + target: "./output/subfolder/example2.css" +}]; ``` To support fingerprinting of images and fonts, use `faucet-pipeline-static` to @@ -47,13 +45,11 @@ If you don't want to prefix your CSS even though you have a Browserslist configuration, you can deactivate it per bundle: ```js -module.exports = { - sass: [{ - source: "./example.scss", - target: "./output/example.css", - browserslist: false - }] -}; +export const sass = [{ + source: "./example.scss", + target: "./output/example.css", + browserslist: false +}]; ``` If you use groups in your Browserslist, faucet-pipeline uses the `default` group @@ -61,13 +57,11 @@ by default. If you want to choose a different one, you can, for example, set it "legacy" like this: ```js -module.exports = { - sass: [{ - source: "./example.scss", - target: "./output/example.css", - browserslist: "legacy" - }] -}; +export const sass = [{ + source: "./example.scss", + target: "./output/example.css", + browserslist: "legacy" +}]; ``` ## Compacting diff --git a/src/static.md b/src/static.md index 9d98302..7530166 100644 --- a/src/static.md +++ b/src/static.md @@ -10,15 +10,13 @@ and `target` is the target folder. The resulting configuration might look something like this: ```js -module.exports = { - static: [{ - source: "./images", - target: "./public/images" - }, { - source: "./fonts", - target: "./public/fonts" - }] -}; +export const static = [{ + source: "./images", + target: "./public/images" +}, { + source: "./fonts", + target: "./public/fonts" +}]; ``` If you only want to copy _some_ of the files, you can select them using a @@ -30,17 +28,15 @@ In this example, we only copy `.ttf` fonts and omit images from the `templates` directory: ```js -module.exports = { - static: [{ - source: "./fonts", - target: "./public/fonts", - filter: file => file.endsWith(".ttf") - }, { - source: "./images", - target: "./public/images", - filter: file => !file.startsWith("templates/") - }] -} +export const static = [{ + source: "./fonts", + target: "./public/fonts", + filter: file => file.endsWith(".ttf") +}, { + source: "./images", + target: "./public/images", + filter: file => !file.startsWith("templates/") +}]; ``` ## Compact @@ -61,13 +57,11 @@ If you prefer to compact your images on your own, you could for example use JPGs: ```js -module.exports = { - static: [{ - source: "./src", - target: "./dist", - compact: { - jpg: require("imagemin-mozjpeg")({ quality: 80 }) - } - }] -}; +export const static = [{ + source: "./src", + target: "./dist", + compact: { + jpg: require("imagemin-mozjpeg")({ quality: 80 }) + } +}]; ``` diff --git a/src/watching.md b/src/watching.md index 6e50929..83feab9 100644 --- a/src/watching.md +++ b/src/watching.md @@ -11,9 +11,5 @@ config file. The configuration expects an array of strings. The strings are paths relative to your configuration file. It might look like this: ```js -module.exports = { - // configuration of your pipelines... - - watchDirs: ["./src", "./lib"] -} +export const watchDirs = ["./src", "./lib"]; ```