Extend documentation for customised UIkit theme deployment

[oshihirii]

There are additional steps required to have a custom UIkit theme outside of /node_modules/uikit.

It is important to do this so that customisations are not overwritten when upgrading UIkit.

These steps are not described at the following locations:

https://getuikit.com/docs/custom-icons
https://getuikit.com/docs/installation

Below are some of the steps required, defined with assistance of @aarongerig in issues and gitter chats.

It would be beneficial if they could be verified and added to the official documentation.

The following assumes you are using webpack, npm and less.

01) To install UIkit in your project, in your repo directory, run npm install --save-dev uikit.

02) Change into /node_modules/uikit and run the following:

npm install
npm install yarn
npm run compile

(edit: 09/03/24 - i had to install pnpm in order to run npm run compile successfully, ie: npm install -g pnpm)

03) Create a file at your_repo/path_to_your_source/js/uikit.js with the following contents:

// comment out the things you don't need, uncomment the things you do need

import UIkit from 'uikit/dist/js/uikit-core';
// import Countdown from 'uikit/dist/js/components/countdown';
// import Filter from 'uikit/dist/js/components/filter'; 
import Lightbox from 'uikit/dist/js/components/lightbox';
// import LightboxPanel from 'uikit/dist/js/components/lightbox-panel'; 
// import Notification from 'uikit/dist/js/components/notification';
// import Parallax from 'uikit/dist/js/components/parallax';
// import Slider from 'uikit/dist/js/components/slider'; 
// import SliderParallax from 'uikit/dist/js/components/slider-parallax'; 
// import Slideshow from 'uikit/dist/js/components/slideshow';
import Sortable from 'uikit/dist/js/components/sortable';
// import Tooltip from 'uikit/dist/js/components/tooltip';
// import Upload from 'uikit/dist/js/components/upload';

import Icons from 'uikit/dist/js/uikit-icons';

UIkit.use(Icons);

// UIkit.component('countdown', Countdown);
// UIkit.component('filter', Filter); 
UIkit.component('lightbox', Lightbox);
// UIkit.component('lightboxPanel', LightboxPanel); 
// UIkit.component('notification', Notification);
// UIkit.component('parallax', Parallax);
// UIkit.component('slider', Slider); 
// UIkit.component('sliderParallax', SliderParallax); 
// UIkit.component('slideshow', Slideshow);
UIkit.component('sortable', Sortable);
// UIkit.component('tooltip', Tooltip);
// UIkit.component('upload', Upload);

export default UIkit;

04) Create the following in your_repo/path_to_your_source/css/:

-- custom_uikit_theme
--- my_theme
---- _import.less
--- my_theme.less <-- this will contain all your custom css

05) Add the following to the top of my_theme.less:

// import UIkit default theme
@import "../../../node_modules/uikit/src/less/uikit.theme.less";
// import component override styles
@import "my_theme/_import.less";

06) Paste the following into _import.less:

// comment out what you don't need to customise, uncomment what you do need to customise

// Base
@import "variables.less";
// @import "mixin.less";
// @import "base.less";

// Elements
// @import "link.less";
// @import "heading.less";
// @import "divider.less";
// @import "list.less";
// @import "description-list.less";
@import "table.less";
// @import "icon.less";
// @import "form-range.less";
@import "form.less"; // After: Icon, Form Range
@import "button.less";

// Layout
// @import "section.less";
// @import "container.less";
// @import "grid.less";
// @import "tile.less";
@import "card.less";

// Common
// @import "close.less"; // After: Icon
// @import "spinner.less"; // After: Icon
// @import "totop.less"; // After: Icon
// @import "marker.less"; // After: Icon
// @import "alert.less"; // After: Close
// @import "badge.less";
// @import "label.less";
// @import "overlay.less"; // After: Icon
// @import "article.less"; // After: Subnav
// @import "comment.less"; // After: Subnav
// @import "search.less"; // After: Icon

// Navs
// @import "nav.less";
@import "navbar.less"; // After: Card, Grid, Nav, Icon, Search
// @import "subnav.less";
// @import "breadcrumb.less";
// @import "pagination.less";
// @import "tab.less";
// @import "slidenav.less"; // After: Icon
// @import "dotnav.less";
// @import "thumbnav.less";

