The purpose of this tool is to compile JavaScript, TypeScript, Sass, and other file types into minified bundles with source maps.
https://github.com/tangibleinc/tangible-roller
Node.js version 12 or higher is required.
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
.
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.
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]
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.
The required config property build
is an array of tasks.
Each task is an object with the following properties:
-
src
- Source file with extensionjs
,jsx
,ts
,tsx
,scss
, orhtml
-
dest
- Destination file with extensionmin.js
,min.css
, orhtml
During development, the source files are watched for any changes, and rebuilt as needed.
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 modulesreact
andreact-dom
are aliased topreact/compat
-
wp
- Import modulesreact
andreact-dom
are aliased to global variablewp.element
. Also, import modules@wordpress/*
are aliased to properties under global variablewp
.
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 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.)
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 is3000
To start your own server, define the node
property.
-
node
- Require script file path
This can be used with or without the dir
property.
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.
format: 'src'
format: [
'assets',
'!assets/build',
'**/*.php',
'!test'
]
Run the archive
command to create a zip package of the project.
It requires the config property archive
. It is an object with
-
src
- Source of all files: string or an array of path patterns to match -
dest
- Path to destination file with extension.zip
-
exclude
- Optional: String or an array of path patterns to match folders and files to exclude from the package
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 insrc
property.