DEV Community: Wendell Adriel

Structuring a Server-Side Application

Wendell Adriel — Fri, 05 Aug 2022 11:39:17 +0000

Introduction

This is the English version of an article that I wrote in Portuguese here

In this article, I'll talk about how can we structure a server-side application in a simple way, while using a clean and efficient architecture that could be used for small to large applications.

This will be a "theoric" article, I won't show code and it won't be tied to a specific language, it's going to be an approach based on the design/architecture of the application, this way you can apply it to any language that you may know.

I hope that this article can help you!

Once Upon a Time the MVC

Probably you heard about the famous MVC:

M - Model - Data Layer
V - View - Visual Layer
C - Controller - Communication Layer

This is a software architecture heavily used some time ago and probably still used nowadays for simpler software.

In this architecture we have three different layers where the access to the data (Database) is on the Data Layer, that's accessed by the Communication Layer that's the layer responsible for receiving the requests from the Visual Layer where the user interacts with the software, doing the needed processing and returning the response back to the Visual Layer.

This is a simple and practical architecture, but with the advance of the software that started to grow in complexity, this architecture started to be obsolete because of the coupling of the code and the layers starting to have a lot of responsibilities.

Evolving the Architecture of the Applications

Nowadays the Client-Side (Front-end) applications are complex as the Server-Side (Back-end) applications and can have different architectures and patterns to be created on a way to support small and simple, but also large and complex applications. Because of that, the MVC architecture can be broken down, having the Visual Layer as a totally different application with its own architecture. The focus of this article will be the architecture of a Server-Side application.

Removing the Visual Layer of our architecture, if we were going to follow the MVC architecture we would be left with only two layers: the Data Layer and the Communication Layer, but as I said before this type of architecture results in a coupled code, where we can have code duplication and a lot of responsibilities in a single layer.

The New Server-Side Architecture

Since the two layers that we talked about early aren't enough to create a clean and easy-to-maintain application, the solution is to recreate the architecture of our server-side application in a way that gets cleaner and decoupled.

There are many books, courses and tutorials out there and also N types of architectures that are possible to follow, here I'll explain only one of those architectures but that has been working good for me and the projects that I've been working on in the last years.

The architecture that I've been using is composed of four layers:

Communication Layer
Validation Layer
Service/Business Layer
Data Layer

Below I'll explain briefly each one of them.

Communication Layer

This is the simplest layer of the application and the one with fewer responsibilities, as the name already says, this is the communication layer between the user and the logic of our application. It's responsible only for the IO (Input & Output) of our application, this layer receives the data sent by the user (it could be through a CLI tool or a Web page or a Mobile App) and returns the result back to the user after going through the other layers.

Validation Layer

This layer is responsible for validating the data received by the Communication Layer. And if you're asking the reason for separating those two layers, the answer is simple. Imagine that currently your application communicates with a Web page and all the validation is coupled with the HTTP request. Now you or your company decide to create a CLI tool for your application. Being your validation logic coupled with the HTTP request, now you'll have to recreate all the validation logic again. If you had separated that into a specific layer, you just needed to create a new Communication Layer that would be your CLI tool and the whole application would be working fine.

Service/Business Layer

This is the most critical layer of our application, here lies all the business logic, the core of our application. This layer is responsible for getting the already validated data from the Validation Layer, getting the needed data, applying the needed logic and formatting the data to send back to the Communication Layer.

Data Layer

This is the layer responsible for getting and saving data into the application's database (s). To have the separation between the business logic and the data itself, this should be the ONLY layer that accesses the Database(s), this way if any other layer needs to access this data, it should be done through this layer.

Conclusion

In this article, we learned what's the MVC architecture, the reason that this architecture is obsolete nowadays and we say an example of an architecture for modern Server-Side applications that's simple but efficient to create clean and easy-to-maintain applications. This architecture can be used with any language and it's not only for Web applications but as well for APIs, CLIs, etc.

I hope that this article helped you to have a better understanding of how the architecture and the design of an application can impact A LOT in the final result of our software in order to create a clean, easy to maintain and evolve software.

#Descomplica - DTO

Wendell Adriel — Tue, 21 Jun 2022 11:40:56 +0000

Introdução

E aí pessoas, tudo bem?
Esse será o primeiro artigo do #Descomplica, uma série de pequenos artigos que irão sempre focar em um tema específico, com uma abordagem simples e direta sobre o assunto e o nosso primeiro assunto será sobre DTOs.

O que é um DTO

DTO (Data Transfer Object/Objeto de Transferência de Dados) é um(a) Design Pattern/Padrão de Projeto simples, porém eficiente para se aplicar na arquitetura um software.

Um DTO nada mais é que um objeto utilizado para encapsular e mapear dados primitivos e que podem ser serializados.

Como criar e utilizar um DTO

Como dito anteriormente, um DTO nada mais é que um objeto simples para encapsular e mapear dados que serão enviados entre as camadas da nossa aplicação. Então vamos ver um exemplo bem simples em PHP de um DTO utilizado para encapsular dados para um endpoint/serviço que irá salvar um usuário:

class SaveUserDTO
{
    public function __construct(
        private string $name,
        private string $email,
        private string $password
    ) {}

    // GETTERS AND SETTERS
}

$userDTO = new SaveUserDTO('Wendell', 'me@wendelladriel.com', 'S3cR3t');

Como podem ver acima, criar e utilizar um DTO é extremamente simples e fácil. Agora vamos aprender o porquê utilizar esse padrão.

Porquê utilizar DTOs

Para mim, a utilização de DTOs no código gera um código simples, limpo e de fácil manutenção. Para quem trabalha com Laravel e outros frameworks PHP já devem ter visto como eu vi em várias aplicações algo como abaixo nos controllers:

public function saveUser(Request $request): JsonResponse
{
    $this->service->saveUser($request->all());
}

No código acima o código pega todos os parâmetros do Request e os envia para a Camada de Serviço. Alguns dos problemas criados por isso são:

Não temos a definição de quais valores estão a ser enviados
Caso o Request seja atualizado, não vamos saber de forma fácil o que foi alterado
Para alguém que não conhece o código ou se ficar um tempo sem mexer no código, dificilmente saberá os possíveis valores desse Request

Se ao invés de fazer isso, usarmos o DTO que criamos acima, qualquer dev que entrar na equipe ou caso alguém precise fazer alguma alteração ou manutenção no código, será muito mais fácil de saber quais são os dados esperados pelo serviço, o que podemos utilizar e como alterar algo se necessário.

O código fica muito mais limpo, fica muito mais fácil de dar manutenção ou alterar algo e oferece uma excelente DX (Developer Experience/Experiência para o Desenvolvedor) para toda a equipe!

Conclusão

Vimos nesse artigo o que é, como utilizar e o porquê utilizar DTOs para melhorar a arquitetura da nossa aplicação! Espero que tenham gostado e aproveitem pra comentar aqui se conheciam esse padrão, se utilizam e como utilizam!

Um grande abraço e até o próximo #Descomplica!

Estruturando uma Aplicação Server-Side

Wendell Adriel — Mon, 20 Jun 2022 12:01:19 +0000

Introdução

E aí pessoal, depois de um hiato de dois anos sem escrever nenhum artigo, esse será o meu primeiro artigo pra voltar a escrever e tentar ajudar a comunidade de alguma forma.

Nesse artigo irei falar de como estruturar uma aplicação server-side de forma simples, mas com uma arquitetura limpa e eficiente para pequenas e grandes aplicações.

Esse será um artigo "teórico", não irei mostrar código e não estará ligado a uma linguagem específica, será uma abordagem no ponto de vista do design e arquitetura da aplicação, dessa forma vocês poderão utilizar em qualquer linguagem que conheçam.

Espero que esse artigo venha a ser útil para alguém!

Era uma vez o MVC

Provavelmente vocês já devem ter ouvido falar do famoso MVC:

M - Model (Modelo) - Camada de Dados
V - View (Visualização) - Camada de Visualização
C - Controller (Controlador) - Camada de Comunicação

Essa é uma arquitetura de software muito utilizada há alguns tempos atrás e provavelmente ainda usada hoje em dia para softwares mais simples.

Nessa arquitetura, temos três camadas distintas onde o acesso aos dados (Base de Dados) fica na Camada de Dados, que por sua vez é acessada pela Camada de Comunicação que é a camada responsável por receber os pedidos da Camada de Visualização onde o usuário interage com o software, fazer o processamento necessário e retornar a resposta novamente para a Camada de Visualização.

Essa é uma arquitetura simples e prática, porém com o avanço dos softwares que foram ficando mais complexos essa arquitetura começou a ficar um pouco obsoleta pelo acoplamento do código e as camadas foram ficando com muitas responsabilidades.

Evoluindo a Arquitetura das Aplicações

Hoje em dia as aplicações Client-Side (Front-end) são tão complexas quanto as aplicações Server-Side (Back-end) e possuem arquiteturas e padrões para serem criadas de forma a suportar pequenas e simples, mas também grandes e complexas aplicações. Por isso a arquitetura MVC pode ser quebrada, tendo a Camada de Visualização se tornado uma aplicação com sua própria arquitetura. O foco desse artigo será a arquitetura da aplicação Server-Side.

Tirando a Camada de Visualização da nossa arquitetura, se fóssemos seguir a arquitetura MVC iríamos sobrar apenas com duas camadas: a Camada de Dados e a Camada de Comunicação, mas como eu disse anteriormente esse tipo de arquitetura resulta em um código muito acoplado, onde podemos ter duplicação de código e muitas responsabilidades em uma única camada.

A Nova Arquitetura Server-Side

Se as duas camadas que falamos anteriormente não são suficientes para criar uma aplicação mais limpa e fácil de ser mantida, a solução é recriar a arquitetura da nossa aplicação server-side para que ela fique mais desacoplada e mais limpa.

Existem diversos livros, cursos e tutoriais falando sobre e também existem N tipos de arquitetura que são possíveis, aqui eu vou explicar apenas uma dessas arquiteturas, mas que funciona para mim e os projetos que tenho trabalhado nos últimos anos.

A arquitetura que venho utilizando é composta por quatro camadas:

Camada de Comunicação
Camada de Validação
Camada de Serviço/Negócio
Camada de Dados

Abaixo irei explicar resumidamente cada camada.

Camada de Comunicação

Essa é a camada mais simples da aplicação e com menos responsabilidades, como o próprio nome diz, ela é a camada de comunicação entre o usuário e a lógica da nossa aplicação. Ela é responsável apenas pelo IO (Input & Output) da nossa aplicação, ou seja, essa aplicação recebe os dados enviados pelo usuário (pode ser através de uma ferramenta CLI ou uma página Web ou uma App de dispositivos móveis) e retorna o resultado de volta ao usuário depois de passar pelas outras camadas.

Camada de Validação

Essa camada é responsável por validar os dados recebidos pela Camada de Comunicação. E se você está perguntando o motivo de separar essas duas camadas a resposta é simples. Imagine que hoje sua aplicação comunique com uma página Web e toda validação esteja acoplada com a requisição HTTP. Agora você ou sua empresa decidem criar uma ferramenta CLI para a aplicação. Estando sua lógica de validação acoplada com a requisição HTTP, você terá de recriar toda a lógica de validação novamente. Se você tivesse separado isso em uma camada específica, bastava recriar uma nova Camada de Comunicação que seria para a ferramenta CLI e toda sua aplicação estaria a funcionar normalmente.

Camada de Serviço/Negócio

Essa é a camada mais importante da nossa aplicação, aqui é onde fica toda a lógica de negócio, todo o núcleo da aplicação. Essa camada é responsável por receber os dados já validados da Camada de Validação, buscar os dados necessários, aplicar a lógica necessária e formatar os dados de forma a enviar de volta para a Camada de Comunicação.

Camada de Dados

Essa é a camada responsável por buscar e salvar os dados na(s) Base(s) de Dados da aplicação. Para se ter a separação da regra de negócio dos dados, essa deve ser a ÚNICA camada que faz acesso à(s) Base(s) de Dados, dessa forma se qualquer outra camada necessitar de acessar esses dados, deve ser feito através dessa camada.

Conclusão

Com esse artigo aprendemos o que é a arquitetura MVC, os motivos dessa arquitetura estar obsoleta nos dias de hoje e vimos o exemplo de uma arquitetura para as aplicações Server-Side atuais que apesar de simples, é eficaz para se criar aplicações limpas e com código menos acoplado. Essa arquitetura pode ser aplicada em qualquer linguagem e não apenas para aplicações Web, como também APIs, CLIs, etc.

Espero que esse artigo possa ajudar vocês a terem uma visão de como a arquitetura e o design da aplicação pode influenciar e MUITO no resultado final do software, para conseguir criar um software limpo e fácil de ser mantido e evoluído.

PurgeCSS gotchas

Wendell Adriel — Wed, 13 May 2020 14:10:59 +0000

Some time ago I bought a Tailwind UI license and I wanted to test it alongside Vue.

Following the example of someone who created a website to sell pixels from the website: http://milliondollarhomepage.com

And the "I'm Rich" app: https://en.wikipedia.org/wiki/I_Am_Rich

I came up with something funny to work on and test it. I created URList, a site to archive a limited amount of URLs that can be tagged!!! 🥳🥳🥳

I used Laravel, Laravel Forge, Vue CLI and Tailwind UI to create it and it was a wonderful experience! If you already worked with TailwindCSS you know that it offers a wonderful experience to create UIs, so you know what I'm talking about.

The first time I created a build I didn't set the PurgeCSS so I got a 3MB+ css file. Then I configured PurgeCSS and ran again and it was less than 20Kb, this is amazing!!! But when I took a look on the app, some things were broken and I didn't understand why, but it was because of the PurgeCSS somehow.

After some minutes I remembered that I had some classes that were applied dynamically using Vue, so I set these on PurgeCSS whitelist and it was all good.

I know that this is something really basic and simple, but I thought about writing about this because since I had this issue, maybe it will help someone else.

Creating Modularized Stateless APIs with Laravel 7.x

Wendell Adriel — Wed, 25 Mar 2020 19:08:15 +0000

I work with the Laravel framework since it was on version 4.x and I really love the Framework and the things that it provides. But when I started to work with more complex applications and creating APIs with it, I missed some things. So I saw myself doing the same configurations and changing the default Laravel installation structure quite some times. So I decided to create a Skeleton structure for myself and also to use as the base structure for the new API for my company, that’s when I created LarAPI and made it as an Open Source project this week:

https://github.com/WendellAdriel/larapi

This Skeleton has a lot of things already configured out-of-the-box:

JWT Authentication
User Roles
API documentation with Swagger
Exception Handler configured to return only JSON responses
Base classes with common features for projects
Git Hooks to lint the code, run tests and update the API documentation automatically

I’m still planning to add more things, but you can start using it right now!!! Check out the repository for the complete documentation and to know how to use it.
If you want to help, give it a star and share with your friends!

A Walk on the Svelte Side: Introduction

Wendell Adriel — Mon, 13 May 2019 17:29:39 +0000

CodeShare

I have a project called CodeShare, to create free and high-quality content in Portuguese, to reach more people in Brazil that didn’t have the opportunity to learn English yet.

So when I write a post there, I’ll post here as well, but in English (of course), so if you want to check the original version of this article (in Portuguese) you can check it here!

Introduction

You may have entered this article because you heard this name somewhere and don't know what it is, or you already know, but you want to know more about it or you can be just asking yourself something like "Why do I need another reactive UI lib if I already have React and Vue?". So, whatever reason that brought you here, prepare yourself because we're going on an adventure: A Walk on the Svelte Side is the new series of articles from CodeShare where I'll show what Svelte is, its main features and we will build examples along with this series and in the end you'll be ready to start using this lib in your projects!

This first article will be more theoretical, but that's really important to know how Svelte differs from other libs. I suggest that you read with attention so we can dive in the code after.

What is Svelte

Svelte, like other UI libs, is based in components, but with an essential and very important difference: it doesn't use the Virtual DOM differentiation like React or Vue.js because this libs use declarative structures that are converted into DOM operations that can overload a little the frames of our apps and also the Garbage Collector (in Portuguese).

But how Svelte works then? All the work is done in the build time, that way it converts all of your components to a high-performance imperative code that applies the fewest possible DOM operations, making that Svelte "disappears" completely of your final code. You'll have a pure, high-performance imperative JavaScript code. We can highlight some important aspects of Svelte:

Extraordinary performance
Small bundles
Accessibility aspects included in the lib
Styles encapsulation/isolation by default
Declarative transitions included in the lib
Learning curve

And in the end, the answer to our question: "What is Svelte?" can be answered saying that it's a compiler because its job is to compile the components into an imperative JavaScript code.

Reactivity on Svelte

Svelte version 3 was released on April 21 and brought huge changes to the lib, making that the written code is cleaner and improving how it works with the reactivity of the components. For example, before this version, to update the state of our components we needed something like:

const { clicks } = this.get()
this.set({ clicks: clicks + 1 })

If you already worked with React, you'll note a huge resemblance on how we handle the state on a class based component (before the launch of the famous Hooks):

const { clicks } = this.state
this.setState({ clicks: clicks + 1 })

With the launch of the Hooks, the way that React works with the state of the components has changed significantly and some other libs started to create their own version of the Hooks. Svelte didn't want to follow this path, because behind the curtains they create some overload to the Garbage Collector (in Portuguese) and if you need to run this code on an embedded device or if your app relies on many animation-based interactions this can lead to some issues.

So how Svelte 3 works with reactivity and updating a component state? In a very simple way, without using proxies or nothing like that. When we want to change for example a state variable named clicks, we just need to update it:

clicks += 1

Since Svelte's job is done in the app build time, for being a compiler, it can only do the instrumentation of these updates without any additional complexity. Behind the curtains what he does is:

clicks += 1
$$invalidate('count', count)

Performance on Svelte

One of the main diff between Svelte and other libs like React and Vue is that it doesn't use the Virtual DOM, but you must be thinking: how can it be so fast without using the Virtual DOM? If you work with Front-end (or even with Back-end, but like to read about), probably you already heard about the Virtual DOM and that working with it is more performant than with the Real DOM.

But what's the Virtual DOM and how the libs work with it? In a very simple way, the Virtual DOM is only a JavaScript object that defines the basic structure of your page. When a change occurs in the state of your application, for example, the value of some property is updated, it's created a new object and the lib work is to find the diff between the old and the new object and apply the fewest number of updates in the Real DOM.

In practice, there is no way to make any changes to the Real DOM without first comparing the two states of the Virtual DOM, but this can lead to some unnecessary steps. Svelte works as a compiler, in the app build time it already knows how the state of the application can be changed, so it generates the fewest possible steps to manage this possible changes without having any work during application execution.

Creating our first Svelte component

One of the main features of Svelte is to let us build apps in a simple way and writing less code. The longest the code, greater will be the effort to understand it and the chance of having bugs increases, so when we write less code, we have the benefit of being able to understand it faster and introducing fewer bugs.

Let's create our first component, it will be something really simple. We will have two text fields where we can provide our first and last name respectively and it will be shown a welcome message on the screen with our full name. Svelte components use the .svelte extension where we declare:

the behaviour of our component with JavaScript inside a <script> tag
the style of our component with CSS inside a <style> tag, the styles that we declare on a component have a restrict scope to that component, that means that if you create a rule to change the style of the <p> tags of your component, it won't affect any other <p> tag outside your component
the structure of our component with HTML, it is not necessary to encapsulate this structure in a <template> tag as we do on Vue, and also may have several root elements, other than the React that we can return only one element or use the Fragments.

First, we have the behaviour part of our component that will be a totally normal and basic JavaScript code. We will create two variables and define a function that we will use when we define the structure of our component:

<script>
    let firstName = ''
    let lastName = ''

    function showGreeting () {
        window.alert(`Welcome, ${firstName} ${lastName}`)
    }
</script>

Below we will also define the style of our component that is also a normal CSS code, the only difference is that the styles declared here will affect only the elements of this component:

<style>
    * {
        font-family: sans-serif;
    }

    p {
        font-weight: 700;
    }

    .warning {
        color: #ff2b56;
    }
</style>

The last part of our component is the structure of our component, that's done with HTML, with only some little details that we will check after:

<label for="first_name">First name:</label>
<input id="first_name" type="text" bind:value={firstName}>

<label for="last_name">Last name:</label>
<input id="last_name" type="text" bind:value={lastName}>

{#if firstName.length > 0 && lastName.length > 0}
    <p>Hello, {`${firstName} ${lastName}`}</p>
    <p>
        <button type="button" on:click={showGreeting}>Show alert greeting!</button>
    </p>
{:else}
    <p class="warning">Type your first and last name above...</p>
{/if}

As you can see we have some details that aren't an HTML code in our structure, but that is used to connect the structure of our component with its behaviour. In our <input> elements the attribute value is changed to bind:value={variable}, where we link a state variable of our component so that when this variable is changed the change will be reflected in the <input> element and vice versa.

Just as it is easy to link state variables, invoking functions that we define when an event occurs in the DOM is also very easy, we use on:event={function}. In our code, when the button receives a click it will invoke our showGreeting function defined above.

Often we need to show or hide some content according to the state of our component, Svelte gives us a simple way to do this with the blocks: {#if} {:else if} {:else} {/if}, this way we can control in a simple and clean way what and when to display and hide some content.

Our example can be seen in the CodeSandbox below:

As you can see in the CodeSandbox above, we have a index.js file that imports our component and renders it in the <body>. This file alongside with the files package.json and the config for Rollup, the default bundler that Svelte uses, rollup.config.js are already included in the default template for Svelte.

You can play on the CodeSandbox to not need to create the projects locally, but if you want to is really easy as well. We can use NPX to create our project in a simple way:

npx degit sveltejs/template my-app && cd my-app && yarn

That way you'll create a project using a tool called Degit that will create a copy of this repository that's the minimum default template for an app, with all the needed config. If you prefer or want to make any changes to this default template you can fork this repository and change the command above to use your Github user:

npx degit your-github-user/template my-app && cd my-app && yarn

In the README.md file of this template you'll find instructions on how to run your project locally and also instructions on how to deploy your app.

Conclusion

In this first article we saw what Svelte is, its main features and we built our first component to see how it works. In the next articles we will go deeper on other features of this lib while we create examples to put in practice the concepts we will learn.

I hope that you liked this article and if you do, don't forget about commenting and sharing this article with your friends!!! See ya! 😎

Working with multiple CSS themes

Wendell Adriel — Fri, 26 Apr 2019 19:17:41 +0000

CodeShare

I have a project called CodeShare, to create free and high-quality content in Portuguese, to reach more people in Brazil that didn’t have the opportunity to learn English yet.

So when I write a post there, I’ll post here as well, but in English (of course), so if you want to check the original version of this article (in Portuguese) you can check it here!

Introduction

In the first article of this series we saw how variables work on CSS and how we can use them to create themes for our projects. In this article, we will put this into practice creating some simple themes and seeing how to change between them.

Creating the Default Theme

As we saw before, the :root selector can be used to store the global variables of our themes. To create a default theme for our app, we will define some variables in this selector that will be used by our elements:

:root {
    --global-bg-color: #fff;
    --global-font-family: Verdana, sans-serif;
    --global-text-color: #222;
    --global-link-color: blue;
    --global-link-hover: lightblue;
}

In the code above we defined some variables that will be used as the base values for our theme. That way we can use these values to style our elements. Since we're only working on an example, the number of variables we have are just a few, but in a large project, this list can be much bigger. Now, let's use our variables:

html {
    background: var(--global-bg-color);
    font-family: var(--global-font-family);
    color: var(--global-text-color);
}

a {
    color: var(--global-link-color);
    text-decoration: none;
    font-weight: 700;
}

a:hover {
    color: var(--global-link-hover);
}

In the code above we used our variables to control the background and text colors, the font and also the color of the links. If in the middle of our project we want to customize any of these values, we just need to change the value of the variable that we want and all the elements that use it will update, pretty simple. Now let's create some elements to check our theme in action:

<!DOCTYPE html>
<html>
    <head>
        <title>Tematização com CSS</title>
        <meta charset="UTF-8" />

        <style>
            <!-- STYLE HERE -->
        </style>
    </head>

    <body>
        <h1>Tematização com variáveis CSS</h1>
        <p>
            Exemplo para ser usado em um artigo na
            <a href="https://codeshare.com.br" target="_blank">CodeShare</a>
        </p>
    </body>
</html>

Creating a Night Mode Theme

Now that we already have our default theme, we can work in a new theme for our app. A lot of sites have a "Night Mode" to make it easier to read during the night. Let's create a theme for this.

There are some ways of working with themes, but my favorite is to use the data- attributes on HTML. These data- attributes are a convention used to define custom attributes for tags and to identify which theme we're using we will create a data-theme attribute. All the elements with this attribute and their children will be modified. Since our new theme will be for our Night Mode we will call it dark.

Since our elements are already using the variables that we created, to create a new theme we just need to update the values of the ones that we need to modify, that way the values that we change will overwrite the others and the ones we don't change will be inherited from the :root element. We will use the attribute selector on CSS to apply our theme. Since our theme is a Global Theme, we will link it to the <html> tag:

html[data-theme='dark'] {
  --global-bg-color: #444;
  --global-text-color: #ddd;
  --global-link-color: yellow;
  --global-link-hover: lightyellow;
}

In the code above we changed the colors for the background, text and links. Now we just need to put the data-theme="dark" attribute in our <html> tag to see the result:

Letting the user switch themes

Now that we created two themes for our app, it would be interesting if we let the user switch between them right? It's not something hard to do, let's create this option. First, let's remove the data-theme="dark" attribute from our <html> tag and create the element that will let the user switch themes when clicked.

<!DOCTYPE html>
<html>
    ...
    <body>
        <span id="theme-toggle" class="theme-toggle"></span>
        ...
    </body>
</html>

Now let's style this element, for that we will create two new variables. We will create this element as a fixed element, so the user can switch themes whenever he wants to. We will also assign different values for these variables when our dark theme is enabled, making that this element will also update its appearance:

:root {
    ...
    --global-theme-toggle-bg: #ccc;
    --global-theme-toggle-content: '🌞 THEME';
}

html[data-theme='dark'] {
    ...
    --global-theme-toggle-bg: #000;
    --global-theme-toggle-content: '🌝 THEME';
}

.theme-toggle {
    position: fixed;
    right: 20px;
    top: 20px;
    background: var(--global-theme-toggle-bg);
    padding: 10px;
    border-radius: 5px;
    font-size: 0.8rem;
    font-weight: 700;
    cursor: pointer;
}

.theme-toggle::after {
    content: var(--global-theme-toggle-content);
}

Now that we have finished setting up the visual part of our component, let's add the needed action to make that our theme will switch when the element is clicked:

function toggleTheme () {
    const htmlTag = document.getElementsByTagName("html")[0]
    if (htmlTag.hasAttribute("data-theme")) {
        htmlTag.removeAttribute("data-theme")
        return
    }

    htmlTag.setAttribute("data-theme", "dark")
}

document
    .getElementById("theme-toggle")
    .addEventListener("click", toggleTheme);

In the code above we created a function that will check if the <html> tag has a data-theme attribute and if so, it will remove it and if doesn't, it will add this attribute with the value dark to activate our Night Mode Theme. After that we create a listener in our element that when it gets clicked it will run the function that we just created:

Improving the Theme Switching

Congrats for us! We already let that our users can switch the theme of our app, but we still have some little details that we can improve. For example, when we switch the theme, the update is made in a very sudden way, it would be interesting to make this update in a smoother way and we can do that easily using the transition rule from CSS, check how simple it is:

html {
    ...
    transition: all 1s;
}

a {
    ...
    transition: all 1s;
}

And it's done!!! See how now the transition between themes is being made much smoother and pleasing to the eye!!! But we can still improve something else. When the user enters in our app and change the theme and leave, we want that when he returns, the site will load the last chosen theme, for that we will use the localStorage to store this info. We will need to make a little change in our toggleTheme function and create one more function to help us:

function toggleTheme () {
    const htmlTag = document.getElementsByTagName('html')[0]
    if (htmlTag.hasAttribute('data-theme')) {
        htmlTag.removeAttribute('data-theme')
        return window.localStorage.removeItem("site-theme")
    }

    htmlTag.setAttribute('data-theme', 'dark')
    window.localStorage.setItem("site-theme", "dark")
}

function applyInitialTheme () {
    const theme = window.localStorage.getItem("site-theme")
    if (theme !== null) {
        const htmlTag = document.getElementsByTagName("html")[0]
        htmlTag.setAttribute("data-theme", theme)
    }
}

applyInitialTheme();

document
    .getElementById("theme-toggle")
    .addEventListener("click", toggleTheme);

That's it, now we can offer a special experience for our users!!!

Applying Themes in Specific Zones

We saw above how to create and switch between two Global Themes, that means that they're applied in our application as a whole, but we can also apply themes to specific zones in our app. To show that, let's create a theme that will change only the font and let's apply that to some elements:

[data-theme='comic'] {
    --global-font-family: 'Comic Sans MS';
}

p, span {
    font-family: var(--global-font-family);
}

<body>
    <span data-theme="comic" id="theme-toggle" class="theme-toggle"></span>
    <h1>Tematização com variáveis CSS</h1>
    <p>
        Exemplo para ser usado em um artigo na
        <a href="https://codeshare.com.br" target="_blank">CodeShare</a>
    </p>

    <p data-theme="comic">
        Exemplo de um tema aplicado em partes específicas da página! Esse texto
        tem o tema "comic"!
    </p>
</body>

Conclusion

In our examples above, we worked with three simple themes, but in larger projects, the complexity of the themes can be much bigger. Thinking about that, I created a lib called CSS Theme Manager that helps in the management of themes based in CSS variables, check it out and if you find it interesting, use it in your projects!

WendellAdriel / css-theme-manager

Zero dependency lib to manage CSS themes easily for your app

CSS Theme Manager

Zero dependency lib to manage CSS themes easily for your app

How to use

Install the package

npm install css-theme-manager --save
// or with yarn
yarn add css-theme-manager

Import it and init the CSS Theme Manager with a default theme A theme is an object with the name of your variables as keys and the value of the variables as the values.

import CSSThemeManager from 'css-theme-manager'

const themeManager = new CSSThemeManager({
  'bg-color': '#fff',
  'text-color': 'darkblue',
  'featured-font': 'Verdana, sans-serif'
})

This will create and insert the given variables in the :root selector. All the variables created with this CSS Theme Manager will have a csstm- prefix. The code above will result in:

:root {
    --csstm-bg-color: '#fff';
    --csstm-text-color: 'darkblue';
    --csstm-featured-font: 'Verdana, sans-serif';
}

Check the API Reference below to check all that you can…

View on GitHub

I hope that you liked this article and if you do, don't forget about commenting and sharing this article with your friends!!! See ya! 😎

Theming with CSS variables

Wendell Adriel — Wed, 24 Apr 2019 14:51:51 +0000

CodeShare

I have a project called CodeShare, to create free and high-quality content in Portuguese, to reach more people in Brazil that didn't have the opportunity to learn English yet.

So when I write a post there, I'll use DEV.to to post here as well, but in English (of course).

Introduction

It doesn't matter if we're creating a website or an admin page or an app, we need to deliver a solid and consistent design always. We can't have a software where on each page we use a different font or buttons of all colours and shapes. We need to define a pattern, not only because of the visual aspect but when we create a pattern of colours and layout, the users can learn and get used quickly with our product.

To make this process easier, some time ago we had to ask for the help of the CSS pre-processors to use features like variables that make our lives easier when it comes to theming. Gladly we don't need that anymore because of CSS already let us work with variables natively and in this article, we will see how we can use this feature to create a simple, yet efficient design system for our projects.

Declaring and using variables

To declare a CSS variable it's super simple. The name of the variables MUST start with -- and they are case-sensitive.

.my-class {
    --font-size: 1rem;
}

The same way that's easy to declare a variable, using it is also super simple. We just need to use the var() function. This function takes two parameters: the first one is the name of the variable that we want to get its value and the second one is an optional parameter with a fallback value if the given variable passed as the first parameter isn't found.

.my-class p {
    font-size: var(--font-size, 0.8rem);
}

The variables on CSS inherit values, that means that if a value is not found in a given element, the parent element value will be used.

Two layers theming

If in our project we group all variables in a single place (Global Variables), we create a single source of truth, but we lose the ability to modularize our theme and always when a dev needs to customize a component he will need to overwrite the CSS rules.

In the other hand, if we leave the variables scattered all around, we will create a modularized theme, but we lose the consistency between our components and if we need to make a general change, we will have a lot of work.

To solve this issue we will think about our theme having two layers, we will have the Global Variables and the Modules Variables. That way we can get the best of the two worlds.

Global Variables

Global variables are generic variables that will be used to keep the consistency between all our components. Some examples of global variables are font, default font-size and color palette. It's super simple to define global variables on CSS, we use the :root selector and inside it, we define our variables. It's not mandatory, but to make it simple to identify that a variable is global or not, I like to use the global- prefix, that way when I'm reading the code I can already know that certain value comes from a global variable.

:root {
    --global-font-family: Verdana, sans-serif;
    --global-font-size: 0.8rem;
    --global-text-color: #222;
    --global-primary-title-size: 2rem;
    --global-color-primary: #88498f;
    --global-color-secondary: #779fa1;
    --global-color-warning: #e28413;
    --global-color-danger: #ff6542;
}

In the code above, we define some variables that will be used as base values in all our project: font, font size for texts and for main titles, font color for texts and a color palette with four different colors. Now we will use the global variables that we just defined:

body {
    font-family: var(--global-font-family);
    font-size: var(--global-font-size);
    color: var(--global-text-color);
}

h1 {
    font-size: var(--global-primary-title-size);
}

In the code above we define the default font, font color and font size for all our product and we also define the font size for the main titles. If we need to change any of these values in the middle of our project, we just need to change the variables declaration with the new values and it's done! That way we can create some sort of consistency in our product and also create a common reference point for devs and designers to work together in a quick and easy way.

Modules Variables

These are variables with a restricted scope where it's defined. Every module variable MUST be defined using the value from a global variable and we also need to provide a fallback value for the case that the module will be used in an environment that doesn't provide global variables, it doesn't break. It's not mandatory, but to make it simple to identify that a variable is a module variable, I like to use the module- prefix, that way when I'm reading the code I can already know that certain value comes from a variable of the X module. Let's take as an example a module for a button:

:root {
    ...
    --global-border-radius-sm: 3px;
    --global-text-color-light: #fff;
}

.btn {
    --btn-border-radius: var(--global-border-radius-sm);
    --btn-text-color: var(--global-text-color-light);
    border-radius: var(--btn-border-radius, 5px);
    color: var(--btn-text-color, #ddd);
}

.btn-primary {
    --btn-primary-bg: var(--global-color-primary);
    --btn-primary-border: var(--global-color-primary);
    background-color: var(--btn-primary-bg, #605770);
    border-color: var(--btn-primary-bg, #605770);
}

.btn-secondary {
    --btn-secondary-bg: var(--global-color-secondary);
    --btn-secondart-border: var(--global-color-secondary);
    background-color: var(--btn-secondary-bg, #7fc29b);
    border-color: var(--btn-secondary-bg, #7fc29b);
}

Understanding the two layers theming

Ok, now that we already saw how to structure our theme, we need to understand the reason why this Two Layers Theming works. The way that we built our theme, we make independent modules, because if they are being used on a context where we have the global variables, they will inherit the values from these variables, but if it doesn't find these variables, we also defined fallback values that will be used.

We also made that changes can be really easy to be done. For example if we want to change the primary color everywhere in our product, we just need to change the --global-color-primary global variable and all our modules, including the btn module will be affected. Now imagine that we want to change the font color of all our buttons, we can change the --global-text-color-light variable, but that will affect all the other modules, so we just need to change the --btn-text-color module variable that will affect only the btn module.

Conclusion

We saw how to create a consistent and adaptable theme for our projects using only CSS. Using this Two Layers Theming approach, we created a better environment and experience for our teams of devs and designers. You can check an example of the code we created in this article in this Codepen that I created:

I hope that you liked this article and if you do, don't forget about commenting and sharing this article with your friends!!! See ya! 😎