Application based themed styling for your components

More precisely: workspace based styling

Content

1. Introduction
2. Background infos
3. How to create a new workspace?
4. The theming demo
5. Creating the neumorphic button & toolbar
6. Adding the neumorphic components into MyApp1
7. Creating the blue button & red toolbar
8. Can we do more?
9. What is neo.mjs?

1. Introduction

It was possible for a long time to add new components into the neo.mjs framework and using the SCSS based theming engine to style your components differently for each theme.

With the new theming engine in place, we now get a granular CSS output, we can automatically lazy load CSS files as needed and we even get cross browser window delta CSS updates for the multi window apps scope.

However, one important thing was missing: In case you want to create new components which either don’t fit into the framework scope or you (or your company) don’t want to share them with the community, we need the ability to style components inside your workspaces.

This article will cover how to do it.

2. Background infos

In case you want to learn more about the new theming engine under the hood, as well as the different modes (optional CSS vars):

How to create a file by file custom SCSS build including dependencies, using postcss and optional…

This article covers delta CSS updates across multiple browser windows:

Expanding Single Page Apps into multiple Browser Windows — Part 2

3. How to create a new workspace?

The neo.mjs CLI got you covered. Just enter the following into your terminal (or cmd):

> npx neo-app

You can just hit enter on all questions.

This video is a little bit outdated (the theme builds are no longer using webpack), but the result is still the same.

In case something does not work for you using the npx script locally, you can just clone / fork the following repo:

neomjs/workspace

Just run:

> npm install

4. The theming demo

I created a new repository to show you some example use cases here:

neomjs/theming-demo

Inside this repo, I created a second app. Let us take a quick look into the package.json file:

We can use all neo.mjs programs inside a workspace too.

To create a second app, we don’t need to use the npx call again, but go for

> npm run create-app

A quick overview of the demo structure:

5. Creating the neumorphic button & toolbar

We want to use the neumorphic button & toolbar inside MyApp1 and MyApp2. While we could create the components inside MyApp1 and import the files inside MyApp2, this feels very wrong from an architecture perspective.

The clean way is to create both components inside the workspace src folder.

src/button/Neumorphic.mjs

src/container/NeumorphicToolbar.mjs

In case there was a neumorphic theme already, we would not need these class extensions. Possible to do it. In case you like the idea, add a comment here:
https://github.com/neomjs/neo/discussions/2049

For the button class, we want to extend button.Base, for the toolbar class, the base class container.Toolbar fits best. We are just adding an extra CSS class for both of our custom components and this is it.

We also create 2 SCSS files inside the resources/scss folder. Important: we need to use the same namespace.

resources/scss/src/button/Neumorphic.scss

resources/scss/src/container/NeumorphicToolbar.scss

We are using a double box-shadow for the button states and stick to just CSS for this one (we will cover SCSS vars inside the section 7).

6. Adding the neumorphic components into MyApp1

This part is easy, we just need to import and add the new items into our MainContainer JS module.

We need to run a themes build at this point:

> npm run build-themes

Our demo app default theme is “theme-light”, so you can pick the build options

1. themes: theme-light
2. env: dev
3. use CSS vars: yes

This build takes 2.01s on my machine.

Let us open the dev mode version inside your browser:

Press a button:

Looking into the dev tools:

Real code (no source maps) inside the application worker scope.

7. Creating the blue button & red toolbar

We will only use these two inside MyApp1, so let us create the files there.

apps/myapp/view/BlueButton.mjs

apps/myapp/view/RedToolbar.mjs

Same as before.

resources/scss/src/apps/myapp/view/BlueButton.scss

resources/scss/src/apps/myapp/view/RedToolbar.scss

In case you need more infos about the v() method, the first article inside background infos covers this in depth.

In short: in case we are building a theme using CSS variables, we will get the matching CSS var as the value. Without using CSS vars, we will get the plain value of the SCSS variable instead.

So, we need to define this one:

resources/scss/theme-light/apps/myapp/view/RedToolbar.scss

The neo($key) is just a shortcut for map-get($neoMap, $key) .

Now the really cool part here is that you can literally use all SCSS vars which exist inside the neo theme.

Example:

We could e.g. use textfield-border-color which is not related to the class hierarchy at all.

[Side note] Take a look at the _all.scss files inside the workspace theme folder. For “var” files, we need to manually include them in an order which honors the dependencies. E.g. if you create a component inside your workspace which uses vars of a different workspace component.

apps/myapp/view/MainContainer.mjs

> npm run build-all

We want to get the theme enhancements as well as the dist versions.

Inside dist/production we now get our cross apps split chunks.

8. Can we do more?

In case you have been following the neo.mjs blog, you have most likely seen that we can lazy load tab.Container items as needed. This would include lazy loading the required CSS as well. I skipped this part here to keep the article shorter.

On top of using the SCSS engine, you can as well specify inline styles for your components.

You can apply a neo-theme on any level of the virtual dom, so having parts of your apps using different themes is a piece of cake. You could as well drop a theme into the cls config of a component (either on class or instance level). Take a look at the docs app (dev mode → examples) to get the idea.

If you think about creating components inside a workspace src folder, the buzzword micro frontends will probably have popped up in your mind.

This is actually one goal. Prepare for a follow up article where we will add a workspace into another one as a dependency :)

9. What is neo.mjs?

I just had to create an only 33s video for the Javascript Open Source awards program (the deadline ended on May 16th):

You can find the fully MIT licensed project here:

neomjs/neo

The most important design goal is an application worker being the main actor:

This blog post marks the v2.1.0 release.

Best regards & happy coding,
Tobias