systematic
Advanced tools
An opinionated, mostly framework-agnostic toolchain to package ES6 applications and libraries for the browser.
Features :
npm install systematic
The file structure expected for your application or library.
├── dist # what gets built
│ ├── app.settings.js
│ ├── bundle.js
│ ├── bundle.js.map
│ ├── translations.json
│ ├── an_asset.png
│ └── index.html
|
├── src # your code
│ ├── some_module/
| | ├── enums.js
| | ├── index.js
| | ├── index.spec.js
| | └── models.js
| |
│ ├── utils.js
│ ├── index.html # HTML entry point (applications)
│ ├── index.spec.js # A test spec file
│ └── index.js # JS entry point
|
├── webpack.config.js # Webpack config, inherits systematic's
├── Makefile # Your application's Makefile
└── systematic.ini # systematic config
Systematic requires a systematic.ini configuration file in the root folder of your project.
[build]
; Mandatory
; Project type, can be application, component or library. An app will need an HTML entry point
type = library
; Optional, default: vanilla
; Build profile, can be vue, react, ...
profile = vanilla
; Optional, default: dist
; The relative path for the build output, defaults to dist
output_dir = dist
; Optional, default: src
; The relative path to the source dir
src_dir = src
; Optional, default: /
; The path where the application will be hosted in production (eg. '/app/')
public_path = /
; Optional, default is blank
; The locales to generate translation files
locales = en_US en_GB
; Optional, default is []
; Adds entries to the noParse config of webpack; large libraries without a require can go there.
; It's only an optimization to speed up compilation in some cases, but it may break the build.
no_parse[] = vuetify
; Optional, default is []
; In "component" or "library" mode, this enables you to actually IMPORT adependency within the bundle
; instead of having them all out. For instance this may be useful for undistributed dependencies, or
; proprietary ones.
keep_dependency[] = lodash
; Optional, default is 0
; Analyze the bundle right after build to check the sizes.
analyze = 1
[serve]
; Interface to listen
host = 127.0.0.1
; Optional, default: 8080
; The network port to access local website, if it's an app
port = 8080
[test]
; Optional, default: <YOUR_SRC_DIR>/**/*tests.js
; All files matching this pattern will be processed with Jest
; It is relative to the root given to the Jest config, usually the project root
file_pattern = src/**/*tests.js
Systematic uses GNU make. Create a Makefile at the root of your project, to import systematic commands:
include node_modules/systematic/mk/main.mk
# Your own commands
The default source folder (containing your source code and tests) is src. It must contain an entrypoint file named index.js. Example:
import somelib from 'some-lib'
import m1 from './module1'
import m2 from './module1'
// Bootstrap your project here
somelib.bootstrap(m1, m2)
If your project is an application, there must be an HTML entry point named index.html in the source folder, containing the primary page. Your JS entry point will be automatically added.
Example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Your website</title>
</head>
<body>
<!-- Some application bootstrap !-->
</body>
</html>
make help gives a list of all commands.
make serve to run a local server.
make dist for a prod build.
make test runs all test that match the test file pattern (default **/*tests.js).
make livetest run test continuously, when a file changes.
make makemessages extract translations from your HTML and JS files using easygettext.
The resulting .po files will be in /locale.
make translations generates a JSON file from them, located at dist/translations.json. It is automatically run with serve, dist and test.
You can then load them in your JS as an object:
import translations from 'dist/translations.json'`
make settings generates a file dist/app.settings.js from all INI files in src/settings/ if your project is an application.
Settings files are processed in alphabetical order, the last one overriding the previous. It is automatically run with serve, dist and test.
The generated file dist/app.settings.js needs to be included in your index.html, since it will not be added by Webpack.
After the app is deployed, you might want to change the settings. This part is not handled by systematic, but we recommand to regenerate the settings from INI files. INI files are an ideal format, as it is not error prone, ensures only settings values are changed and no javascript is added.
From systematic.ini's profile option. For now, only the angular profile is supported on top of the
natural vanilla profile.
Value : angular
Adds the ng-annotate Babel plugin.
Value : vue
Adds translation management with the vue translation token.
It's possible to override the build or test config by adding config files at the root of the projet.
For Webpack: webpack.config.js. Example :
// import systematic default webpack settings
const webpackDefaults = require('systematic').webpack_get_defaults(__dirname)
// optional overrides (an example !)
webpackDefaults.module.loaders.push({ test: /\.file_extension_example$/, loader: 'my-loader' })
module.exports = webpackDefaults
For Jest: jest.conf.js. Example:
// import systematic default jest settings
const jestDefaults = require('systematic').jest_get_defaults(__dirname)
// optional overrides example
jestDefaults.plugins.push('my-plugin')
module.exports = jest => jest.set(jestDefaults)
A component is halfway between a library and an application. You get to have an index.html page that is useful for development, but the dependencies aren't bundled with the final package, just like a library.
You also have the choice of having the component used directly within a page, without being required from within another JS application that goes through webpack.
In that regard, you have to pay attention to NOT import your dependencies using Webpack-based import feature and use the /* global _, L */
notation in your sources (use import in your tests, why not) so that your application will try and find those symbols on window;
also, use the keep_dependency feature in your configuration file for any dependency yo uwant bundled with.
When building a library, we don't want the dependencies included in the bundle. It can cause version conflict with other packages or duplicated library imports.
Systematic will set all dependencies as webpack "externals", which means they have to be required by the app.
Systematic uses Babel to transpile ES6, ES6+ code to plain ES5.
Polyfilling is still needed:
console.log('blah'.repeat(2)) // Dynamically evaluated so transpilation lets it untouched
You have two solutions:
babel-polyfill just like in tests. You have to include it in the app entry point, before any other import:import 'babel-polyfill'
This has the advantage of simplicity and consistency across browsers but it pollutes the global scope quite broadly.
core-js (on which babel-polyfill is built) on a per case basis:import _repeat from 'core-js/library/fn/string/repeat';
const myStr = _repeat('blah', 2);
This method is preferred as you can precisely choose what's being added to the environment. But it's more tedious.
Avoid a global polyfill as it modifies global entities such as "Function" or "String".
Use precise imports from core-js as described above if needed.
You should probably allow more watchers on your machine, see how on webpack's doc.
MIT
FAQs
Simple tooling for frontend apps
The npm package systematic receives a total of 6 weekly downloads. As such, systematic popularity was classified as not popular.
We found that systematic demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 9 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
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.