@plone/registry as ESM module, move to TS, complete documentation (p…

…lone#6399)

Co-authored-by: Steve Piercy <[email protected]>
Co-authored-by: David Glick <[email protected]>

.eslintignore

@@ -4,3 +4,5 @@ packages/volto
 packages/volto-guillotina
 !.*
 dist
+packages/registry/lib
+packages/registry/docs

.github/workflows/acceptance.yml

@@ -521,6 +521,9 @@ jobs:
       - name: Install yalc
         run: npm -g install yalc
 
+      - name: Build dependencies
+        run: make build-deps
+
       - name: Install a yalc'ed version of the current Volto in the project - publish
         run: |
           yalc publish packages/types

.github/workflows/docs-rtd-pr-preview.yml

@@ -10,6 +10,7 @@ on:
       - "docs/source/**"
       - .readthedocs.yaml
       - requirements-docs.txt
+      - "packages/registry/docs/**"
 
 permissions:
   pull-requests: write

.github/workflows/readme-link-check.yml

@@ -20,4 +20,4 @@ jobs:
     - name: Check links in README.md with awesome_bot
       run: |
         gem install awesome_bot
-        awesome_bot --request-delay 1 --allow-dupe --white-list http://localhost:8080/Plone,http://localhost:3000,https://github.com/kitconcept/volto-blocks-grid.git,https://my-server-DNS-name.tld/api --files PACKAGES.md,README.md,packages/blocks/README.md,packages/client/README.md,packages/components/README.md,packages/generator-volto/README.md,packages/registry/README.md,packages/scripts/README.md,packages/tsconfig/README.md,packages/types/README.md,packages/volto-slate/README.md,apps/nextjs/README.md,apps/remix/README.md,apps/vite-ssr/README.md
+        awesome_bot --request-delay 1 --allow-dupe --white-list http://localhost:8080/Plone,http://localhost:8080,http://localhost:3000,https://github.com/kitconcept/volto-blocks-grid.git,https://my-server-DNS-name.tld/api --files PACKAGES.md,README.md,packages/blocks/README.md,packages/client/README.md,packages/components/README.md,packages/generator-volto/README.md,packages/registry/README.md,packages/scripts/README.md,packages/tsconfig/README.md,packages/types/README.md,packages/volto-slate/README.md,apps/nextjs/README.md,apps/remix/README.md,apps/vite-ssr/README.md

.prettierignore

@@ -5,6 +5,7 @@
 styles/rules/*
 node_modules
 packages/volto/types/*
+packages/registry/docs/*
 storybook-static
 apps/vite-ssr/src/routeTree.gen.ts
 apps/vite/src/routeTree.gen.ts

apps/remix/tsconfig.json

@@ -25,8 +25,6 @@
     "paths": {
       "~/*": ["./app/*"]
     },
-
-    // Vite takes care of building everything, not tsc.
     "noEmit": true
   }
 }

apps/remix/vite.config.ts

@@ -1,6 +1,7 @@
 import { vitePlugin as remix } from '@remix-run/dev';
 import { defineConfig } from 'vite';
 import tsconfigPaths from 'vite-tsconfig-paths';
+import { PloneRegistryVitePlugin } from '@plone/registry/vite-plugin';
 
 export default defineConfig({
   plugins: [
@@ -12,6 +13,7 @@ export default defineConfig({
       },
     }),
     tsconfigPaths(),
+    PloneRegistryVitePlugin(),
   ],
   server: {
     port: 3000,

docs/source/upgrade-guide/index.md

@@ -522,6 +522,63 @@ The `react/jsx-key` rule has been enabled in ESlint for catching missing `key` i
 You might catch some violations in your project or add-on code after running ESlint.
 Adding the missing `key` property whenever the violation is reported will fix it.
 
+### `@plone/registry` moved to ESM
+
+The `@plone/registry` package has been moved to ESM.
+The add-on registry scripts have also been refactored to TypeScript.
+For maximum compatibility with CommonJS builds, the default exports have been moved to named exports.
+The modules affected are now built, and the import paths have changed, too.
+These changes force some import path changes that you should patch in your Plone project or add-on boilerplates.
+
+```{note}
+As always, when something changes in the boilerplate, you may regenerate one from Cookieplone and move your code into it, instead of fiddling with it.
+```
+
+For example, in your project's {file}`.eslintrc.js`:
+
+```diff
+ const fs = require('fs');
+ const projectRootPath = __dirname;
+-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++const { AddonRegistry } = require('@plone/registry/addon-registry');
+
+ let voltoPath = './node_modules/@plone/volto';
+
+@@ -17,15 +17,15 @@ if (configFile) {
+     voltoPath = `./${jsConfig.baseUrl}/${pathsConfig['@plone/volto'][0]}`;
+ }
+
+-const reg = new AddonConfigurationRegistry(__dirname);
++const { registry } = AddonRegistry.init(__dirname);
+
+ // Extends ESlint configuration for adding the aliases to `src` directories in Volto addons
+-const addonAliases = Object.keys(reg.packages).map((o) => [
++const addonAliases = Object.keys(registry.packages).map((o) => [
+   o,
+-  reg.packages[o].modulePath,
++  registry.packages[o].modulePath,
+ ]);
+
+-const addonExtenders = reg.getEslintExtenders().map((m) => require(m));
++const addonExtenders = registry.getEslintExtenders().map((m) => require(m));
+```
+
+Also in the Storybook configuration {file}`.storybook/main.js`.
+
+```diff
+-    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++    const { AddonRegistry } = require('@plone/registry/addon-registry');
+
+-    const registry = new AddonConfigurationRegistry(projectRootPath);
++    const { registry } = AddonRegistry.init(projectRootPath);
+```
+
+```{versionadded} Volto 18.0.0-alpha.47
+```
+
+```{versionadded} @plone/registry 3.0.0-alpha.0
+```
+
 ### Deprecation notices for Volto 18
 
 #### `@plone/generator-volto`

package.json

@@ -44,6 +44,9 @@
     "overrides": {
       "@pmmmwh/react-refresh-webpack-plugin": "0.5.11",
       "react-refresh": "0.14.0"
+    },
+    "patchedDependencies": {
+      "[email protected]": "patches/[email protected]"
     }
   }
 }

packages/generator-volto/generators/app/templates/.eslintrc.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const projectRootPath = __dirname;
-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+const { AddonRegistry } = require('@plone/registry/addon-registry');
 
 let voltoPath = './node_modules/@plone/volto';
 
@@ -17,15 +17,15 @@ if (configFile) {
     voltoPath = `./${jsConfig.baseUrl}/${pathsConfig['@plone/volto'][0]}`;
 }
 
-const reg = new AddonConfigurationRegistry(__dirname);
+const { registry } = AddonRegistry.init(__dirname);
 
 // Extends ESlint configuration for adding the aliases to `src` directories in Volto addons
-const addonAliases = Object.keys(reg.packages).map((o) => [
+const addonAliases = Object.keys(registry.packages).map((o) => [
   o,
-  reg.packages[o].modulePath,
+  registry.packages[o].modulePath,
 ]);
 
-const addonExtenders = reg.getEslintExtenders().map((m) => require(m));
+const addonExtenders = registry.getEslintExtenders().map((m) => require(m));
 
 const defaultConfig = {
   extends: `${voltoPath}/.eslintrc`,

packages/generator-volto/generators/app/templates/.storybook/main.js

@@ -104,9 +104,9 @@ module.exports = {
       [],
       defaultRazzleOptions,
     );
-    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+    const { AddonRegistry } = require('@plone/registry/addon-registry');
 
-    const registry = new AddonConfigurationRegistry(projectRootPath);
+    const { registry } = AddonRegistry.init(projectRootPath);
 
     config = lessPlugin({ registry }).modifyWebpackConfig({
       env: { target: 'web', dev: 'dev' },

packages/generator-volto/news/6399.breaking

@@ -0,0 +1,2 @@
+Breaking changes in `.eslintrc.js` and `.storybook/main.js` because of #6399. @sneridagh
+Please see the [Upgrade Guide](https://6.docs.plone.org/volto/upgrade-guide/index.html).

packages/registry/.eslintrc.js → packages/registry/.eslintrc.cjs

@@ -16,6 +16,8 @@ module.exports = {
   // Base config
   extends: ['eslint:recommended'],
 
+  ignorePatterns: ['docs/_static/searchtools.js'],
+
   overrides: [
     // React
     {
@@ -61,7 +63,11 @@ module.exports = {
 
     // Node
     {
-      files: ['.eslintrc.js', 'src/*.js'],
+      files: [
+        '.eslintrc.cjs',
+        'src/addon-registry/**/*.{js,ts}',
+        '__tests__/**/*.{js,ts}',
+      ],
       env: {
         node: true,
         es6: true,

packages/registry/.gitignore

@@ -1,6 +1,7 @@
 .parcel-cache/
 dist
+/bin
+/lib
+/include
 
-# yarn 3
-.pnp.*
-.yarn/*
+docs/_build/

packages/registry/.readthedocs.yaml

@@ -0,0 +1,34 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+  commands:
+    - cd ./packages/registry && make docs-rtd-registry
+
+# Build documentation in the "docs/" directory with Sphinx
+#sphinx:
+#  configuration: packages/registry/docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+#python:
+#  install:
+#    - requirements: requirements-docs.txt

packages/registry/Makefile

@@ -0,0 +1,90 @@
+### Defensive settings for make:
+#     https://tech.davis-hansson.com/p/make/
+SHELL:=bash
+.ONESHELL:
+.SHELLFLAGS:=-eu -o pipefail -c
+.SILENT:
+.DELETE_ON_ERROR:
+MAKEFLAGS+=--warn-undefined-variables
+MAKEFLAGS+=--no-builtin-rules
+
+# Sphinx variables
+# You can set these variables from the command line.
+SPHINXOPTS      ?=
+VALEOPTS        ?=
+# Internal variables.
+SPHINXBUILD     = "$(realpath bin/sphinx-build)"
+SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)"
+DOCS_DIR        = ./docs/
+BUILDDIR        = ./_build/
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
+VALEFILES       := $(shell find $(DOCS_DIR) -type f -name "*.md" -print)
+
+# We like colors
+# From: https://coderwall.com/p/izxssa/colored-makefile-for-golang-projects
+RED=`tput setaf 1`
+GREEN=`tput setaf 2`
+RESET=`tput sgr0`
+YELLOW=`tput setaf 3`
+
+## Docs
+
+bin/python: ## Create a Python virtual environment with the latest pip, and install documentation requirements
+	python3 -m venv . || virtualenv --clear --python=python3 .
+	bin/python -m pip install --upgrade pip
+	@echo "Python environment created."
+	bin/pip install -r ../../requirements-docs.txt
+	@echo "Requirements installed."
+
+.PHONY: docs-clean
+docs-clean:  ## Clean current and legacy docs build directories, and Python virtual environment
+	rm -rf bin include lib
+	rm -rf docs/_build
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+
+.PHONY: docs-html
+docs-html: bin/python  ## Build html
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: docs-livehtml
+docs-livehtml: bin/python  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
+		--ignore "*.swp" \
+		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+.PHONY: docs-linkcheck
+docs-linkcheck: bin/python  ## Run linkcheck
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+		"or in $(BUILDDIR)/linkcheck/ ."
+
+.PHONY: docs-linkcheckbroken
+docs-linkcheckbroken: bin/python  ## Run linkcheck and show only broken links
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? -eq 0; then exit 1; fi || test $$? -ne 0
+
+.PHONY: docs-vale
+docs-vale: bin/python  ## Install (once) and run Vale style, grammar, and spell checks
+	bin/vale sync
+	bin/vale --no-wrap $(VALEOPTS) $(VALEFILES)
+	@echo
+	@echo "Vale is finished; look for any errors in the above output."
+
+.PHONY: docs-rtd-pr-preview
+docs-rtd-pr-preview: ## Build previews of pull requests that have documentation changes on Read the Docs via CI
+	pip install -r requirements-docs.txt
+	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
+
+.PHONY: docs-rtd-registry
+docs-rtd-registry: ## Build Plone Registry docs on RTD
+	pip install -r ../../requirements-docs.txt && cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
+
+## Build
+
+.PHONY: rename-to-cjs
+rename-to-cjs: ## Rename the built files js -> cjs
+	mv dist/cjs/addon-registry.js dist/cjs/addon-registry.cjs
+	mv dist/cjs/create-addons-loader.js dist/cjs/create-addons-loader.cjs
+	mv dist/cjs/create-theme-loader.js dist/cjs/create-theme-loader.cjs