Setting up Semantic UI build tools
For links to download Semantic UI, check our our download page.
Semantic uses command-line tools to build your project while theming. After getting Semantic, you will need to install nodejs and gulp to run the build process.
Installing node on OSX is easiest with homebrew
Node on Linux should be installed to work without sudo. You can do that by using one of these techniques.
I personally use this set-up procedure:
Windows install just requires downloading the node binary
After installing Node, Gulp can be installed globally using Node Package Manager (NPM)
Node dependencies are managed per project in a special file package.json to make installing a project's depencies easy.
Once you're up and running. Navigate to the semantic directory and install the npm dependencies.
Semantic uses gulp to compile your stylesheets when your theme changes. The first time you run gulp you will be greeted with an interactive installer
The installer will let you select which components to include, and specify paths for your project.
| Installation Type | |
|---|---|
| Automatic | Installation will use the default paths, outputing css files to dist/ and packaging all components together |
| Express | Will let you move your site folder and your dist folder and select from a list of components to include in your concatenated release. |
| Custom | Will prompt you for all available options |
The install process will create two files: semantic.json stores paths for your build and sits on the top-level of your project, theme.config is a LESS file that exists in src/ and allows you to centrally set the themes for each UI component.
The installer will also create a special folder which contains your site-specific themes. The default location for this is src/site. For more information on using site themes, see our customization guide.
If you prefer these files and folders can be moved manually instead of using the installer.
You can use normal package manager functions to update your project, just be sure to re-install semantic after upgrading. Re-install will extend your semantic.json but not overwrite it
The method for updating Semantic will depend on your package manager, but in all cases just involves updating your source files and re-running the gulp installer
After setting up your project you have access to several commands for building your css and javascript.
Semantic creates minified, and uncompressed files in your source for both individual components, and the components specified for your packaged version.
Keep in mind semantic will automatically adjust URLs in CSS and add vendor-prefixes as part of the build process. This means definitions and theme files do not need vendor prefixes.
Building and watching Semantic is only necessary while adjusting your UI. This is usually the first part of building a new project, and a separate process than building-out pages in your site.
During this architecting phase you can try downloading different themes, adjusting your site-wide settings (font-family, colors, etc) and tweaking components in your site's component overrides.
Files in the examples/ folder of your project can be useful for testing out changes in your UI. For example, you might run gulp watch download a new theme to src/site/themes/ then adjust your theme.config file with the name of the new theme and refresh examples/kitchensink.html to inspect changes in the theme.
You will only need to use Semantic's build tools while refining your UI, while designing pages you can rely on the compiled css and js in dist/ and your software stack's normal build set-up.
gulp watch will automatically recompile only the necessary definition files when you update semantic.config or any .variables or .overrides file.
One useful way to track ui modifications for a team is to run a local instance of the UI docs to serve as a team "styleguide".
You can grab the doc source from GitHub.
The easiest setup is to keep semantic ui source and the docs source in adjacent directories and use Gulp to serve files to the docs.
Gulp includes two special commands for serving files to a second location
This translation is only % complete!
We need your help to make Semantic available to people who speak your language.
Our translation tools are easy to use and allow you to translate text without having to leave the site. If you are interested in joining our translation team please e-mail me for access to our translation hub.
