@liferay/npm-scripts

@liferay/npm-scripts is our principal abstraction for building, formatting, linting, and testing frontend code in liferay-portal. It provides:

• A simplified interface: The liferay-npm-scripts command-line implements a small number of subcommands such as build, checkFormat and test, most of which don't require any arguments and do the right thing "out-of-the-box", automatically.
• Industry-standard dependencies: @liferay/npm-scripts brings a set of well-tested and robust dependencies including Babel, ESLint, Jest, Prettier, and others, ensuring that people working anywhere in a Liferay project have access to a single, consistent set of tools.
• Reasonable default configuration: All of the bundled tools come with configurations that have been tuned to work in a Liferay environment, and can be overridden via standard configuration files (eg. .eslintrc.js etc) on the rare occasions that it is necessary to do so.

While @liferay/npm-scripts was designed with liferay-portal in mind, it is also used in other projects such as liferay-learn; see this issue for context.

Usage

npm install --save-dev @liferay/npm-scripts

package.json

{
	"scripts": {
		"build": "liferay-npm-scripts build"
	}
}

Scripts Available

build

Build script that compiles all necessary JavaScript and bundles it together using liferay-npm-bundler.

liferay-npm-scripts build

Do you need to use liferay-npm-bridge-generator? Just add a .npmbridgerc file and follow the configuration options here.

check

liferay-npm-scripts check

check runs ESLint to catch semantic problems in JS (equivalent to running eslint without the --fix option), stylelint to catch problems in SCSS files, and Prettier to catch formatting issues (equivalent to running prettier with the --check flag), for the globs specified in your npmscripts.config.js configuration (or, in the absence of explicit configuration, in the default preset).

This is the task that runs in liferay-portal projects when you run yarn checkFormat.

fix

liferay-npm-scripts fix

fix runs ESLint and stylelint to identify and fix autofixable issues in JS and SCSS, and Prettier to enforce formatting (equivalent to calling prettier with the --write flag) for the globs specified in your npmscripts.config.js configuration (or, in the absence of explicit configuration, in the default preset).

This is the task that runs in liferay-portal projects when you run yarn format (or gradlew formatSource -a, or ant format-source).

prettier

liferay-npm-scripts prettier

When @liferay/npm-scripts uses Prettier, it additionally applies some tweaks in a post-processing step to match liferay-portal coding conventions. Normally, you will want to run liferay-npm-scripts check or liferay-npm-scripts fix as described above rather than interacting with the prettier executable directly.

However, in order to facilitate integration with editors and editor plugins, this subcommand exposes the augmented version of prettier, providing this "Prettier plus post-processing" functionality, using an interface that is similar to that of the prettier executable. Example usage:

liferay-npm-scripts prettier --write src/someFileToFormat.js 'test/**/*.js'

Supported flags:

• --stdin-filepath=FILEPATH
• --stdin
• --write

All other prettier flags are ignored.

Editor integrations

Vim

One way to run prettier from Vim is with the vim-prettier plugin. It comes with a setting, g:prettier#exec_cmd_path, that you can use to configure a custom prettier executable. For example, you could take this sample shell script and copy it somewhere such as ~/bin/:

curl https://raw.githubusercontent.com/liferay/liferay-frontend-projects/master/projects/npm-tools/packages/npm-scripts/contrib/prettier/prettier.sh > ~/bin/prettier.sh
chmod +x !$

Then, add a line like this to your ~/.vim/vimrc:

let g:prettier#exec_cmd_path = "~/bin/prettier.sh"

Now you can use the :Prettier command and others provided by the vim-prettier plugin in Vim, and it will use your script instead of the upstream version of Prettier. The script tries first to find the @liferay/npm-scripts version, then prettier, and ultimately will fall back to npx prettier as a last resort. When working outside of a liferay-portal clone, it doesn't try to use the version provided by @liferay/npm-scripts.

If you don't want to install vim-prettier, you can of course run the script directly using the ! command:

!~/bin/prettier.sh --write %

Or, if the script is in your path:

!prettier.sh --write %

And you can always call directly into liferay-npm-scripts if you prefer:

