@tresinternet/trex
v5.1.1
Published
TRES' asset building tool
Downloads
94
Keywords
Readme
TREX
TREX is TRES internet's internal build- and development tool.
Build
TREX can be used to build the Design System, used for development and presentation purposes. This tool executes the following build-steps:
assets
clean
html
icons
library
mail
optimize
pin
scripts
styles
The purpose of each step is described below.
Assets
Copy all assets to the corresponding folder. Generate *.webp
-files for all images.
Clean
Clear all previously generated files
HTML
Parse all Nunjunck-templates and save them as *.html
Icons
Copy all icons to the corresponding folder
Library
Copy all Design System files to the corresponding folder
Parse all *.mjml
-templates and save them as *.html
Optimize
Optimize all images and SVG
-files
Pin
Generate a pincode.config
-file that prevents unauthorized access to the deployed Design System
Scripts
Depending on the scripts.useModernJs
-property, the following steps are executed:
Modern JavaScript
Compile all *.js
- and *.ts
-files and run them through Webpack for TypeScript and ES6 support.
Legacy JavaScript
Minify all *.js
files and run them trough Babel for ES6 support.
Uses the include()
-plugin to import javascript files from within other javascript files.
Styles
Parse all *.scss
-files, compile them, run them trough PostCSS, generate sourcemaps and save them as *.css
Deploy
This tool is also used to deploy the assets to a server. It omits a few steps from the build
-task, and executes the following steps:
assets
clean
html
icons
scripts
styles
Serve
TREX can also be used to serve the Design System locally. It watches for changes in the source files and automatically rebuilds the Design System. Changes in the Design System are automatically reloaded in the browser using BrowserSync.
The following scripts are executed when a file is changed:
assets
html
icons
library
mail
optimize
scripts
styles
The directories that are watched for changes can be configured in the config
-object, as described below.
Usage
Install
pnpm i @tresinternet/trex
Run dev-server
npx gulp serve
The Design System should be build at least once for the dev-server to work.
Build Design System
npx gulp build
Build for Production
npx gulp deploy
Migration
v3.x.x to v5.x.x
The following configuration keys are required in the config
-object:
config.scripts
- Script configuration
Example values:
config: {
scripts: {
useModernJs: true,
minify: { "builtIns": false, "mangle": true }
},
}
The following configuration keys are optional in the config
-object:
config.paths.assets.webp
- WebP input paths. Make sure the input paths only contain images.
Example values:
config: {
paths: {
assets: {
webp: [
path.posix.join(base.dest, "assets", "images", "**", "*.jpg"),
path.posix.join(base.dest, "assets", "images", "**", "*.jpeg"),
path.posix.join(base.dest, "assets", "images", "**", "*.png")
]
}
}
}
Configuration
TREX can be configured by adding a gulpfile.js
-file to the root of your project.
Gulpfile.js
The gulpfile.js
-file should init the TREX-package. This function takes the gulp
-task and a config
-object as parameters.
const gulp = require('gulp');
const trex = require('@tresinternet/trex');
const config = {
// Config
};
trex.init(gulp, config);
Config
The config
-object has the following properties:
| Property | Description |
| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| src
| The base path of the source directory |
| dest
| The base path of the destination directory |
| paths
| An object containing the paths of the source, destination and watch directories. Accepts additional properties for certain tasks |
| njk
| An object containing the options for the Nunjucks-parser |
| postcss
| An object containing the options for the PostCSS-parser |
| scripts
| An object containing the options for the Javascript-parser |
| pin
| The pincode used to prevent unauthorized access to the deployed Design System |
Paths
The paths
-property contains the paths of the source, destination and watch directories. It accepts additional properties for certain tasks.
All paths are defined as glob
-patterns and accept an array of globs. See https://docs.python.org/3/library/glob.html for more information. Also, the path.posix.join
-function is used to join the paths. See https://nodejs.org/api/path.html#path_path_posix_join_paths for more information.
| Path property | Description | Used by tasks |
| ------------- | ---------------------------------------------------------------------------------------------- | ------------- |
| input
| The glob that is used as the entry point for the specific tasks | All |
| output
| The output directory of the assets generated for this task | All |
| watch
| The glob that is used to watch for changes | All |
| path
| The path of the source directory. Necessary for the Nunjucks-parser | html
|
| index
| The path of the index file. Used as entry-point for the Design System | library
|
| serve
| The path of the directory that is served by the dev-server | library
|
| webp
| The path of the images that should be converted to webP-images. Make sure you only pass images | assets
|
| callback
| The callback-function that is executed after the task is finished | optimize
|
An example of the paths
-property:
paths: {
clean: {
input: [
path.posix.join(base.dest, '**', '*'),
]
},
styles: {
input: path.posix.join(base.src, 'stylesheets', '*.scss'),
output: [path.posix.join(base.dest, 'assets/stylesheets')],
watch: [
// In addition to the `*.scss`-files, the `tailwind.config.js`-file is also watched for changes.
path.posix.join(base.src, 'stylesheets', '**', '*.scss'),
'./tailwind.config.js'
]
},
html: {
input: [
path.posix.join(base.src, 'html', '**', '*.njk'),
],
output: path.posix.join(base.dest, 'html'),
path: path.posix.join(base.src, 'html'),
watch: path.posix.join(base.src, 'html', '**', '*.njk')
},
mail: {
input: [path.posix.join(base.src, 'html', '**', '*.mjml')],
output: path.posix.join(base.dest, 'html'),
watch: path.posix.join(base.src, 'html', '**', '*.mjml')
},
assets: {
input: path.posix.join(base.src, 'assets', '**', '*'),
output: path.posix.join(base.dest, 'assets'),
watch: path.posix.join(base.src, 'assets', '**', '*')
},
library: {
input: path.posix.join(base.src, 'library', '**', '*'),
output: path.posix.join(base.dest, 'library'),
serve: path.posix.join(base.dest),
index: path.posix.join('library', 'index.html'),
watch: path.posix.join(base.src, 'library', 'library.json')
},
scripts: {
input: path.posix.join(base.src, 'scripts', '*.js'),
output: path.posix.join(base.dest, 'assets/scripts'),
watch: path.posix.join(base.src, 'scripts', '**', '*.js')
},
optimize: {
input: [
path.posix.join(base.src, 'assets', 'images', '**', '*'),
path.posix.join(base.src, 'html', 'icons', '**', '*')
],
// The output-directory is omitted, because the optimize-task optimizes the images and icons in-place.
watch: [
path.posix.join(base.src, 'assets', 'images', '**', '*'),
path.posix.join(base.src, 'html', 'icons', '**', '*')
],
callback: function() {
// Inject the icons into the Nunjucks-parser
config.njk.data.icons = dirTree('./src/html/icons', {
attributes: ['type', 'extension']
});
}
},
icons: {
input: path.posix.join(base.src, 'html', 'icons', '**', '*'),
output: path.posix.join(base.dest, 'icons'),
watch: path.posix.join(base.src, 'html', 'icons', '**', '*')
}
},
In order to use base.dest
and base.src
in the paths
-property, the base
-object is defined as follows:
const base = {
src: './src',
dest: './dist'
};
Nunjucks
To configure the Nunjucks-parser, the njk
-property is used. All properties are nested in a data
-object. The following properties should be defined:
| Property | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| base
| The base path of the Design System. Should be an empty string when served locally, or the URL of the base path when served online |
| client
| The name of the client. Used to display the title of the Design System |
| tailwind
| The path of the tailwind.config
-configuration file. Used to extract some data for the Design System |
| icons
| The path of the icons-directory, wrapped in a dirTree
-function. Used to display the icons |
An example of the njk
-property:
njk: {
data: {
base: process.argv.find(arg => arg === 'serve' || arg === 'build' || arg === 'html') ? '' : 'https://example.com',
client: 'TRES internet',
tailwind: require('./tailwind.config'),
icons: dirTree('./src/html/icons', {
attributes: ['type', 'extension']
})
}
}
Postcss
To configure the Postcss-parser, the postcss
-property is used. The following properties should be defined:
| Property | Description |
| --------- | --------------------------- |
| plugins
| An array of Postcss-plugins |
For more information about the plugins, see the PostCss documentation at https://postcss.org/.
An example of the postcss
-property:
postcss: {
// Only use PurgeCSS when building or deploying the Design System, or when running the styles-task directly
plugins: process.argv.find(arg => arg === 'styles' || arg === 'build' || arg === 'deploy') ? [
require('tailwindcss'),
postcssPresetEnv({
// ...
}),
require('@fullhuman/postcss-purgecss')({
content: [
path.posix.join(base.src, '/**/*.njk'),
path.posix.join(base.dest, '/**/*.html')
],
defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
})
] : [
require('tailwindcss'),
postcssPresetEnv({
// ...
}),
]
},
Scripts
To configure the Javascript-parser, the scripts
-property is used. The following properties can be defined:
| Property | Description |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| minify
| The babel-minify options - https://babeljs.io/docs/gulp-babel-minify#minifyoptions. Set to false
to disable minification |
BrowserSync
To configure the BrowserSync-server, the browserSync
-property is used. See the BrowserSync documentation for more information.
An example of the browserSync
-property:
browserSync: {
ghostMode: false,
},
Pin
To protect the Design System from being accessed by unauthorized users, the pin
-property is used. This is a simple 5-digit pin.
Full example
/* global require process */
const dirTree = require('directory-tree');
const gulp = require('gulp');
const path = require('path');
const postcssPresetEnv = require('postcss-preset-env');
const trex = require('@tresinternet/trex');
const base = {
src: './src',
dest: './dist'
};
const config = {
src: base.src,
dest: base.dest,
paths: {
clean: {
input: [
path.posix.join(base.dest, '**', '*'),
]
},
styles: {
input: path.posix.join(base.src, 'stylesheets', '*.scss'),
output: [
path.posix.join(base.dest, 'assets/stylesheets'),
],
watch: [
path.posix.join(base.src, 'stylesheets', '**', '*.scss'),
'./tailwind.config.js'
]
},
html: {
input: [
path.posix.join(base.src, 'html', '**', '*.njk'),
path.posix.join('!', base.src, 'html', '**', '_macros', '*.njk')
],
output: path.posix.join(base.dest, 'html'),
path: path.posix.join(base.src, 'html'),
watch: path.posix.join(base.src, 'html', '**', '*.njk')
},
mail: {
input: [path.posix.join(base.src, 'html', '**', '*.mjml')],
output: path.posix.join(base.dest, 'html'),
path: path.posix.join(base.src, 'html'),
watch: path.posix.join(base.src, 'html', '**', '*.mjml')
},
assets: {
input: path.posix.join(base.src, 'assets', '**', '*'),
output: path.posix.join(base.dest, 'assets'),
watch: path.posix.join(base.src, 'assets', '**', '*')
},
library: {
input: path.posix.join(base.src, 'library', '**', '*'),
output: path.posix.join(base.dest, 'library'),
serve: path.posix.join(base.dest),
index: path.posix.join('library', 'index.html'),
watch: path.posix.join(base.src, 'library', 'library.json')
},
scripts: {
input: path.posix.join(base.src, 'scripts', '*.js'),
output: path.posix.join(base.dest, 'assets/scripts'),
watch: path.posix.join(base.src, 'scripts', '**', '*.js')
},
optimize: {
input: [
path.posix.join(base.src, 'assets', 'images', '**', '*'),
path.posix.join(base.src, 'html', 'icons', '**', '*')
],
watch: [
path.posix.join(base.src, 'assets', 'images', '**', '*'),
path.posix.join(base.src, 'html', 'icons', '**', '*')
],
callback: function() {
config.njk.data.icons = dirTree('./src/html/icons', {
attributes: ['type', 'extension']
});
}
},
icons: {
input: path.posix.join(base.src, 'html', 'icons', '**', '*'),
output: path.posix.join(base.dest, 'icons'),
watch: path.posix.join(base.src, 'html', 'icons', '**', '*')
}
},
njk: {
data: {
base: '',
client: 'TRES internet',
tailwind: require('./tailwind.config'),
icons: dirTree('./src/html/icons', {
attributes: ['type', 'extension']
})
}
},
postcss: {
plugins: process.argv.find(arg => arg === 'styles' || arg === 'build') ? [
require('tailwindcss'),
postcssPresetEnv({
}),
require('@fullhuman/postcss-purgecss')({
content: [
path.posix.join(base.src, '/**/*.njk'),
path.posix.join(base.dest, '/**/*.html')
],
defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || [],
})
] : [
require('tailwindcss'),
postcssPresetEnv({
}),
]
},
browserSync: {
ghostMode: false,
},
pin: 12345
};
trex.init(gulp, config);