Migrate to Eleventy 3 and ESM packages, big changes in eleventy-plugin-text-to-speech

.envrc

@@ -0,0 +1,17 @@
+export CLOUDFLARE_ACCOUNT_ID=43f9884041661b778e95a26992850715
+# export DEBUG="Eleventy:EleventyErrorHandler,11ty-test-utils"
+export DEBUG="Eleventy:EleventyErrorHandler,11ty-test-utils,11ty-plugin*"
+# export DEBUG="DevEleventy:*,Eleventy*"
+export NODE_DEBUG="script:*"
+export NODE_ENV=production
+export SKIP_TELEGRAM_MESSAGES=1
+# export SKIP_VALIDATION=1
+
+# secrets exposed as environment variables
+export CLOUDFLARE_R2=$(cat /run/secrets/cloudflare_r2/personal)
+export ELEVENLABS_API_KEY=$(cat /run/secrets/elevenlabs/api_key)
+export GITHUB_TOKEN=$(cat /run/secrets/github-tokens/semantic_release_bot)
+# export GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/prj-kitchen-sink/sa-storage-uploader
+export NPM_TOKEN=$(cat /run/secrets/npm-tokens/semantic_release_bot)
+export PLAUSIBLE=$(cat /run/secrets/plausible/test_site)
+export TELEGRAM=$(cat /run/secrets/telegram/personal_bot)

.github/workflows/ci.yaml

@@ -14,19 +14,23 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
+        # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources
+        # os: [ubuntu-latest, macos-latest, windows-latest]
         # Test all packages with:
         # 1. Maintenance LTS
         # 2. Active LTS
         # 3. Current (i.e. the latest Node.js version available)
-        # https://nodejs.org/en/about/releases/
-        node: ['lts/gallium', 'lts/hydrogen', 'current']
-        eleventy: ['2.0.0']
+        # https://nodejs.org/en/about/previous-releases
+        node: [ lts/Iron]
+        # node: [lts/Hydrogen, lts/Iron, current]
+        # https://www.npmjs.com/package/@11ty/eleventy?activeTab=versions
+        eleventy: ['3.0.0-alpha.4']
     steps:
       - name: 🛎️ Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: ⚙️ Set up Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
 
@@ -52,6 +56,7 @@ jobs:
 
       - name: 🔍 Test @jackdbd/eleventy-plugin-ensure-env-vars
         env:
+          DEBUG: Eleventy:EleventyErrorHandler,11ty-plugin*
           NODE_ENV: test
         run: npm run test:ci -w packages/eleventy-plugin-ensure-env-vars
 
@@ -65,16 +70,21 @@ jobs:
 
       - name: 🔍 Test @jackdbd/eleventy-plugin-text-to-speech
         env:
-          GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
-          TELEGRAM: ${{ secrets.TELEGRAM }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CLOUDFLARE_R2: ${{ secrets.CLOUDFLARE_R2 }}
+          SA_JSON_KEY_STORAGE_UPLOADER: ${{ secrets.SA_JSON_KEY_STORAGE_UPLOADER }}
+          SA_JSON_KEY_TEXT_TO_SPEECH: ${{ secrets.SA_JSON_KEY_TEXT_TO_SPEECH }}
         run: npm run test:ci -w packages/eleventy-plugin-text-to-speech
 
-      - name: ⬆️ Upload test coverage to Codecov
-        # https://github.com/marketplace/actions/codecov
-        uses: codecov/codecov-action@v3
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-        with:
-          # fail_ci_if_error: false
-          fail_ci_if_error: true
-          verbose: true
+      # TODO: all my tests use the Node.js test runner, which can print coverage
+      # reports to stdout. However, I still need to figure out how to generate
+      # the coverage files (which I will then upload to CodeCov with this action).
+      # - name: ⬆️ Upload test coverage to Codecov
+      #   # https://github.com/marketplace/actions/codecov
+      #   uses: codecov/codecov-action@v3
+      #   env:
+      #     CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      #   with:
+      #     # fail_ci_if_error: false
+      #     fail_ci_if_error: true
+      #     verbose: true

.github/workflows/release-to-npmjs.yaml

@@ -14,15 +14,14 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         # Use the Active LTS for this workflow
-        # https://nodejs.org/en/
-        # https://nodejs.org/en/about/releases/
-        node: ['16.17.0']
+        # https://nodejs.org/en/about/previous-releases
+        node: ['lts/Iron']
     steps:
       - name: 🛎️ Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: ⚙️ Set up Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
 

.gitignore

@@ -25,3 +25,8 @@ packages/**/.cache/
 # default cache directory of @jackdbd/eleventy-plugin-plausible
 packages/eleventy-plugin-plausible/.cache-plausible-json-responses/
 packages/demo-site/.cache-plausible-json-responses/
+
+# Clojure formatter
+.clj-kondo/
+# Language Server Protocol
+.lsp/

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-  "recommendations": ["pflannery.vscode-versionlens"]
+  "recommendations": ["esbenp.prettier-vscode", "pflannery.vscode-versionlens"]
 }

