Frontend Developer tools for Drupal core

Install pre-requisites

1. Node.js - ensure that you are using at least the latest long-term support (LTS) release of Node.js, which is available at the Node.js downloads page. Alternatively, you can install Node.js via a package manager on many OS platforms.
2. Yarn - we use yarn for managing dependencies and running build scripts. Different versions of Drupal require different versions of yarn. Run corepack enable as a one-time setup step, so that Node can automatically choose the correct version.
3. Install package dependencies - from the root of your Drupal folder: cd core && yarn install

Common workflows

JavaScript code (since Drupal 10)

Drupal 10 does not transpile, because browser support is now good enough to use modern JavaScript without the need for transpiling, but JavaScript in core must be linted, and developing for CKEditor 5 requires webpack.

Once the pre-requisites are installed, edit the .js file you want, and when the code is ready, make sure the code is formatted correctly with: 

# Command to run from inside the core/ folder.

yarn lint:core-js-passing

JavaScript code (for Drupal 9)

Drupal core adopted modern features of the JavaScript language before those features were universally supported in browsers, so Drupal 9 used babel to transpile modern JavaScript to a version compatible with older browsers. The convention was that all JavaScript must be written in a file with the extension .es6.js, and the corresponding .js file for legacy browsers would be automatically created by the build tools detailed below. For CSS Drupal core also supports PostCSS and build tools will handle any file with the extension .pcss.css and create the corresponding .css file when running the build command.

Once the pre-requisites are installed, when working on a patch, the overall Drupal 9 workflow is:

1. launch a watcher for changes in .es6.js files,
2. lint the code and fix formatting errors,
3. compile (or "transpile") the .es6.js code to .js files,
4. and finally create the patch to send to drupal.org.

# Commands to run from inside the core/ folder.

# Listen to changes on all *.es6.js files and
# automatically compile the *.js file.
yarn run watch:js

# Work on the JavaScript until satisfied, 
# stop the watch command. 


# Before creating the patch to send to drupal.org
yarn run lint:core-js-passing

# All errors and warning displayed must be fixed
# before sending the patch to drupal.org.
# Some errors can be automatically corrected,
# such as code formatting by adding the '--fix'
# parameter to the lint command.
yarn run lint:core-js-passing --fix


# Once there are no more syntax errors build  
# all .js files with
yarn run build:js

At this point you can create a patch to send to Drupal.org issue queue. It is very important to run the linter on JavaScript code so that the quality of our code doesn't degrade over time.

yarn run build:js -- --file misc/drupal.es6.js

Reviewing changes to CKEditor 5 build files

We can reduce the risk of security issues being added by new JavasScript dependencies by reviewing un-minified build assets.

1. Create a branch for the development build.

2. Build the files by running the development build command and commit the changes. This build command will un-minify the build files.

yarn build:ckeditor5-dev

git commit -am 'Unminified build assets'

3. Go back to the branch with the new changes you want to review the build files for.

4. Run the development build command again on this branch and commit the changes.

yarn build:ckeditor5-dev

git commit -am 'Unminified build assets'

6. Now you can compare this against the branch created earlier.

git diff <Your_Branch> <Branch_To_Compare_With> -- core/modules/ckeditor5/js

CSS code

When developing core CSS locally you can use the watcher to make changes and have them compiled as you save.

cd core
yarn install
yarn run watch:css

This watcher will only watch changes in files with the .pcss.css extension.

Building core CSS

To build all CSS run yarn run build:css. This will create .css versions of the .pcss.css files.

If you want to only compile a specific file you can pass the --file flag:

yarn run build:css -- --file themes/seven/css/base/elements.pcss.css

Check the coding standard using:

yarn run lint:css 

Building Drupal core's forked jQuery UI

When modifying the forked copy of jQuery UI that ships with Drupal core, build the minified JS files using yarn run build:jqueryui .

Updating third-party dependencies

Updating JavaScript dependencies other than CKEditor or modernizr

To check if there are updates to a third party dependency:

1. Run yarn outdated to find outdated packages
   1. Update package.json version requirement if necessary (when updating dependencies in non-production branch).
      1. Development dependencies: required for updating major releases.
      2. Production dependencies: required for updating minor and major releases.
   2. Run yarn upgrade <package>
2. Run yarn vendor-update to automatically:
   1. Copy all required files to the core/assets/vendor folder
   2. Update the libraries definition in core.libraries.yml with the correct version and License URL
3. Run yarn build to ensure any changes to the third party libraries are reflected in build files
4. Check that all changes were made correctly:
   1. No missing vendor files
   2. URLs to licences and versions in the core.libraries.yml are correct
   3. Run yarn lint:css and yarn lint:core-js-passing to ensure any updates to the lint rules are not failing with existing code

Updating CKEditor 5

1. Increase the package constraints for the CKEditor 5 dependencies as needed in core/package.json (all packages with the @ckeditor namespace).
2. Perform a clean installation of core's yarn dependencies:
   

   cd core
   rm -rf node_modules
   yarn install

3. Update the vendor assets: yarn run vendor-update.
4. Run the CKEditor 5 build: yarn run build:ckeditor5.
5. Run yarn run build:ckeditor5-types (this step is needed for compiling a map of CKEditor 5 JSDoc types in a format that is compatible with IDEs).

Updating modernizr

Copied from /core/assets/vendor/modernizr/README.md.

To update modernizr:

For some reason the link in the core file https://modernizr.com/download/?-details-inputtypes-addtest-mq-prefixed-prefixes-setclasses-teststyles always produces a 3.6.0 version when using the Build option. Browse to the same URL and use the Command Line Config option to Download the config JSON file modernizr-config.json. Following the instructions from modernizr's documentation:

sudo npm install -g npm
npm install -g modernizr
modernizr -c modernizr-config.json // This is the file downloaded from http://modernizr.com/download

This produces a modernizr.js file that should be renamed to modernizr.min.js and copied to core/assets/vendor/modernizr/modernizr.min.js. Also remember to update the version number of Modernizer in core/core.libraries.yml.

Quick Reference

package.json in the DRUPAL_ROOT/core has some useful script commands for Drupal core development. Run these commands in the core directory.

Compile ("transpile") JavaScript ES6 files (only for Drupal 9)

• yarn build:js
• yarn build:js-dev
• yarn watch:js
• yarn watch:js-dev

Check JavaScript

• yarn lint:core-js
• yarn lint:core-js-passing
• yarn lint:core-js-stats
• yarn prettier

Compile PostCSS files

• yarn build:css
• yarn watch:css

Check Stylesheets

• yarn lint:css
• yarn lint:css-checkstyle

Compile both JavaScript and PostCSS files

• yarn build
• yarn watch

Compile jQuery UI

• yarn build:jqueryui

Run Tests

• yarn test:nightwatch.

Update third-party libraries

• yarn upgrade <package>
• yarn vendor-update

Un-minify CKEditor 5 JavaScript files with development mode

• yarn build:ckeditor5-dev
• yarn watch:ckeditor5-dev