// JavaScript
// @import "accordion.less";
// @import "drop.less"; // After: Card
// @import "dropdown.less"; // After: Card
@import "modal.less"; // After: Close
// @import "lightbox.less"; // After: Close
// @import "slideshow.less";
// @import "slider.less";
// @import "sticky.less";
@import "offcanvas.less";
// @import "switcher.less";
// Scrollspy
// Toggle
// Scroll

// Additional
@import "iconnav.less";
// @import "notification.less";
// @import "tooltip.less";
// @import "placeholder.less";
// @import "progress.less";
// @import "sortable.less";
// @import "countdown.less";

// Utilities
// @import "animation.less";
// @import "width.less";
@import "text.less";
// @import "column.less";
// @import "cover.less";
// @import "background.less";
// @import "align.less";
@import "utility.less";
// @import "flex.less"; // After: Utility
// @import "margin.less";
// @import "padding.less";
@import "position.less";
// @import "transition.less";
// @import "visibility.less";
// @import "inverse.less";

// Need to be loaded last
// @import "print.less";

07) For each component you do overwrite, add the relevant file to the directory:

your_repo/path_to_your_source/css/custom_uikit_theme/my_theme

For example, if you were overwriting position.less, add a file called position.less to the above directory with your contents, eg:

// misc mixin
// see: https://getuikit.com/docs/less#miscellaneous-hooks
.hook-position-misc() {
    //overwriting existing value
    .uk-position-top-right { z-index: 9999; }
}

08)Add the following lines to your src/js/common.js file:

import '../css/custom_uikit_theme/my_theme.less';
import UIkit from './uikit';

09) Add this to your webpack.config.js file:

resolve: {
alias: {
    'uikit-util': path.resolve(__dirname, 'node_modules/uikit/src/js/util')
}
}

10) Your repo will now look something like this:

my_repo
- src
-- js
--- uikit.js  <- this is the js file you created above
--- common.js  <- this is where you import the js and css files created above
-- css
-- custom_uikit_theme <- this is the custom theme you created above
--- my_custom_theme.less
--- my_custom_theme
---- _import_less
---- any_components_you_are_overwriting_here
-- img
- app.js
- package.json
- webpack.config.js

Now, every time you upgrade UIkit you will just need to run your own webpack build process and the latest UIkit files will be used.

TO DO:

To include custom icons in your own your_repo/src/img/custom/icons directory so that they are available in the same manner UIkit library icons are, eg:

<span uk-icon="icon: download; ratio: 1.5" class="uk-icon"></span>
<span uk-icon="icon: ic_mail_outline_white_24px; ratio: 1.5" class="uk-icon"></span>

do this...

[zero4573]

For those of you that are looking to include custom icons in your own your_repo/src/img/custom/icons directory, i've sort of found a way to do so through calling uikit's build/icons.js

For this to work you need to do the following:

1. Install all of the required dependencies to run the script: npm install --save-dev minimist fs-extra path glob less svgo rollup uglify-js clean-css rollup-plugin-html rollup-plugin-json rollup-plugin-buble rollup-plugin-replace rollup-plugin-import-alias
2. create your icons directory for which you want to include icons from, in my case, I am using mkdir assets/icons, and place your icons in it
3. Copy the node_modules/uikit/src/js/icons.js to <project root>/src/js/icons.js, this step is required as the node_modules/uikit/build/icons.js script references the src/js/icons.js script relative to the working directory instead of the module directory. Making the following change to the node_modules/uikit/src/js/icons.js script will make this work without copying the script, and from my limited testing will not break anything else:

14c14
<             util.compile('src/js/icons.js', `dist/js/uikit-icons-${name}`, {name, replaces: {ICONS}})
---
>             util.compile(`${__dirname}/../src/js/icons.js`, `dist/js/uikit-icons-${name}`, {name, replaces: {ICONS}})

4. run node node_modules/uikit/build/icons.js --custom="assets/icons" to build your icons, this will create a dist/js/uikit-icons-assets.js file at your root directory.
5. Use the newly created file, I use this through webpack, so I do this like so:

const UIkit = require('uikit');

const uikit_icons = require('uikit/dist/js/uikit-icons');
const custom_icons = require('dist/js/uikit-icons-assets.js');

UIkit.use(uikit_icons);
UIkit.use(custom_icons);

Tested on uikit 3.0.3