mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-19 07:56:38 +02:00
178 lines
5.9 KiB
Markdown
178 lines
5.9 KiB
Markdown
# Client-side build tooling
|
|
|
|
Core JavaScript, CSS, and thirdparty dependencies are managed with the build tooling
|
|
described below.
|
|
|
|
Note this only applies to core SilverStripe dependencies, you're free to manage
|
|
dependencies in your project codebase however you like.
|
|
|
|
## Installation
|
|
|
|
The [NodeJS](https://nodejs.org) JavaScript runtime is the foundation of our client-side
|
|
build tool chain. If you want to do things like upgrade dependencies, make changes to core
|
|
JavaScript or SCSS files, you'll need Node installed on your dev environment. Our build
|
|
tooling supports the v6.x (LTS) version of NodeJS.
|
|
|
|
If you already have a newer version of Node.js installed, check out the
|
|
[Node Version Manager](https://github.com/creationix/nvm) to run multiple versions
|
|
in your environment.
|
|
|
|
Since we're compiling SVG icons, you'll also need to compile native Node addons,
|
|
which requires `gcc` or a similar compiler - see [node-gyp](https://github.com/nodejs/node-gyp#installation)
|
|
for instructions on how to get a compiler running on your platform.
|
|
|
|
[yarn](https://yarnpkg.com/) is the package manager we use for JavaScript dependencies.
|
|
The configuration for an npm package goes in `package.json`.
|
|
You'll need to install yarn after Node.js is installed.
|
|
See [yarn installation docs](https://yarnpkg.com/en/docs/install).
|
|
We recommend using `npm` which comes with Node.js to install it globally.
|
|
|
|
```
|
|
npm install -g yarn
|
|
```
|
|
|
|
Once you've installed Node.js and yarn, run the following command once in each core module folders:
|
|
|
|
```
|
|
yarn
|
|
```
|
|
|
|
## The Basics: ES6, Webpack and Babel
|
|
|
|
[ECMAScript 6](https://github.com/lukehoban/es6features](https://github.com/lukehoban/es6features) (ES6)
|
|
is the newest version of the ECMAScript standard. It has some great new
|
|
features, but the browser support is still patchy, so we use Babel to transform ES6 source
|
|
files back to ES5 files for distribution.
|
|
|
|
[Webpack](https://webpack.github.io) contains the build tooling to
|
|
"transpile" various syntax patterns (ES6, SCSS) into a format the browser can understand,
|
|
and resolve ES6's `import` ([details](https://github.com/lukehoban/es6features#modules)).
|
|
Webpack provides the entry point to our build tooling through a `webpack.config.js`
|
|
file in the root folder of each core module.
|
|
|
|
[Babel](https://babeljs.io/) is a JavaScript compiler. It takes JavaScript files as input,
|
|
performs some transformations, and outputs other JavaScript files. In SilverStripe we use
|
|
Babel to transform our JavaScript in two ways.
|
|
|
|
## Build Commands
|
|
|
|
The `script` property of a `package.json` file can be used to define command line
|
|
[scripts](https://docs.npmjs.com/misc/scripts](https://docs.npmjs.com/misc/scripts).
|
|
A nice thing about running commands from an npm script is binaries located in
|
|
`node_modules/.bin/` are temporally added to your `$PATH`. This means we can use dependencies
|
|
defined in `package.json` for things like compiling JavaScript and SCSS, and not require
|
|
developers to install these tools globally. This means builds are much more consistent
|
|
across development environments.
|
|
|
|
To run an npm script, open up your terminal, change to the directory where `package.json`
|
|
is located, and run `$ yarn run <SCRIPT_NAME>`. Where `<SCRIPT_NAME>` is the name of the
|
|
script you wish to run.
|
|
|
|
### build
|
|
|
|
```
|
|
$ yarn run build
|
|
```
|
|
|
|
Runs [Webpack](https://webpack.github.io/) to builds the core JavaScript files.
|
|
You will need to run this script whenever you make changes to a JavaScript file.
|
|
|
|
Run this script with `-- --watch` to automatically rebuild on file changes.
|
|
The first `--` separator is required to separate arguments from NPM's own ones.
|
|
|
|
```
|
|
$ yarn run build -- --watch
|
|
```
|
|
|
|
*For development only*:
|
|
Run this to keep webpack automatically rebuilding your file changes, this will also include *.map files
|
|
for easier debugging. It is important to note that this should not be used for pushing up changes,
|
|
and you should run `yarn run build` after you're done.
|
|
|
|
```
|
|
$ yarn run watch
|
|
```
|
|
|
|
### css
|
|
|
|
```
|
|
$ yarn run css
|
|
```
|
|
|
|
Compiles all of the `.scss` files into minified `.css` files.
|
|
|
|
Run this script with `-- --watch` to automatically rebuild on file changes.
|
|
The first `--` separator is required to separate arguments from NPM's own ones.
|
|
|
|
```
|
|
$ yarn run css -- --watch
|
|
```
|
|
|
|
### lint
|
|
|
|
```
|
|
$ yarn run lint
|
|
```
|
|
|
|
Run linters (`eslint` and `sass-lint`) linters to enforce
|
|
our [JavaScript](/contributing/javascript_coding_conventions) and
|
|
[CSS](/contributing/css_coding_conventions) coding conventions.
|
|
|
|
### test
|
|
|
|
```
|
|
$ yarn run test
|
|
```
|
|
|
|
Runs the JavaScript unit tests.
|
|
|
|
### coverage
|
|
|
|
```
|
|
$ yarn run coverage
|
|
```
|
|
|
|
Generates a coverage report for the JavaScript unit tests. The report is generated
|
|
in the `coverage` directory.
|
|
|
|
## Requiring SilverStripe ES6 Modules in your own CMS customisation
|
|
|
|
SilverStripe creates bundles which contain many dependencies you might also
|
|
want to use in your own CMS customisation (e.g. `react`).
|
|
You might also need some of SilverStripe's own ES6 modules (e.g. `components/FormBuilder`).
|
|
|
|
To avoid double including these in your own generated bundles,
|
|
we have exposed many libraries as [Webpack externals](https://webpack.github.io/docs/library-and-externals.html).
|
|
This helps to keep the file size of your own bundle small, and avoids
|
|
execution issues with multiple versions of the same library.
|
|
|
|
In order to find out which libraries are exposed, check
|
|
the `framework/admin/client/src/bundles/` files for `require('expose?...')` statements.
|
|
|
|
A shortened `webpack.config.js` in your own module could look as follows:
|
|
|
|
```
|
|
module.exports = {
|
|
entry: {
|
|
'bundle': `mymodule/client/src/js/bundle.js`,
|
|
},
|
|
output: {
|
|
path: './client/dist',
|
|
filename: 'js/[name].js',
|
|
},
|
|
externals: {
|
|
'components/FormBuilder/FormBuilder': 'FormBuilder',
|
|
jQuery: 'jQuery',
|
|
react: 'react',
|
|
}
|
|
};
|
|
```
|
|
|
|
Now you can use the following statements in your ES6 code without double includes:
|
|
|
|
```
|
|
import react from 'react';
|
|
import jQuery from 'jQuery';
|
|
import FormBuilder from 'components/FormBuilder/FormBuilder';
|
|
```
|