!path/to/liferay-npm-scripts prettier --write %

Visual Studio Code

A popular choice for running prettier from VSCode is the "Prettier - Code Formatter" extension.

You can take this sample wrapper module and configure the extension to use it instead of the standard prettier one. For example, to install a copy of the wrapper to ~/bin/prettier.js, you could run the following:

curl https://raw.githubusercontent.com/liferay/liferay-frontend-projects/master/projects/npm-tools/packages/npm-scripts/contrib/prettier/prettier.js > ~/bin/prettier.js

If you have the script at ~/bin/prettier.js, in the UI you would go to Preferences → Settings → User → Extensions → Prettier → Prettier Path and set it to ~/bin/prettier.js. Alternatively, if you prefer to manipulate the VSCode settings.json file directly, you would set prettier.prettierPath to ~/bin/prettier.js.

Note: You will have to restart VSCode for this change to actually take effect.

The wrapper script attempts to detect when you are working in a liferay-portal checkout and uses the customized Prettier formatting in that case; otherwise, it falls back to the standard behavior.

test

liferay-npm-scripts test

Runs jest with a default configuration specified in jest.json. You can override or add any additional configuration by following jest documentaion.

Additionally if you want to use any flags for jest, such as --watch you can do so.

For example

liferay-npm-scripts test --watch

theme

liferay-npm-scripts theme TASK

Inside a theme directory, runs one of the available Gulp tasks, TASK, from liferay-theme-tasks, automatically passing settings for use inside liferay-portal.

For example:

liferay-npm-scripts theme build

Runs the "build" task, providing it with the configuration it needs to find core dependencies such as the liferay-frontend-theme-styled base theme files.

types

liferay-npm-scripts types

Freshens all TypeScript type definition files in a liferay-portal checkout. Normally, these artifacts (.d.ts and tsconfig.tsbuildinfo files) would be committed along with changes to the corresponding module, but this command exists as a convenience for doing a global refresh across the entire repo (which would otherwise be tedious to do by hand because the projects must be built in dependency order).

Config

Note: as of v2.x the config file was renamed from .liferaynpmscriptsrc to npmscripts.config.js

If you need to add additional configuration you can do so by creating a npmscripts.config.js file at the root of your project. The default configuration of this file can be seen here.

preset

npmscripts.config.js allows for a preset option which is a pre-defined configuration. By default @liferay/npm-scripts uses its own bundled "preset-standard". If you want to create your own preset, you need to create an npm package or a local dependency. You can also extend from a preset by creating a npmscripts.config.js that looks something like...

module.exports = {
	preset: 'path/to/some/dependency',
};

// or npm package (this needs to also be specified in your package.json)

module.exports = {
	preset: 'my-cool-preset',
};

If you want to extend from the standard preset and then add an additional dependency, you will have to do something like...

const standardPreset = require('@liferay/npm-scripts/src/presets/standard/index');

module.exports = {
	preset: '@liferay/npm-scripts/src/presets/standard/index',
	build: {
		dependencies: [...standardPreset.build.dependencies, 'asset-taglib'],
	},
};

If you just set dependencies to be ['my-new-dependency'], it will override the existing dependencies from the standard preset.

Other Config

If you need more flexibility over Babel or the bundler. You can still add a .babelrc.js or .npmbundlerrc which will be merged with the default settings this tool provides. Default Babel Config, Default Bundler Config

Want to use a different NODE_ENV? Try doing something like

NODE_ENV=development liferay-npm-scripts build

Appendix: stylelint rules

The shared stylelint configuration lists the rules that are activated from among the bundled rules in addition to the following custom rules that we've developed:

• liferay/no-block-comments: Disallows block-style comments (/* ... */).
• liferay/no-import-extension: Disallows the use of an explicit ".scss" extension in Sass @import statements.
• liferay/single-imports: Requires one @import statement per imported resource.
• liferay/sort-imports: Requires @import statements to be alphabetically sorted (separate groups of imports with a blank line to force manual ordering).
• liferay/trim-comments: Trims leading and trailing blank lines from comments.