Menu

Build Tools
Using Gulp with Semantic UI

Overview

30 Second Explanation

Download Semantic UI navigate to the install folder then run a gulp command.

To build all files:

gulp build

To watch for changes

gulp watch

Why Build Tools?

Semantic UI uses Gulp for several reasons:

Process LESS files with theming variables
Add vendor prefixes for supported browsers with autoprefixer
Watch file changes and rebuild the necessary files when adjusting themes
Automatically process asset paths, so that minified and concatenated releases can exist in different directories
Allow custom builds with only the required components for your site
Allow advanced usage like Right-To-Left (RTL) languages using RTLCSS

Folder Structure

A Semantic UI project includes the following folder structure.

src
site
Your site's theme
themes
default
Default theme
packaged-theme
Additional themes
theme.config
Config file for setting packaged themes
dist
Compiled CSS and JS files
components
Individual component CSS and JS
semantic.css
concatenated release
semantic.js
concatenated release
semantic.json
Contains build settings for gulp

Gulp Commands

Below is a list of all available gulp commands

Command Description
install Asks install questions to setup semantic.json
watch (default) Watches for changes in source files, and builds file on change
build Build all files
clean Cleans dist/ folder
version Outputs current version
build-javascript Build JS files
build-css Build CSS files
build-assets Build assets files
serve-docs Serves files to local docs instance
build-docs Builds files to docs folder

Configuration Files

semantic.json

Build tool settings are stored in a special file called semantic.json It can be included in any folder that is in a parent folder of the semantic install folder.

If you used the npm or meteor, a semantic.json file is automatically generated for you in the root of your project. If you used a different package manager you can run gulp install to run the interactive installer.

{ // base path added to all other paths specified in "paths" "base": "", // current version of Semantic UI "version": "2.4.2", "paths": { "source": { // source theme.config "config" : "src/theme.config", // source definition folder "definitions" : "src/definitions/", // source site theme "site" : "src/site/", // source themes folder "themes" : "src/themes/" }, "output": { // packaged source (both compressed/uncompressed) "packaged" : "dist/", // uncompressed source "uncompressed" : "dist/components/", // compressed source "compressed" : "dist/components/", // output directory for theme assets "themes" : "dist/themes/" }, // directory for gulp clean task "clean" : "dist/" }, // when set to an integer permission, will set dist files with this file permission "permission" : false, // whether gulp watch/build should run RTLCSS "rtl": false, // will only include components with these names "components": [ "reset", "site", "button", "container", "divider", "flag", "header", "icon", "image", "input", "label", "list", "loader", "rail", "reveal", "segment", "step", "breadcrumb", "form", "grid", "menu", "message", "table", "ad", "card", "comment", "feed", "item", "statistic", "accordion", "checkbox", "dimmer", "dropdown", "embed", "modal", "nag", "popup", "progress", "rating", "search", "shape", "sidebar", "sticky", "tab", "transition", "api", "state", "visibility" ], // whether to include special project maintainer tasks "admin": false }

theme.config

LESS uses a special configuration file theme.config which lets you specify what theme each component should use. If you have not generated this file yet, you will receive an error message when running build tools

You can learn more about theme.config by checking out the theming guide

Importing Gulp Tasks

See our recipes section for examples on how to import individual gulp tasks into your custom Gulpfile.

Auto-Install & Continuous Integration
New in 2.2

We've added a new setting to semantic.json in 2.2 to help make working with a CLI, or other automated deployments more streamlined.

Specifying autoInstall: true in an environments semantic.json configuration will prevent any user prompting when running npm install allowing for automated deployment.

Dimmer Message
Dimmer sub-header