@tangible/roller NPM

Tangible Roller

Build project assets using Rollup and ESBuild

The purpose of this tool is to compile JavaScript, TypeScript, Sass, and other file types into minified bundles with source maps.

Source code

https://github.com/tangibleinc/tangible-roller

Requirement

Node.js version 18 or higher is required.

Install

Install in your project as a dependency for development.

npm install --save-dev @tangible/roller

This provides a local command called roll, which can be run using npm or npx.

Scripts

Add the following NPM scripts in your project's package.json file.

{
  "scripts": {
    "dev": "roll dev",
    "build": "roll build",
    "format": "roll format"
  }
}

These can be run from the terminal when you're inside the project folder.

Usage

Build for development and watch files for changes

npm run dev

Press CTRL + C to stop.

Build for production

npm run build

Format files to code standard

npm run format

Run TypeScript file

Builds the given file and runs it.

npx roll run [file] [...options]

Example:

npx roll run index.ts

Create zip package for archive

npx roll archive

Other commands

Use npx, which is bundled with Node.js, to run other builder commands.

npx roll [command]

Run the above without any command to see a help screen.

Project directory

Optionally specify a child directory as project root

npm run [command] [folder]
npx roll [command] [folder]

The build and format commands support multiple projects.

npm run build [...folders]
npm run format [...folders]

Config

Before starting, the builder needs a configuration file.

Create a file called tangible.config.js in your project folder.

Example:

module.exports = {
  build: [
    {
      src: 'src/index.js',
      dest: 'build/app.min.js'
    },
    {
      src: 'src/index.scss',
      dest: 'build/app.min.css'
    },
  ],
  format: 'src'
}

The config file exports an object with the following properties.

build - Array of build tasks
serve - Optional: Server config
format - Optional: Format config

Build

The required config property build is an array of tasks.

Each task is an object with the following properties:

src - Source file with extension js, jsx, ts, tsx, scss, or html
dest - Destination file with extension min.js, min.css, or html

During development, the source files are watched for any changes, and rebuilt as needed.

React mode

Files with React JSX syntax must have extension jsx or tsx. They will automatically import React.

The optional task property react sets the React mode.

Its value is one of:

react (default)
preact - Import modules react and react-dom are aliased to preact/compat
wp - Import modules react and react-dom are aliased to global variable wp.element. Also, import modules @wordpress/* are aliased to properties under global variable wp.

Aliases

The following optional task properties perform various substitutions.

alias - Map import module name to target module name or file path
importToGlobal - Map import module name to global variable name; supports dynamic name such as @example/*, for which a function should be given that takes the module name and returns the variable name
globalToImport - Map global variable name to import module name
replaceStrings - Map string to another string

HTML

HTML files are compiled using a template engine called eta. Visit the link for its documentation.

For the HTML build task, the src property can be a single file name or glob syntax for multiple files. In the latter case, the dest property must specify the destination directory name. (It can be also for single file.)

Serve

If an optional config property serve is defined, a static file server is started during the dev and serve command.

It is an object with:

dir - Serve from directory - Relative path such as .
port - Serve from port - Optional: default is 3000

To start your own server, define the node property.

node - Require script file path

This can be used with or without the dir property.

Format

Run the format command to automatically format files to code standard.

It requires the config property format, which is a string or an array of path patterns to match.

Use * as wildcard, ** to match any directory levels, and ! to exclude pattern. Use {} and a comma-separated list to match multiple items.

Folders named node_modules and vendor are excluded by default.

Example: All files in directory

format: 'src'

Example: Plugin

format: [
  'assets',
  '!assets/build',
  '**/*.php',
  '!test'
]

Install dependencies

Run the install command to install dependencies for production or development.

npx roll install

This requires the config property install. It is a list of objects which define a dependency.

zip - Zip package URL, or
git - Git repository URL
branch - Git branch - Optional: default is main
dest - Path to destination folder

It can be useful to run this as postinstall script, to prepare a project.

Dev dependencies

An optional config property installDev defines dependencies needed only during development, such as third-party plugins or companion libraries.

These can be installed with the --dev option.

npx roll install --dev

Update

To update the dependencies, run the update command. Git repositories pull from remote origin, and zip sources are downloaded optionally by prompting yes or no.

Use the --dev option to update dev dependencies also.

Comparison with Tangible Builder

Tangible Roller is the next generation of the build tool. It's much faster, and better compatible with Node.js version 12 and above.

The configuration schema in tangible.config.js is almost the same, except:

JS files with React JSX syntax must have file extension .jsx
For each build task's config, the watch property is no longer needed and can be removed. All imported files are automatically watched for changes.
Similarly, the task property (js/sass/html) can be removed. The task type is automatically inferred from the file extension in src property.