Commit bfa66318 authored by Philipp Nowinski's avatar Philipp Nowinski

[BUGFIX] fix documentation and license + bring back creation of config

files
parent e232a1af
# License
## Commercial usage
## SPL (Sgalinski Plugin License)
The usage of this software for commercial projects, requires the payment of a small fee. The available version on NPM
is an old state. You can find the latest release on our shop (https://shop.sgalinski.de). We will maybe backport some
features from time to time.
Copyright (c) 2018 sgalinski Internet Services
Details about the commercial licence can be found here:
http://www.binpress.com/license/view/l/fcc5e62729e934a0fa6d1442eda5372d
Software released under this license is allowed to be used for commercial purposes and ads can be removed by paying a small fee. Permission is only granted to use the software. Any other actions, including copying, modifying, merging, publishing, distribution, sublicensing and / or selling copies are strictly prohibited!
### MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.
[![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/)
# sgalinski command line interface
# sgalinski CLI Task Runner
> **Please note:**
> The CLI is intended to be used with bash or zsh. In order for scss-lint to work, you need to have ruby installed on your machine.
> The CLI is intended to be used with bash or zsh.
## Installation
Move the 'sgc-core' folder inside your project root and execute the install script.
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:
```bash
./sgc-core/install.sh
......@@ -23,14 +30,17 @@ If you don't want to install the sgc command globally (e.g. in a server environm
### Windows
> **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!
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 might run into an error where the SGC is not able to install the scss_lint ruby gem. This is due to an SSL error
with rubygems that occurs on Windows. In this case, you will have to install scss_lint manually. Read more about that
error here: https://gist.github.com/luislavena/f064211759ee0f806c88
* You have to open git-bash with administrator privileges to run the installation script
## SGC Releases
......@@ -53,7 +63,8 @@ Please note that the following steps need to be executed before a new release:
* ```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)
* ```sgc lighthouse```: **experimental** runs a lighthouse test suite against your site
* ```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
* ```sgc open {sites}``` Opens a set of URLs in the default browser, that you can define inside your .sgc-config.json
You can call every command with the ```--production``` flag. This will prevent the toolchain from generating SourceMaps.
......@@ -69,12 +80,12 @@ will put into your projects root-directory.
### directories
Holds the paths to the css, sass, javascript, images, sprites, sourcemaps and inline-svgs, relative to the extensions root.
Holds the paths to the css, sass, javascript, images, sourcemaps and inline-svgs, relative to the extensions root.
* webPath: *path to your extension folder as seen from the web*
* basePath: *path to your extension folder as seen from the filesystem*
### abovethefold (enterprise feature)
### abovethefold
Configuration for the critical path css.
......@@ -86,11 +97,11 @@ Configuration for the critical path css.
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.
* compiler: *es6|typescript* (enterprise feature)
* compiler: *es6|typescript*
* libraryPaths: *additional locations that should be searched when resolving CommonJS require statements*
* excludeFromQa: *glob patterns with locations that hold JavaScript that does not need to be linted (vendor stuff)
### images (enterprise feature)
### images
* optimize: *locations of user uploaded images that should be optimized*
......@@ -128,34 +139,6 @@ the website in your browser, as a browsersync session (changed js and css will a
*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.
### sprite task (will be called by the css task automatically)
```bash
sgc css:sprites --ext [extension name]
```
Triggers sprite generation inside the given directory.
Assumptions:
* all sprite images are inside images/sprites, relative to the given path.
* all sprite images are PNGs.
* there is a sass directory, next to the images folder.
This task will generate a png inside the images folder, containing all the sprites and a .scss file inside the sass
folder, which will provide the necessary mixins. To use the sprites inside your SASS code, import the _sprite.scss file.
You can then use the following mixins:
```scss
// will output css for a sprite image 'box.png'
.element {
@include sprite ($box);
}
```
The @sprite mixin already contains width and height. If you need these values for something else, use the @sprite-width
and @sprite-height functions.
### css:svg task (will be called by the css task automatically)
```bash
sgc css:svg --ext [extension name]
......@@ -173,7 +156,7 @@ associated SVG as a css background image.
```
### css:abovethefold (will be called by the css task automatically) (enterprise feature)
### css:abovethefold (will be called by the css task automatically)
```bash
svg css:abovethefold
```
......@@ -200,7 +183,7 @@ 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.
### images task (enterprise feature)
### images task
```bash
sgc images --ext [extension name]
......@@ -212,7 +195,7 @@ Assumptions:
* all images are inside the image directory, relative to the given path.
### optimize images in fileadmin and uploads (enterprise feature)
### optimize images in fileadmin and uploads
```bash
sgc images:uploaded
......@@ -221,7 +204,7 @@ sgc images:uploaded
This tasks optimizes all images (png, jpg, gif, svg) inside the folders you specified in the sgc-config.json file. You might want to
run this task on a regular basis to compress user uploaded media.
# Extending the sgc with your own modules (enterprise feature)
# Extending the sgc with your own modules
You can easily extend the sgc functionality by writing your own modules. Simply create a sgc-scripts folder next to sgc-core
and put your custom scripts in there. Right now only shell-scripts with are supported, other languages might follow in the future.
......@@ -239,16 +222,3 @@ Execute your custom scripts by calling sgc <scriptName>
```bash
sgc updateInstance
```
# Troubleshooting
## Timeouts of the registry while installing the toolchain
Please try to remove the npm-shrinkgwrap.json file and execute the following commands:
```bash
cd sgc-core
rm -rf node_modules
npm set registry http://registry.npmjs.org/
npm install
```
{
"directories": {
"basePath": "web/typo3conf/ext/",
"webPath": "typo3conf/ext/",
"css": "Resources/Public/StyleSheets",
"sass": "Resources/Public/Sass",
"cssSourceMaps": "Resources/Public/SourceMaps",
"javascriptSrc": "Resources/Public/JavaScript",
"javascriptDest": "Resources/Public/JavaScript/Dist",
"javascriptSourceMaps": "Resources/Public/SourceMaps",
"images": "Resources/Public/Images",
"sprites": "Resources/Public/Images/Sprites",
"svg": "Resources/Public/Images/Svg"
},
"abovethefold": [
{
"template": "web/typo3conf/ext/project_theme/Resources/Private/Templates/Abovethefold/Src/PageRenderTemplate.html",
"dest": "web/typo3conf/ext/project_theme/Resources/Private/Templates/Abovethefold/Dist/"
}
],
"js": {
"libraryPaths": [
"./web/typo3conf/ext/project_theme/node_modules"
],
"excludeFromQa": [
"!**/Extensions/**/*",
"!**/node_modules/**/*"
],
"pipeline": {
"dev": {
"uglify": false,
"renameToDotMin": true,
"polyfills": true,
"qa": true,
"sourceMaps": true
},
"prod": {
"uglify": true,
"renameToDotMin": true,
"polyfills": true,
"qa": false,
"sourceMaps": false
}
}
},
"css": {
"excludeFromQa": [
"!**/_svg.scss"
],
"pipeline": {
"dev": {
"cleanCss": false,
"renameToDotMin": true,
"qa": true,
"sourceMaps": true
},
"prod": {
"cleanCss": true,
"renameToDotMin": true,
"qa": false,
"sourceMaps": false
}
},
"svgIconPrefix": "icon-"
},
"supportedBrowsers": [
"> 2%",
"ie 11"
],
"images": {
"optimize": [
"web/fileadmin",
"web/uploads"
]
},
"extensions": [
"project_theme"
],
"logMessages": {
"imagesSuccess:uploaded": {
"level": "error",
"message": "Please make sure to clear the TYPO3 cache now, image hashes might have changed. Also make sure to run this command again after a few days."
}
},
"browsersync": {
"url": "https://www.website-base.dev",
"urlparams": "no_cache=1&disableScriptmerger=1"
},
"open": {
"all": [
"https://www.website-base.dev",
"https://www.website-base.dev/typo3"
]
}
}
#!/bin/bash
echo -e "\n"
echo -e "\033[0;31m .__ .__ __ .__\033[0m"
echo -e "\033[0;31m ______ _________ | | |__| ____ _____| | _|__|\033[0m"
echo -e "\033[0;31m / ___// ___\__ \ | | | |/ \ / ___/ |/ / |\033[0m"
echo -e "\033[0;31m \___ \/ /_/ > __ \| |_| | | \\___ \| <| |\033[0m"
echo -e "\033[0;31m/____ >___ (____ /____/__|___| /____ >__|_ \__|\033[0m"
echo -e "\033[0;31m \/_____/ \/ \/ \/ \/\033[0m"
echo -e " \033[33m ███████╗ ██████╗ ██████╗\033[0m"
echo -e " \033[33m ██╔════╝██╔════╝ ██╔════╝\033[0m"
echo -e " \033[33m ███████╗██║ ███╗██║ \033[0m"
echo -e " \033[33m ╚════██║██║ ██║██║ \033[0m"
echo -e " \033[33m ███████║╚██████╔╝╚██████╗\033[0m"
echo -e " \033[33m ╚══════╝ ╚═════╝ ╚═════╝\033[0m\n"
. ./sgc-core/core/version.conf
echo -e " \033[103m\e[30m \033[0m\e[49m"
echo -e " \033[103m\e[30m Welcome to the \033[0m\e[49m"
echo -e " \033[103m\e[30m sgalinski CLI Task Runner \033[0m\e[49m"
echo -e " \033[103m\e[30m \e[1mv${SGC_VERSION} \033[0m\e[49m"
echo -e " \033[103m\e[30m \033[0m\e[49m"
echo -e "\n"
echo -e "\033[0;32mWelcome to the sgalinski CLI.\033[0m"
if [ ! -e ./sgc-core ]
then
echo -e "\n\033[0;31mWrong directory! Call this script from the directory that contains the sgc-core folder! This is usually your project root directory.\033[0m\n";
echo -e "\n\e[41m\e[97m Error: \e[49m"
echo -e "\033[0;31m Wrong directory! Call this script from the directory that contains the sgc-core folder!\033[0m";
echo -e "\033[0;31m This is usually your project root directory.\033[0m\n";
exit 1;
fi
......@@ -26,8 +36,9 @@ then
# nvm installation on windows cannot be automated
if [ -z `which nvm` > /dev/null ]
then
echo -e "\n\033[0;31mYou need to install the Node Version Manager for Windows before you can proceed with the installation.\033[0m"
echo -e "\033[0;31m ==> https://github.com/coreybutler/nvm-windows\033[0m\n"
echo -e "\n\e[41m\e[97m Error: \e[49m"
echo -e "\033[0;31m You need to install the Node Version Manager for Windows before you can proceed with the installation.\033[0m"
echo -e "\033[0;31m ==> https://github.com/coreybutler/nvm-windows\033[0m\n"
exit 1;
fi
else
......@@ -116,6 +127,44 @@ fi
. ./core/version.conf
echo "INSTALLED_SGC_VERSION=$SGC_VERSION" > .sgc_version
if [ ! -e ../.sgc-config.json ]
then
echo -e "\033[33mNo .sgc-config.json file found.\033[0m";
echo -e "\033[33mDo you want me to create an example config-file? [Y/N]\033[0m";
read -n 1 -r
echo # move to a new line
if [[ $REPLY =~ ^[Yy]$ ]]
then
cp ./core/installers/example-sgc-config.json ../.sgc-config.json
fi
echo -e "\033[0;32mCreated .sgc-config.json ✓\033[0m\n"
fi
if [ ! -e ../.stylelintrc ]
then
echo -e "\033[33mNo .stylelintrc file found.\033[0m";
echo -e "\033[33mDo you want to use the sgalinski default configuration? [Y/N]\033[0m";
read -n 1 -r
echo # move to a new line
if [[ $REPLY =~ ^[Yy]$ ]]
then
curl -s https://gitlab.sgalinski.de/snippets/29/raw >> ../.stylelintrc
fi
echo -e "\033[0;32mCreated .stylelintrc ✓\033[0m\n"
fi
if [ ! -e ../.eslintrc.js ]
then
echo -e "\033[33mNo .eslintrc.js file found.\033[0m";
echo -e "\033[33mDo you want to use the sgalinski default configuration? [Y/N]\033[0m";
read -n 1 -r
echo # move to a new line
if [[ $REPLY =~ ^[Yy]$ ]]
then
curl -s https://gitlab.sgalinski.de/snippets/28/raw >> ../.eslintrc.js
fi
echo -e "\033[0;32mCreated .eslintrc.js ✓\033[0m\n"
fi
# go back to the root folder
cd ..
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment