@viu/launchpad
Advanced tools
Launchpad is our proven frontend build toolkit and asset pipeline to get projects off the ground quickly. It uses Gulp, Webpack and an assortment of handy tasks to develop, optimize and deploy frontends or entire static sites.
Launchpad requires NodeJS and NPM 18.16.0 or higher. We recommend using Node 22 and NVM to manage node versions.
Install VIU Launchpad into your project
npm install @viu/launchpad --save-dev
gulpfile.js to gulpfile.mjs and gulpfile.js/index.js to gulpfile.mjs/index.mjs in your package.jsonpackage.json to 22.3.0 or higher and NPM to 10.0.0 or higher. If you have build scripts or an .nvmrc file then update them too.node_modules folder or NPM LOCK files (package-lock.json, yarn.lock) and then run a complete npm install or yarn install. "config": {
"css": {
"sass": {
"silenceDeprecations": ["mixed-decls", "legacy-js-api", "import", "global-builtin"]
}
}
}
This is a major breaking update in many regards. Many dependencies have gotten major updates or they have been succeeded by more modern alternatives. Launchpad now uses Webpack 5, Dart Sass instead of Node Sass, Stylelint instead of Sasslint, eslint instead of tslint. All these changes enable Launchpad to run on Node 14+ with 16.14.* being the recommended version.
Existing projects should continue to work with a few configuration changes and linting. However support for icon font generation has been removed. If you use icon fonts, consider managing them in another tool and simply storing them in src/assets/static.
package.json to 16.14.2 or higher and NPM to 8.5.0 or higher. If you have build scripts or an .nvmrc file then update them too.node_modules folder or NPM LOCK files (package-lock.json, yarn.lock) and then run a complete npm install or yarn install."nunjucks" or "handlebars" task to the config in your package.json to continue rendering html. You can set the src files to be named *.html or rename your existing templates to .njk (Nunjucks) or .hbs (Handlebars). Both renderers can run in the same project but target files will be overwritten if both tasks export to .html.eslint replaced tslint, the eslintrc.js must be updated if Typescript is used in the project. parser: '@typescript-eslint/parser',
plugins: [
'@typescript-eslint',
'import',
],
npm start and your project should be running.npm lint to check if the updated linters and linting rules trigger new warnings or errors.Create the following folder structure or use the example configuration from the ./demo/ folder.
src/assets
fonts/ (files are copied to the root folder of the output destination)images/ (files will be optimized)sprites/ (files are merged into an SVG sprite)static/ (files are copied to the root folder of the output destination)webapp/ (files are copied to the root folder of the output destination and updated with revisioned URLs)src/components
src/data
global.json (file that holds all global data)src/design (contains the single source of truth regarding the design)
breakpoints.jsoncolors.jsonsizes.jsontypography.jsonsrc/javascripts
global.js (if you follow the example configuration below)src/stylesheets
globals.scss (if you follow the example configuration below)src/templates
layouts/**/Copy the scripts and config object from bellow into your package.json file. Adapt the config as required. The initial configuration for all tasks is found in node_modules/@viu/launchpad/gulpfile.mjs/config.json and a working demo config can be found in demo/package.json.
"scripts": {
"start": "npm run develop",
"develop": "npm run gulp",
"gulp": "gulp --gulpfile node_modules/@viu/launchpad/gulpfile.mjs/index.mjs",
"lint": "npm run gulp lint",
"production": "npm run gulp production",
"demo": "npm run gulp production && npm run gulp server"
},
"config": {
"root": { /* allows you to specify your own source and destination folders. the following values are defaults and can be omitted in your file, unless you want to change them */
"base": "../../../../",
"src": "../../../../src",
"dest": "../../../../public"
},
"tasks": {
"js": {
"entries": {
"global": [
"./global.js"
]
},
"plugins": [
{
"reference": "jQuery",
"name": "jquery"
}
]
},
"nunjucks": {
"src": "./templates/**/*.html",
"extensions": [
"html",
"json"
],
"excludeFolders": [
"layouts",
"macros",
"partials"
],
"componentExtensions": ["html"]
},
"handlebars": {
"src": "./templates/**/*.hbs",
"destExtension": "html"
},
"browserSync": {
"https": false,
"open": false,
"cors": true,
"rewrites": { "from": ".", "to": "/index.hbs"} /* for projects that use push-state and need to send the same html file for all requests */
},
"production": {
"rev": false
}
}
}
npm start
The npm start command runs the default task, defined in gulpfile.mjs/tasks/default.js. All files will compile in development mode (uncompressed with source maps). BrowserSync will serve up files to localhost:3000 and will stream live changes to the code and assets to all connected browsers. Additional BrowserSync tools are available on localhost:3001. The npm run develop command has the same effect.
Launchpad can only be run within a project. (ex. demo)
npm run lint
Runs linters on JavaScript and TypeScript (with eslint) and CSS, SCSS (with stylelint) and outputs warnings and errors according to the specified linter config. By default the subfolders vendor and generated will be excluded and files in there will not be checked.
The eslint-config inherits from the Airbnb JavaScript Style Guide and adds the environments for browser and node. Additionally the eslint-plugin import is installed to check failed imports.
CSS and SCSS is linted via stylelint. The default config extends the sass guidelines and adds stricter configuration for classic BEM conventions. Feel free to configure according to your project's specifications.
npm run production
This will compile revisioned and compressed files to ./public.
npm run demo
In addition to generating production files, this will start a static server to serve the files from http://localhost:5000. This is primarily meant as a way to preview your production build locally, not for use as a live production server.
npm run debug
This will compile and revision files to ./public, in the same way that npm run production does. However, this command will not minify / uglify your code, but rather keep the readable source.
Modular ES2021 and/or Typescript with Babel and Webpack.
Also:
Sass (indented, SCSS, or both) with JSON importer and autoprefixer based on browserlist.
Static templating with either Nunjucks or Handlebars and Webpack.
Components automatically load the json datafile (in the same folder and with the same name as the component) and combine this data object with data that can be provided directly in the template where the component is included. Data provided via the layout is overwriting the default data taken from the component folder.
Components are used via the component-tag which is not Nunjucks standard functionality but added in VIU Launchpad. usage:
{% component 'test', exampleComponentData %}
Components can also be used from within node modules. For that to work, use the following format:
{% component '::test', exampleComponentData %}
For this to work, the node module needs to be named "test" and it needs to contain an 'index.html' and an 'index.json' file (make sure to list these files in the files-property of the packages.json). To be able to use macros from node packages, reference them with their path: {% import '../node_modules/example-component/index.html' as example %} and then call as with other macros.
You may configure this task to use gulp-cached to only rebuild, if the file has actually changed during development.
In projects with many html templates, this may improve performance. As a side-effect, the templates will not be rebuilt, if only the json is edited.
"html": {
"cache": true,
},
The data/global.json and the package.json are merged recursively with the page template of the current page and the merged object is available in the template.
To use the handlebars task, just create .hbs files in your components / layouts.
The handlebars task can either be run in parallel to the html task (the handlebar task only picks up *.hbs files), or can completely replace the html task.
The demo project shows the tasks running in parallel.
To disable the nunjucks task, update the package.json:
"config": { "tasks": { "nunjucks": false, // ... } }
To disable the handlebars task, update the package.json:
"config": { "tasks": { "handlebars": false, // ... } }
Compression with imagemin (based on mozjpeg)
gulpfile.mjs/tasks/svgSprite
SVGs sprites are super powerful. This particular setup allows styling 2 different colors from your CSS. You can have unlimited colors hard coded into your SVG.
In the following example, the first path will be red, the second will be white, and the third will be blue. Paths without a fill attribute will inherit the fill property from CSS. Paths with fill="currentColor" will inherit the current CSS color value, and hard-coded fills will not be overwritten, since inline styles trump CSS values.
.sprite
fill: red
color: white
<svg xmlns="http://www.w3.org/2000/svg">
<path d="..."/>
<path fill="currentColor" d="..."/>
<path fill="blue" d="..."/>
</svg>
We've included a helper to generate the required SVG markup in src/templates/macros/helpers.html, so you can do:
{{ sprite('my-icon') }}
Which generates HTML-output like this:
<span class="sprite sprite--my-icon">
<svg viewBox="0 0 500 500"><use xlink:href=#svgicon-my-icon" /></use></svg>
</span>
Feel free to update the helper to your liking and add additional classes etc.
We recommend setting up your SVGs on a square canvas, centering your artwork, and expanding/combining any shapes of the same color. This last step is important.
The IDs of the generated sprite-symbol-references will be prefixed with svgicon- (configurable in the task svgSprite-config). It is recommend to always use a prefix for the sprite-icons, to prevent issues with ID-collision in HTML (as an example: there could be an input-field with the id email and also an icon email—they both would get the same id, which is bad).
There are some files that belong in your root destination directory that you won't want to process or revision in production. Things like favicons, app icons, etc., should go in src/static, and will get copied over to public as a last step (after revisioning in production). Nothing should ever go directly in public, since it gets completely trashed and re-built when running the default or production tasks.
There are some files that belong in your root destination directory that you want to go into webroot and be updated with revisioned URLs. Files like service workers, web workers, your manifest or .htaccess configuration should go in src/webapp and will get copied over to public. Nothing should ever go directly in public, since it gets completely trashed and re-built when running the default or production tasks.
Add capability to define build-target-specific variables. These variables can be used in JavaScript files and will be replaced to the configured value at compile-time.
config.tasks.js.targetBuildVariables
Usage:
Basic scenario would be that you want to have different build, which test different API's, for instance: Test-API on: "test.example.com" Develop-API on: "dev.example.com" Example package.JSON: (Only with specific 'develop' script. You probably have to define the other Scripts like "production_test", "production_develop" etc. as well.)
"tasks": {
"js": {
"targetBuildVariables": [
"API_USERS",
"API_PRODUCTS"
]
}
},
"scripts": {
"develop": "gulp --gulpfile node_modules/@viu/launchpad/gulpfile.mjs/index.mjs",
"develop_test": "cross-env API_USERS=test.example.com/getusers API_PRODUCTS=test.example.com/getproducts npm run develop",
"develop_dev": "cross-env API_USERS=dev.example.com/getusers API_PRODUCTS=dev.example.com/getproducts npm run develop"
}
IMPORTANT: Note the cross-env call at the beginning of the npm-scripts develop_test and develop_dev. The cross-env package will make sure that setting the environment-variable (e.g. API_USERS) will work cross-platform.
With this configuration, you can use your custom variables in your JavaScript files like following:
console.log(__API_USERS__);
console.log(__API_PRODUCTS__);
npm run develop_test
=> 'test.example.com/getusers'
=> 'test.example.com/getproducts'
npm run develop_dev
=> 'dev.example.com/getusers'
=> 'dev.example.com/getproducts'
Note: If you have set the environment variable directly via CLI, you would run 'npm run develop'.
We use SemVer for versioning. For the versions available, see the tags on this repository.
.hbs extension.demo. Fewer rules exceptions where possible.democonfig.json. Minor updates to tslint config.svgicon- (configurable) to prevent id collisions with other HTML-elementsdemo and in documentation as it has become the de-facto default for all projects at viu and for many other such build systemsbrowserlist.rc for /demo to be based on the widely accepted default/demo projectThis project is licensed under the MIT License - see the LICENSE file for details
./demo/ projectFAQs
Gulp based frontend build tool
We found that @viu/launchpad demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.