Node Packages

Any custom javascript or styles should exist as part of a node js package.

Each node package for a theme should exist under the packages/ directory of the theme.

Naming a Package

The first step of creating a package is deciding on a name for the package. The package name should contain only the characters [a-zA-Z0-9\-].

The package should also follow these conventions:

  1. Front End Components should be located in the packages/components path, and should be named components-<component-name>.
  2. Libraries that are not directly included by Drupal, but may be included in the webpack build as a dependency should be located in packages/libraries. There are no further restrictions on the naming convention for libraries.

Creating a new Package

Based on the conventions above, you should create a package under the theme's /packages folder. The name of the package should be the name of the folder.

cd packages
mkdir <package-name>

Next create a package.json for the new package. The name of the package given in the package.json file should follow the format @<theme_name>/<package-name>.

Important

Prefixing the @<theme_name>/ in the package.json is important because it tells yarn that this package belongs to a certain theme.

An easy way to generate a package.json is to run yarn init.

cd <package-name>
yarn init

Fill in the wizard, paying special attention to the package name. The rest of the fields you can just skip through.

If your package will not contain javascript, you should delete the "main": "index.js"," entry in thepackage.jsonthat was created byyarn init`.

Important Package.json Settings

The theme follows the bolt monorepo layout. There are a few special keys to be aware of in package.json that tell webpack about how the package should be treated.

main

The main entry gives a javascript entrypoint for the package. This should not be listed if the package does not include javascript.

Webpack will use the main entry to resolve statements like const pkg = require('@my_theme/package').

The build process will also automatically create library entrypoints for @my_theme/components-package for component packages.

style

The style entry gives a sass entrypoint for the file that will get bundled with the generated component library.

twig

For components, the twig entry gives the main twig file for the component. This isn't bundled with webpack.

Providing a twig entrypoint allows you to reference @my_theme/components-package from the Drupal theme layer.

Updating the Yarn Workspace

After creating a new package, tell yarn to look for new packages:

yarn install --force