README.md 8.9 KB
Newer Older
Philipp Nowinski's avatar
Philipp Nowinski committed
1
[![sgalinski Internet Services](https://www.sgalinski.de/fileadmin/files/for-external-usage/logo.svg  "sgalinski")](https://www.sgalinski.de/typo3-produkte-webentwicklung/gulp-frontend-toolchain/)
Philipp Nowinski's avatar
Philipp Nowinski committed
2

3
# sgalinski CLI Task Runner
Philipp Nowinski's avatar
Philipp Nowinski committed
4

Philipp Nowinski's avatar
Philipp Nowinski committed
5
> **Please note:**
6
> The CLI is intended to be used with bash or zsh.
Philipp Nowinski's avatar
Philipp Nowinski committed
7

Philipp Nowinski's avatar
Philipp Nowinski committed
8
## Installation
Philipp Nowinski's avatar
Philipp Nowinski committed
9

10 11 12 13 14 15 16 17
Move the 'sgc-core' folder inside your project root and execute the install script. If you are using composer, you
can install the sgc by running

```bash
composer requre sgalinski/sgc-core
```

Then run the installer:
Philipp Nowinski's avatar
Philipp Nowinski committed
18 19

```bash
20 21 22 23 24 25 26 27 28
./sgc-core/install.sh
```

### Local Installation

If you don't want to install the sgc command globally (e.g. in a server environment), just pass the --local flag to the install script.

```bash
./sgc-core/install.sh --local
Philipp Nowinski's avatar
Philipp Nowinski committed
29 30
```

Philipp Nowinski's avatar
Philipp Nowinski committed
31 32
### Windows

33 34 35 36 37 38
> **Please note:**
> While it is theoretically possible to run the sgc on Windows, this option is neither thoroughly tested,
> nor is it advertised in any way. Things might have improved with Bash on Windows, but right now we do not have
> the capacity to actively provide a stable version for Windows. Don't hesitate to [get in touch with us](https://www.sgalinski.de/contact/)
> if you think you might be able to help out!

Philipp Nowinski's avatar
Philipp Nowinski committed
39 40 41 42 43 44 45
If you want to install the SGC on a Windows machine, there are some additional preparations are required:

* All commands are to be executed in **git-bash** window, do not try to use the cmd! You'll probably already have the git-bash
installed if you are using git for Windows.
* Install NVM for Windows: https://github.com/coreybutler/nvm-windows
* You have to open git-bash with administrator privileges to run the installation script 

46 47 48 49 50 51 52 53 54 55
## SGC Releases

Please note that the following steps need to be executed before a new release:

* Raise version number (according to SEMVER) in the following files:
 * composer.json
 * package.json
 * core/version.conf
* Add a git-tag with the new version number

56 57 58 59 60 61 62 63 64 65
## Available Commands

* ```sgc```: Loads a BrowserSync instance and listens for file changes (triggers css and js compilation)
    * ```sgc -s```: Loads the BrowserSync instance, but prevents it from automatically open in the browser
    * ```sgc -d domain.dev```: Starts the BrowserSync instance with the specified dev-domain (must be configured in .sgc-config.json) 
* ```sgc css```: Runs the CSS QA task (linting) and compiles all CSS files
* ```sgc css:qa```:  Runs only the CSS QA task (linting)
* ```sgc js```: Runs the JS QA task (linting) and compiles all JS/TS files
* ```sgc js:qa```: Runs only the JS QA task (linting)
* ```sgc releaseExtension --ext {extension name}```: Starts a questionaire wich helps to update an extension according to SEMVER (updates composer.json and ext_emconf.php)
66 67
* ```sgc images```: runs the image optimizer on all images inside the folder you specified in the directories section of the .sgc-config.json
* ```sgc images:uploaded```: runs the image optimizer on all images inside the folder you specified in the images.optimize section of the .sgc-config.json
Philipp Nowinski's avatar
Philipp Nowinski committed
68
* ```sgc open {sites}``` Opens a set of URLs in the default browser, that you can define inside your .sgc-config.json
69 70 71

You can call every command with the ```--production``` flag. This will prevent the toolchain from generating SourceMaps.

Philipp Nowinski's avatar
Philipp Nowinski committed
72 73
## Configuration

74 75 76 77 78 79
To configure the frontend build process to your needs, you will have to modify the .sgc-config.json that the installer
will put into your projects root-directory.

> **Heads up**
> Prior to SGC 1.2.0, the config file was named config.json and lived inside the sgc-core/gulp folder. If this file is
> still present, sgc will use it instead of the .sgc-config.json. It is highly advised to use .sgc-config.json instead!
Philipp Nowinski's avatar
Philipp Nowinski committed
80 81 82

### directories

83
Holds the paths to the css, sass, javascript, images, sourcemaps and inline-svgs, relative to the extensions root.
Philipp Nowinski's avatar
Philipp Nowinski committed
84 85 86

* webPath: *path to your extension folder as seen from the web*
* basePath: *path to your extension folder as seen from the filesystem*
Philipp Nowinski's avatar
Philipp Nowinski committed
87

88
### abovethefold 
Philipp Nowinski's avatar
Philipp Nowinski committed
89 90 91 92 93 94 95 96

Configuration for the critical path css.

* template: *path to the src template*
* dest: *path to the destination*

### js

Philipp Nowinski's avatar
Philipp Nowinski committed
97 98 99
The SGC will support you with writing next generation JavaScript and executing it in Browsers today, by transpiling it
to EcmaScript 5 compliant code. Currently EcmaScript 6 Syntax and TypeScript are supported.

100
* compiler: *es6|typescript* 
Philipp Nowinski's avatar
Philipp Nowinski committed
101
* libraryPaths: *additional locations that should be searched when resolving CommonJS require statements*
Philipp Nowinski's avatar
Philipp Nowinski committed
102 103
* excludeFromQa: *glob patterns with locations that hold JavaScript that does not need to be linted (vendor stuff)

104
### images 
Philipp Nowinski's avatar
Philipp Nowinski committed
105 106 107 108 109 110 111

* optimize: *locations of user uploaded images that should be optimized*

### extensions

A list of extensions that should be included in the watch task. Please note, that the very first extension in this list is expected to be your project_theme.

Philipp Nowinski's avatar
Philipp Nowinski committed
112 113 114 115 116 117 118 119
### browsersync

BrowserSync is a neat tool that will help you during the development and testing process. When you run `sgc`, it will spin
up a small webserver that proxies the URL specified in your .sgc-config.json. If you change a JavaScript or Sass file
inside an extension that is on your watch list (see the option above), BrowserSync will automatically reload the page
or inject your changes directly into the browser. You can also open several instances of the BrowserSync URL in different
browser windows and BS will take care of synchronizing all input and scroll events between them.

Philipp Nowinski's avatar
Philipp Nowinski committed
120 121
## Usage
You can run a specific task on a specific component, or start a watcher that will fire up BrowserSync and run tasks when
Philipp Nowinski's avatar
Philipp Nowinski committed
122
source files change. Extensions that will be watched are defined in your .sgc-config.json file for each project.
Philipp Nowinski's avatar
Philipp Nowinski committed
123 124 125 126

If you run a specific task, you need to specify the extension you want the task to run on with the --ext parameter.

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
127
sgc css --ext project_base
Philipp Nowinski's avatar
Philipp Nowinski committed
128 129 130 131 132 133 134
```

There are a few available tasks you need to remember:

### default/watch task

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
135
sgc
Philipp Nowinski's avatar
Philipp Nowinski committed
136 137 138 139 140 141
```
Starts a project wide watcher that will trigger the css/javascript task when you change any .scss, or .js-file and opens
the website in your browser, as a browsersync session (changed js and css will automatically get injected when recompiled).

*Hint:* If you already have a browsersync instance open in your browser, you can pass the argument -s to restart the session without opening a browser.

Philipp Nowinski's avatar
Philipp Nowinski committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
### css:svg task (will be called by the css task automatically)
```bash
sgc css:svg --ext [extension name]
```

Triggers the generation of Sass-mixins for all SVGs inside the given directory. Each mixin will enable the usage of the
associated SVG as a css background image.

```scss
@import 'svg'; // imports the file with the generated mixins (inside your Sass-root)

.icon-globe {
    @include inline-svg($icon-globe); // inserts the file icon-globe.svg as an inlined background-image
}
```


159
### css:abovethefold (will be called by the css task automatically) 
Philipp Nowinski's avatar
Philipp Nowinski committed
160 161 162 163 164 165 166 167 168 169 170 171 172
```bash
svg css:abovethefold
```

This task will read the html file you specified as abovethefold.template, read every <link> statement in it and replace
it with the css styles the referenced file contains, as an inline style tag. To make use of this feature, you should
create a separate css file in your project (abovethefold.scss -> abovethefold.css), as well as an html-template file
that references this stylesheet (note that the path needs to be relative to the template file). You can then set this
template file as your [PageRenderTemplate](https://docs.typo3.org/typo3cms/TyposcriptReference/Setup/Config/Index.html#pagerenderertemplatefile).
All styles inside your abovethefold.css file will now be inlined directly into the HTML of your website. Note that you
should think about what to put in this file only styles that should be available directly after the render process on
_every_ page should go there.

Philipp Nowinski's avatar
Philipp Nowinski committed
173 174 175
### css task

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
176
sgc css --ext [extension name]
Philipp Nowinski's avatar
Philipp Nowinski committed
177 178 179 180 181 182 183 184 185
```

Triggers css compilation inside the given directory. Note, that this task will also run the sprite task before it starts.

Assumptions:

* all scss files are inside the sass directory, relative to the given path.
* all css files go into the stylesheets directory, relative to the given path.

186
### images task 
Philipp Nowinski's avatar
Philipp Nowinski committed
187 188

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
189
sgc images --ext [extension name]
Philipp Nowinski's avatar
Philipp Nowinski committed
190 191 192 193 194 195 196 197
```

Optimizes all images for the given path.

Assumptions:

* all images are inside the image directory, relative to the given path.

198
### optimize images in fileadmin and uploads 
Philipp Nowinski's avatar
Philipp Nowinski committed
199 200

```bash
Philipp Nowinski's avatar
Philipp Nowinski committed
201
sgc images:uploaded
Philipp Nowinski's avatar
Philipp Nowinski committed
202 203
```

Philipp Nowinski's avatar
Philipp Nowinski committed
204
This tasks optimizes all images (png, jpg, gif, svg) inside the folders you specified in the sgc-config.json file. You might want to
Philipp Nowinski's avatar
Philipp Nowinski committed
205 206
run this task on a regular basis to compress user uploaded media.

207
# Extending the sgc with your own modules 
Philipp Nowinski's avatar
Philipp Nowinski committed
208

209
You can easily extend the sgc functionality by writing your own modules. Simply create a sgc-scripts folder next to sgc-core
Philipp Nowinski's avatar
Philipp Nowinski committed
210 211 212 213 214
and put your custom scripts in there. Right now only shell-scripts with are supported, other languages might follow in the future.

Execute your custom scripts by calling sgc <scriptName>

```
215 216
+ sgc-core
+ sgc-scripts
Philipp Nowinski's avatar
Philipp Nowinski committed
217 218 219 220 221 222 223 224
    - updateInstance.sh
    - updateDeployData.sh
```


```bash
sgc updateInstance
```