Improve documentation for installing prerequisite software

Created on 30 January 2023, almost 2 years ago
Updated 8 May 2023, over 1 year ago

Problem/Motivation

This weekend, I put on the persona of a junior dev and attempted to use ckeditor5_dev to spin up a simple ckeditor5 plugin. I failed to get local development working by following the README instructions. The shortcomings that I found were:

  1. It makes no mention on which version of Node to use
  2. It makes no mention on which version of Yarn to use (or how to install it)
  3. Running the instructions on Ubuntu 22.04, node 16.19.0, and yarn 3.3.1 fails with:
    www-data@5093773eb8f0:~/html/docroot/modules/custom/ooe_cke5_accordion$ yarn build
    [webpack-cli] Failed to load '/var/www/html/docroot/modules/custom/ooe_cke5_accordion/webpack.config.js' config
    [webpack-cli] Error: Qualified path resolution failed: we looked for the following paths, but none could be accessed.
    
    Source path: /var/www/html/docroot/modules/custom/ooe_cke5_accordion/node_modules/ckeditor5/build/ckeditor5-dll.manifest.json
    Not found: /var/www/html/docroot/modules/custom/ooe_cke5_accordion/node_modules/ckeditor5/build/ckeditor5-dll.manifest.json
    Not found: /var/www/html/docroot/modules/custom/ooe_cke5_accordion/node_modules/ckeditor5/build/ckeditor5-dll.manifest.json.js
    Not found: /var/www/html/docroot/modules/custom/ooe_cke5_accordion/node_modules/ckeditor5/build/ckeditor5-dll.manifest.json.json
    Not found: /var/www/html/docroot/modules/custom/ooe_cke5_accordion/node_modules/ckeditor5/build/ckeditor5-dll.manifest.json.node
    
    Require stack:
    - /var/www/html/docroot/modules/custom/ooe_cke5_accordion/webpack.config.js
    - /var/www/html/docroot/modules/custom/ooe_cke5_accordion/.yarn/__virtual__/webpack-cli-virtual-bb9697f60a/0/cache/webpack-cli-npm-4.10.0-09cee8c457-2ff5355ac3.zip/node_modules/webpack-cli/lib/webpack-cli.js
    - /var/www/html/docroot/modules/custom/ooe_cke5_accordion/.yarn/__virtual__/webpack-cli-virtual-bb9697f60a/0/cache/webpack-cli-npm-4.10.0-09cee8c457-2ff5355ac3.zip/node_modules/webpack-cli/lib/bootstrap.js
    - /var/www/html/docroot/modules/custom/ooe_cke5_accordion/.yarn/__virtual__/webpack-cli-virtual-bb9697f60a/0/cache/webpack-cli-npm-4.10.0-09cee8c457-2ff5355ac3.zip/node_modules/webpack-cli/bin/cli.js
    - /var/www/html/docroot/modules/custom/ooe_cke5_accordion/.yarn/__virtual__/webpack-virtual-db685b031a/0/cache/webpack-npm-5.75.0-ebca50e2e7-2bcc5f3c19.zip/node_modules/webpack/bin/webpack.js
        at Function.require$$0.Module._resolveFilename (/var/www/html/docroot/modules/custom/ooe_cke5_accordion/.pnp.cjs:13516:13)
        at Function.require$$0.Module._load (/var/www/html/docroot/modules/custom/ooe_cke5_accordion/.pnp.cjs:13366:42)
        at Module.require (node:internal/modules/cjs/loader:1067:19)
        at require (node:internal/modules/cjs/helpers:103:18)
        at /var/www/html/docroot/modules/custom/ooe_cke5_accordion/webpack.config.js:55:19
        at Array.forEach (<anonymous>)
        at Object.<anonymous> (/var/www/html/docroot/modules/custom/ooe_cke5_accordion/webpack.config.js:16:42)
        at Module._compile (node:internal/modules/cjs/loader:1165:14)
        at Object.Module._extensions..js (node:internal/modules/cjs/loader:1219:10)
        at Object.require$$0.Module._extensions..js (/var/www/html/docroot/modules/custom/ooe_cke5_accordion/.pnp.cjs:13560:33)
        

Steps to reproduce

  1. On a fresh Ubuntu 22.04 machine.
  2. Install Node 16
  3. Install yarn via corepack prepare yarn@stable --activate
  4. Run through the build steps in the README

Proposed resolution

Add documentation for the preferred node version and link to installation methods.
Add documentation for the preferred yarn version and link to installation methods.
Figure out what's missing from the existing steps and make it work "off the shelf".

Remaining tasks

TBD

User interface changes

None

API changes

None

Data model changes

None

πŸ“Œ Task
Status

Active

Version

1.0

Component

Documentation

Created by

πŸ‡ΊπŸ‡ΈUnited States luke.leber Pennsylvania

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Production build 0.71.5 2024