.vscode/settings.json

@@ -1,33 +1,4 @@
 {
-  "editor.formatOnSave": false,
-  // The extension pflannery.vscode-versionlens works only if the file type
-  // associated to package.json is json, not jsonc.
-  // For tsconfig files we can use jsonc without issues.
-  // https://marketplace.visualstudio.com/items?itemName=pflannery.vscode-versionlens
-  "files.associations": {
-    "_headers": "toml",
-    "*.json": "json",
-    "tsconfig*.json": "jsonc"
-  },
-  "files.exclude": {
-    "**/node_modules/": true
-  },
-  "[javascript]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "editor.formatOnSave": true
-  },
-  "[json]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "editor.formatOnSave": true
-  },
-  "[markdown]": {
-    "editor.suggestOnTriggerCharacters": false
-  },
-  "[typescript]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "editor.formatOnSave": true
-  },
-  // https://github.com/prettier/prettier-vscode#prettierconfigpath
   "prettier.configPath": "config/prettier.cjs",
   "prettier.requireConfig": true
 }

README.md

@@ -5,52 +5,93 @@
 [![codecov](https://codecov.io/gh/jackdbd/undici/branch/main/graph/badge.svg?token=P5uJ3doRer)](https://codecov.io/gh/jackdbd/undici)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 
+| Package | Version | Socket | Docs |
+| --- | --- | --- | --- |
+| [@jackdbd/eleventy-plugin-content-security-policy](https://github.com/jackdbd/undici/tree/main/packages/eleventy-plugin-content-security-policy) | [![npm version](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-content-security-policy.svg)](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-content-security-policy) | [![Socket Badge](https://socket.dev/api/badge/npm/package/@jackdbd/eleventy-plugin-content-security-policy)](https://socket.dev/npm/package/@jackdbd/eleventy-plugin-content-security-policy) | [docs](https://jackdbd.github.io/undici/eleventy-plugin-content-security-policy/index.html) |
+| [@jackdbd/eleventy-plugin-permissions-policy](https://github.com/jackdbd/undici/tree/main/packages/eleventy-plugin-permissions-policy) | [![npm version](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-permissions-policy.svg)](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-permissions-policy) | [![Socket Badge](https://socket.dev/api/badge/npm/package/@jackdbd/eleventy-plugin-permissions-policy)](https://socket.dev/npm/package/@jackdbd/eleventy-plugin-permissions-policy) | [docs](https://jackdbd.github.io/undici/eleventy-plugin-permissions-policy/index.html) |
+| [@jackdbd/eleventy-plugin-telegram](https://github.com/jackdbd/undici/tree/main/packages/eleventy-plugin-telegram) | [![npm version](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-telegram.svg)](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-telegram) | [![Socket Badge](https://socket.dev/api/badge/npm/package/@jackdbd/eleventy-plugin-telegram)](https://socket.dev/npm/package/@jackdbd/eleventy-plugin-telegram) | [docs](https://jackdbd.github.io/undici/eleventy-plugin-telegram/index.html) |
+| [@jackdbd/eleventy-plugin-text-to-speech](https://github.com/jackdbd/undici/tree/main/packages/eleventy-plugin-text-to-speech) | [![npm version](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-text-to-speech.svg)](https://badge.fury.io/js/@jackdbd%2Feleventy-plugin-text-to-speech) | [![Socket Badge](https://socket.dev/api/badge/npm/package/@jackdbd/eleventy-plugin-text-to-speech)](https://socket.dev/npm/package/@jackdbd/eleventy-plugin-text-to-speech) | [docs](https://jackdbd.github.io/undici/eleventy-plugin-text-to-speech/index.html) |
+
+> 📌 **Note to self**
+>
+> When Eleventy 3 becomes available as a regular release and is no longer in [alpha](https://www.zachleat.com/web/eleventy-v3-alpha/), update the `peerDependencies` of all packages from:
+>
+> ```txt
+> "@11ty/eleventy": ">=2.0.0 || 3.0.0-alpha.4"
+> ```
+>
+> to:
+>
+> ```txt
+> "@11ty/eleventy": ">=3.0.0"
+> ```
+>
+> Also, don't forget to update the GitHub workflows.
+>
+> **Note:** Eleventy supports **both** CJS and ESM [from version 3 onwards](https://github.com/11ty/eleventy/pull/3074). However, I plan to publish **only** ESM packages for my Eleventy plugins. This means that each one of my plugins should declare `>=3.0.0` in its `peerDependencies`.
+
 Monorepo for my [Eleventy](https://www.11ty.dev/) plugins.
 
-> 📦 **CJS only:**
+> 📦 **ESM only:**
 >
-> All libraries of this monorepo are published to npmjs as CommonJS.
->
-> At the moment none of these packages has a ESM build.
+> All libraries of this monorepo are published to npmjs as ECMAScript modules.
 >
 > See also:
 >
 > - [Eleventy issue #836](https://github.com/11ty/eleventy/issues/836)
+> - [ELEVENTY V3 WITH ESM SUPPORT NOW ON THE CANARY CHANNEL](https://www.zachleat.com/web/eleventy-v3-alpha/)
+> - [CALLING ALL COURAGEOUS CANARY TESTERS FOR ELEVENTY V3.0](https://www.11ty.dev/blog/canary-eleventy-v3/)
 
 ## Installation
 
 Clone the repo:
 
-```shell
+```sh
 git clone [email protected]:jackdbd/undici.git
-```
 
-This project defines a virtual environment with all the necessary dependencies. This environment is declared by the `mkShell` function in the `flake.nix` file you can find in the root directory of this monorepo. Thanks to nix, direnv and the `.envrc` file, you can activate this environment just by entering this monorepo (e.g. with `cd undici`).
+cd undici
+```
 
-If you don't use nix, ensure you have a Node.js version supported by this project. You could use a Node.js version manager like [nvm](https://github.com/nvm-sh/nvm), [asdf](https://github.com/asdf-vm/asdf-nodejs) or [volta](https://volta.sh/).
+Ensure you have a Node.js version supported by this project. You can use a Node.js version manager like [nvm](https://github.com/nvm-sh/nvm), [asdf](https://github.com/asdf-vm/asdf-nodejs) or [volta](https://volta.sh/).
 
-Install all dependencies from npm.js (by passing `--include dev` we can be sure that we are installing `devDependencies` even when `NODE_ENV` is set to `production`):
+Install all dependencies from npm.js:
 
 ```sh
-npm install --include dev --include prod
+npm install --include dev
 ```
 
-If you don't use nix, install [zx](https://github.com/google/zx) globally.
+> :information_source: by passing `--include dev` we can be sure that we are installing `devDependencies` even when `NODE_ENV` is set to `production`. This is important because [we should **always**](https://youtu.be/HMM7GJC5E2o?si=RaVgw65WMOXDpHT2) set `NODE_ENV=production`.
+
+Setup/update `./git/hooks` with [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks).
 
 ```sh
-npm install --global zx
+npx simple-git-hooks
 ```
 
 ## Development
 
 This monorepo uses [Typescript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to build all of its libraries.
 
-Build all libraries (i.e. 11ty plugins):
+### Packages
+
+Build all libraries (i.e. 11ty plugins) in watch mode:
 
 ```sh
-npm run build:libs
+npm run dev:libs
 ```
 
+You can also run `build` / `dev` / `test` on a single package. For example:
+
+```sh
+npm run build -w packages/eleventy-plugin-telegram
+npm run dev -w packages/eleventy-plugin-telegram
+npm run test -w packages/eleventy-plugin-telegram
+```
+
+### Demo site
+
+> :warning: Before building the demo site, be sure to build all other packages first.
+
 Build the demo 11ty site:
 
 ```sh
@@ -63,24 +104,22 @@ Build all libraries and the demo site:
 npm run build
 ```
 
-Serve the demo site:
+Build all libraries and the demo site, both in watch mode, and serve the demo site with the [Eleventy dev server](https://www.11ty.dev/docs/dev-server/):
 
 ```sh
-npm run serve:site
+npm run dev
 ```
 
-Build all libraries and the demo site, both in watch mode, and serve the demo site:
+Watch only the demo site and serve it using the Eleventy dev server:
 
 ```sh
-npm run dev
+npm run dev -w packages/demo-site
 ```
 
-Note: you will still need to refresh the browser (this might change when [Eleventy 2.0 will add a dev server](https://www.11ty.dev/docs/watch-serve/)).
-
-If you want to [update your git hooks](https://github.com/toplenboren/simple-git-hooks?tab=readme-ov-file#update-git-hooks-command) edit the `simple-git-hooks` section in `package.json`, then run:
+Serve the production build of the demo site:
 
 ```sh
-npx simple-git-hooks
+npm run serve -w packages/demo-site
 ```
 
 ## Test
@@ -113,4 +152,6 @@ See these plugins configured for the [demo Eleventy site](./packages/demo-site/R
 
 ## Monorepo management
 
-See [scripts](./scripts/README.md).
+For local development I rely on some environment variables and secrets. They are all set using a `.envrc` file. In my case this `.envrc` file **can** be tracked in git because the environment variables I use are non-sensitive configuration, and the secrets exist only on my filesystem. See also [nix-config](https://github.com/jackdbd/nix-config/) to learn how I encrypt my secrets.
+
+See also [scripts](./scripts/README.md).

config/README.md

@@ -4,7 +4,6 @@ Config files for building, testing, linting, formatting all packages in this mon
 
 - `commitlint.cjs`: configuration for [commitlint](https://github.com/conventional-changelog/commitlint), to enforce [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
 - `eslint.cjs`: configuration for [ESLint](https://eslint.org/).
-- `jest.cjs`: configuration for all `*.test.mjs` files. Use it with Jest [experimental support for ECMAScript Modules (ESM)](https://jestjs.io/docs/ecmascript-modules).
 - `lint-staged.cjs`: configuration for [lint-staged](https://github.com/okonet/lint-staged).
 - `prettier.cjs`: configuration for the [Prettier](https://prettier.io/) (code formatter).
 - `semantic-release.cjs`: common configuration for [semantic release](https://github.com/semantic-release/semantic-release) and [multi-semantic-release](https://github.com/qiwi/multi-semantic-release).

config/eslint-no-typescript.cjs

@@ -12,7 +12,8 @@ const config = {
     node: true
   },
   parserOptions: {
-    ecmaVersion: 'latest'
+    ecmaVersion: 'latest',
+    sourceType: 'module'
   },
   plugins: ['prettier'],
   rules: {