Factorial Frontend Stack

The purpose of this stack is to allow linting, building and watching of your assets, while adding as little overhead and configuration as possible to your project. core is the base package which allows you to install any of the following packages for your project:

• css
• e2e
• html
• images
• javascript
• svg
• twig

Content

• Installation
• Options
• Usage
• Commands
  • init
  • lint
  • optimize
  • build
  • watch
  • test
  • Custom commands
  • Adding additional params via CLI
  • Running a command for specific packages
• Contributing
  • Creating a release

Installation

Add core via:

yarn add @factorial/stack-core

Afterwards run

yarn factorial init

which allows you to select which packages you want to install. core will then automatically add those packages to your project and create a .factorialrc.js with the required configuration. In this file you can also add the following options.

Options

assetFolders, default: []
Asset folders for fonts, icons, etc., relative from rootFolder. These files will be copied to distFolder when creating a build.

cssFiles, default: []
The CSS entry files, relative from rootFolder. These files will be used to create a build.

cssTokens
Please refer to packages/css/README.md for more information.

distFolder, default: "dist"
The folder where the build files will be put

imageFolders, default: []
Folders that contain image files.

jsFiles, default: []
The JavaScript entry files, relative from rootFolder. These files will be used to create a build.

rootFolder, default: "src"
The root folder for jsFiles, cssFiles, assetFolders, imageFolders, svgFolders

svgFolders, default: []
Folders that contain SVG files.

targets, default:

browsers: "last 2 Chrome versions, last 2 Firefox versions, last 2 Safari versions, last 2 ios versions, last 2 ChromeAndroid versions, last 2 Edge versions";

Usage

If not already done via yarn factorial init, create the configuration file like this:

// .factorialrc.js

module.exports = {
  assetFolders: ["fonts/", "icons/"],
  cssFiles: ["index.css"],
  distFolder: "build",
  imageFolders: ["images"],
  jsFiles: ["index.js"],
  svgFolders: ["svgs"],
  rootFolder: "source",
};

NOTE: You can also omit this file if the default configuration is sufficient.

Targets

You can either set a targets or browserslist key in your package.json. The former wins over the latter.

Commands

init

yarn factorial init

This will allow you to pick the packages you want to install and afterwards create a configuration file. If it already exists, you can skip that step.

lint

yarn factorial lint

This will lint all files (found in rootFolder) based on your installed packages once.

You can also lint a specific type via e.g.:

yarn factorial lint --only css

Vice versa, if you want to lint all but one type, you can use --skip:

yarn factorial lint --skip css

Both params (--only and --skip) accept a comma separated list.

If you want to lint only staged files, you can do that by adding --staged:

yarn factorial lint --staged

Please note, that this is only supported by the css, javascript and vue packages.

optimize

yarn factorial optimize

This will optimize all files (found in rootFolder) based on your installed packages once.

You can also optimize a specific type via e.g.:

yarn factorial optimize --only svg

build

yarn factorial build

This will create the build files and sourcemaps in distFolder based on your installed packages. If they should be minified, you can run this command with setting the NODE_ENV to "production":

NODE_ENV=production yarn factorial build

When referencing/importing assets in your component files (import in your JS files or url in your CSS file), the referenced/imported files are copied into your build folder and the paths are adapted. That means, the assets are not inlined.

You can also build a specific type via e.g.:

yarn factorial build --only css

watch

yarn factorial watch

This will watch all files in rootFolder for changes and lint them. If you also want to create a build, when files changed, pass --build:

yarn factorial watch --build

If a specific command should be run every time the build has finished, you can pass that command using --afterBuild:

yarn factorial watch --build --afterBuild yarn run someCommand

If you want to exclude certain types from watching, you can do so by setting the --skip option:

yarn factorial watch --skip html

test

You can run tests based on your installed packages with

yarn factorial test

You can also test a specific type via e.g.:

yarn factorial test --only js

Custom commands

Packages can also export custom commands (e.g. sprite by the SVG package). When running a custom command, core would simply execute the related external task (while core has more sophisticated functionality for the fixed tasks).

Adding additional params via CLI

You can run lint, test and watch with additional params like this:

yarn factorial lint --fix

Every param that comes after the command name (lint, watch, test) is passed through, so you can overwrite or define settings.

NOTE:: Please note that linting runs all tasks, so additional params would passed through to all of them. This might actually cause an error when one package does not support that param and therefore throws an error. If that is the case, try running a more specific command like yarn factorial lint --only css --fix.

Passing additional params to build is not supported at the moment.

Running a command for specific packages

When running a command, you can choose to only run specific packages by using --only. Let's say, you only want to lint CSS and JS files, you could run:

yarn factorial lint --only css,js

Alternatively you can also skip packages using the --skip option:

yarn factorial lint --skip css,js

Contributing

Linting

You can lint this project by running:

yarn lint

This will use the same eslint configuration as exposed by the javascript package.

Committing

We are using Conventional commits.

Creating a release

To create a release, please run any of:

yarn core:release
yarn css:release
yarn e2e:release
yarn html:release
yarn images:release
yarn javascript:release
yarn svg:release
yarn twig:release

This will automatically update the changelog based on the commit messages.

NOTE: This only updates the changelog, creates a tag and commit. It does not push to GitHub or publish the package on npm. This needs to be done manually.