sgalinski command line interface
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.
Move the 'sgc-core' folder inside your project root and execute the install script.
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.
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
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!
- 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)
Configuration for the critical path css.
- template: path to the src template
- dest: path to the destination
- compiler: es6|typescript (enterprise feature)
- libraryPaths: additional locations that should be searched when resolving CommonJS require statements
images (enterprise feature)
- optimize: locations of user uploaded images that should be optimized
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.
BrowserSync is a neat tool that will help you during the development and testing process. When you run
sgc, it will spin
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.
You can run a specific task on a specific component, or start a watcher that will fire up BrowserSync and run tasks when source files change. Extensions that will be watched are defined in your .sgc-config.json file for each project.
If you run a specific task, you need to specify the extension you want the task to run on with the --ext parameter.
sgc css --ext project_base
There are a few available tasks you need to remember:
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)
sgc css:sprites --ext [extension name]
Triggers sprite generation inside the given directory.
- 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:
// will output css for a sprite image 'box.png'.element
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)
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.
; // imports the file with the generated mixins (inside your Sass-root).icon-globe
css:abovethefold (will be called by the css task automatically) (enterprise feature)
This task will read the html file you specified as abovethefold.template, read every 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. 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.
sgc css --ext [extension name]
Triggers css compilation inside the given directory. Note, that this task will also run the sprite task before it starts.
- 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)
sgc images --ext [extension name]
Optimizes all images for the given path.
- all images are inside the image directory, relative to the given path.
optimize images in fileadmin and uploads (enterprise feature)
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)
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.
Execute your custom scripts by calling sgc
+ sgc-core + sgc-scripts - updateInstance.sh - updateDeployData.sh
Timeouts of the registry while installing the toolchain
Please try to remove the npm-shrinkgwrap.json file and execute the following commands:
cd sgc-corerm -rf node_modulesnpm set registry http://registry.npmjs.org/npm install