A CSS boilerplate approach for OutSystems

Photo by Jackson Sophat on Unsplash

CSS code management has always been a challenge for developers. The Outsystems context is no exception. In large projects, and with several UI Developers, the challenge becomes even greater. The bigger the theme, the more dificult it will be to maintain code and its merges.

As such, and to respond to these and other needs, the uDX team chose to find an alternative for managing the code outside the platform. So we created a boilerplate to use in different projects and to solve several challenges that we have in our day-to-day.

The boilerplate

The boilerplate consists in a repository that aims to standardize a folder structure, in an agnostic way, so that it is easier for any team member to understand what they are working on. In addition, it also serves as an accelerator for new projects. The front-end developer only needs to fork the boilerplate and adapt it to the project context.

Main goals:

• Facilitate the CSS code management by using SCSS Partials;
• Control version, code merge, viewing code changes and role back, if necessary;
• Automate some optimizations at compile time;
• Use CSS Linter in order to reduce future bugs and maintain the code patterns;
• Reduce the time of decision making where to place CSS rules in the stylesheet, by giving a CSS structure that maps through the various parts of Outsystems and OutsystemsUI.

We used some tools to process the code in order to fulfill the above goals:

• Node-sass: NodeJS library that compiles SCSS code into CSS;
• PostCSS: transforms CSS, based on some plugins in order to optimize CSS;
• StyleLint: CSS Linter that validates if the CSS rules meets the requirements defined in the .stylelintrc file.

Boilerplate’s structure

Here you can find out a practical example of the boilerplate:

Boilerplate repository

The main folders are Source and Dist. The remaining files are needed in order to compile the code.

The Source directory consists of a folder where the CSS code is developed. After compilation (triggered by saving the file), the output will be in the Dist folder already with the changes and optimized. That CSS file is ready to be passed to Service Studio.

SCSS Architecture

1_abstract

General project settings

Example: CSS and SCSS variables, @font-face, mixins, …

2_elements

Based on the Atomic Design principles, in this folder, we can find the most atomic elements, that correspond the HTML tags

Example: button, input, link, label, …

3_patterns

UI Patterns

This directory contains subfolders. Since there are many UI patterns, and to make easier the decision of where to place the CSS, it has been split into the following divisions:

Custom patterns: any custom pattern created by the developers;

Outsystems Patterns: form, list, popup, upload, …;

OutsystemsUI Patterns: UI patterns from OutsystemsUI.

We already provide the mapping, per file, of each widget provided by Outsystems and OutsystemsUI. Just put the necessary custom CSS in the file.

4_layout

CSS for layout and their parts

Example: layout base, header, footer, …

5_pages

Any CSS that is specific to a particular page. Our suggestion is that the filename matches the name of the outsystems page

6_utils

Utility style classes that Outsystems does not provide by default

Example: spacing classes, display, gap, …

7_libs

CSS provided by external libraries that is imported to the project

Structure example

How to compile the code?

In order to use this boilerplate, you’ll need to use the Bash to run some comands. You can use the default one or a custom, like iTerm.

The only pre-requisite you need is to install NodeJS. Minimum version: NodeJS 16.0.

1. Install dependencies

Before running the node script, it is necessary to install the packages’ dependencies needed to compile the code. This is a setup process and you only need to do it once.

npm install

2. Run NPM Tasks

For node scripts to watch the code changes, it is necessary to init. You can do it by running the following command:

npm start

After that, every time any file in the Source is changed, the script will run and compile the remaining output in Dist directory.

3. Add or change CSS

Now you can add or change CSS code and then save the file. When the file is saved, the NPM task that is watching will run the tasks and compile the code into a new CSS file.

_dummy.scss

index.css

Once the compile is done, you will see a green message on your bash:

Next steps…

Once you have all the changes done in your CSS, the next step is to copy to Outsystems Service Studio.

Index.css

Same output on Service Studio

You can use this boilerplate as a base to adapt it to your and the project needs. It is possible to change de configurations of the plugins. For example: change the CSS output to minified instead of the default one; or add/remove some PostCSS plugins. You can find more information in the plugin’s documentation.

That’s all folks!