What is Semantic UI, how to configure and add it to GIT version control?

What the hell is Semantic?

Recently we got bored with omnipresent Bootstrap and our search for interesting altenatives lead us to Semantic UI. Similar to Bootstrap it is modern front-end framework, targeted at fast and pretty responsive web design.

I assume you have heard about Bootstrap, and even if not, you've seen it for sure. Semantic is quite different from its popular brother - first of all is uses semantic classes in CSS (i.e. class="right floated medium image") which are very useful and easier to learn than standard CSS naming conventions. Second important difference is that we have more components than in Bootstrap (e.g. components for comments, feeds, sidebar, more advanced responsive grid etc.) and more built-in javascript plugins (e.g. visibility plugin, which can load content dynamically as page scrolls).

You may think that all those additions make Semanic more "cluttered" than Bootstrap. Well you won't be far from truth - there are far more asset files available in the package and they are "heavier". But Semantic creators predicted this, and offer advanced build tools, which allow us to choose only selected components (so we don't have to load CSS and JS code that we won't use on our website), compile and minify them.

It all sound complicated? In fact, Semantic is quite harder in handling than Bootstrap, so I recommend it to front-end developers who have at least some experience with other frameworks, LESS, gulp and npm. Despite some complexity, Semantic has gathered (in the moment of writing this article) 24784 stars on github (about 1/4 of the bootstrap's star amount).

How to harmlessly add Semantic to your project?

On official Semantic-UI website there is well written getting started tutorial (with video). In short you want to have nodejs, npm and gulp on your developer machine.

First we download semantic-ui package from npm and save it as dependency in package.json file:

npm install semantic-ui --save

Above command will create node_modules directory (if it doesn't exist yet) and download semantic-ui with all dependencies. At the end, npm will automatically make this callback:

gulp install

Above command will ask us few questions regarding Semantic configuration and create semantic.json file, where configuration is stored. When answering the questions I decided to provide custom base path "base": "assets/semantic/" (so that Semantic will reside in the same directory as the rest of my assets) and I manually definded selected compontents which I'm going to use. Final config file looks like this:

{
  "base": "assets/semantic/",
  "paths": {
    "source": {
      "config": "src/theme.config",
      "definitions": "src/definitions/",
      "site": "src/site/",
      "themes": "src/themes/"
    },
    "output": {
      "packaged": "dist/",
      "uncompressed": "dist/components/",
      "compressed": "dist/components/",
      "themes": "dist/themes/"
    },
    "clean": "dist/"
  },
  "version": "2.1.8",
  "components": [
    "reset",
    "site",
    "button",
    "container",
    "divider"
  ]
}

If you choose automatic installation (with default config values) during first Semantic initialization, you can just edit semantic.json after that and run gulp command, which will recompile JS and CSS files to the directory configured as "output/packaged":

gulp build

Folder structure

Semantic has been designed to allow deep customization and personalization of your website. After instalattion we get folders semantic/src, where are all source files required for compilation and semantic/tasks, where are gulp tasks, which handle compilation process.

When we run command mentioned above; gulp build, there are "production files" being created from the source files (by default in the semantic/dist folder).

And now the most interesting part: you can add custom styles for you personal website in the files that already exist. There is directory (and respective files) specifically created for the purpose of holding our individual site theme: semantic/src/site. The drawback is that all LESS files have .variables and .overrides extensions, so you have to manually set LESS syntax inspection in your code editor.

Actually Semantic offers theme inheritance, so our custom theme overrides some optional packaged themes, which override default theme.

How to add Semantic to version control like GIT?

Semantic UI creators unfortunately don't provide us with "recommended" way of versioning the projcet with Semantic. The only files which we actually need in the production environment are:

semantic/dist/semantic.js
semantic/dist/semantic.css
semantic/dist/themes/* // that's where fonts and images are

In development environment, first of all, we need semantic.json config file and our "custom theme", meaning all .variables and .override files from our custom theme folder. So those files should definitely go to the version control:

semantic/src/site/*

All other files and folders are actually "vendor files", which could be just copied from npm using config information stored in semantic.json. Unfortunately... At the moment of writing this article, npm command which we ran previously to initialize Semantic, offers us two options after detecting existing semantic.json:

  • overwrite semantic.json file and proceed with installation (we would override config that some developer previously created)
  • skip the installation entirely

So in the end, I decided to add whole semantic/src directory to version control. So that after cloning the project, developer will already have all Semantic source files required for compiling assets.

Final .gitignore looks like that:

bower_components
node_modules
semantic/dist/components
semantic/dist/themes/*
!semantic/dist/*.js
!semantic/dist/*.css
!semantic/dist/themes/default/

Npm config file package.json have semantic-ui as dependency:

  "dependencies": {
    "semantic-ui": "^2.1.8"
  }

On developer instance, after cloning the project you have to run npm install in main directory. And after that just

cd semantic
gulp watch
We use cookies to ensure you get the best experience on our website. Privacy policy