DEV Community: James Byrne

Using TailwindCss with Ember

James Byrne — Fri, 03 Jan 2020 19:47:12 +0000

Using tailwindcss

For the last year or more, both in work and at home, I've been using tailwindcss for styling. I love composing styles together with css utility classes to create great User Interfaces (UI) & User Experiences (UX). Overall I've found it great and it's functional/compositional nature really gels with me.

I also love it's component system as well! Reducing the number of abstractions to be made up front is a godsend for any project growing quickly.

Since I like it so much and I use it in pretty much all my examples for all of my posts I thought I'd write up a quick guide for how to get running with tailwindcss and ember.

Cool! …. but what is it though?

feel free to skip if you know what tailwind is

Ok for those of you that haven't worked with it yet, tailwindcss is a utility-first framework. You start with a set of css classes, each of which do one thing well. You then compose these classes together to get more complex behaviour. For example, below is a simple, overly excited, button.

<button class="bg-pink-500 text-white">Press ME!</button>

Now the classes here are pretty self explanatory but let's go through them anyway.

bg-pink-500: set the background colour to pink with a hue of 500
- Hue is a bit like font-weight, in increments of 100 it gets darker starting at 100 and ending at 900
text-white: sets the text colour to white

Simple enough right? But it's not really a nice looking button yet. For one the button is only as big as the text we put into it. Let's make it a tad nicer, we'll add a shadow, round the corners, add margin and some padding.

<button class="shadow bg-pink-500 text-white px-4 py-2 rounded m-10">
  Press ME!
</button>

Much better! See how easy it is to update the styles of a component, no other files, picking colours or shadows. Just sensible, configurable defaults. I'll do the same as above and go through what we've added just to be sure we're all on the same page too.

shadow : Adds a medium sized shadow
- We can also use -sm, -lg etc. for bigger or smaller options
px-4: This adds padding in the x axis, with the 4 relating to the amount of rem to add, in this case 1rem
py-2 : The same as px but in the y axis and 2 gives us .5rem
rounded : This adds a border-radius
- -sm, -lg etc. applies here too
m-10 : Adds margin of 2.5rem in both the x & y axis

Ok cool, but it's kinda boring right? You hover over it and nothing happens. What if we made it look more interactive. Let's do that, we'll add a simple hover effect to increase the shadow size and darken the button.

<button class="shadow hover:shadow-lg bg-pink-500 hover:bg-pink-700 text-white px-4 py-2 rounded m-10">
    Press ME!
</button>

I'm going to take it you get the gist by now. By using these small independent classes we can specify good looking and complex designs without having to worry about writing our own styles. This has a huge impact when creating mocks UIs and helps set a standard set of classes for growing or already large projects.

For large projects under re-write or time critical tasks you'll find the amount of css you don't need to write is a godsend! Speaking from first hand experience on this one.

Ok now that I have you sold on how awesome tailwindcss is let's add it to your ember project!

Adding tailwindcss to an ember app

Previously we could install the library using ember-cli-tailwind by the great people at embermap but it has been deprecated in favour of another package. While more configurable and undoubtably better there is a little more setup involved and since I use it a lot I want to write a small guide on adding it to your projects.

So this section covers how we can get an ember app up and running with tailwind but if your pretty comfortable with embers basics you can check out the excellent documentation on the github page here.

Getting started

skip this if it's an existing app

First of all let's get ember installed. We'll need a version of node installed first, details here. Then we can install ember using ‘npm' like so:

npm install ember-cli -g

Now that we have ember installed we can create our new project and set it running with the following commands:

ember new tailwind-app
cd tailwind-app/

A quick proof of concept

Now before we dive into setting up tailwind let's first create a small example that uses tailwind classes, that way we know they are working later. Add the following to your app/templates/application.hbs file.

<div class="flex items-center justify-center h-screen bg-gray-100">
  <button class="shadow-md hover:shadow-lg hover:bg-green-500 bg-green-400 text-white px-8 py-5 rounded">
    A beautiful button!
  </button>
</div>

Now to get our ember app up and running we need to run ember serve. Once that's finished building visit localhost:4200 in your browser. You should see the following beautiful button.

..... anyway on with the tutorial!

Configuring PostCSS

The next step is to add tailwind itself and configure it into the ember build pipeline. It's easier than it sounds I swear. To start we will need the following dependencies:

yarn add ember-cli-postcss tailwindcss postcss-import @fullhuman/postcss-purgecss -D

Next we need to generate the tailwind configuration file. To do this we need to enter the tailwind directory within our app and run the tailwind init command using npx (npm install npx -g if you don't have it).

mkdir app/tailwind
npx tailwind init app/tailwind/config.js --full

For a real project we wouldn't want to use --full as it includes all of Tailwinds default configuration. You can see more info on this here

Before going further you might want to add /*global module*/ to the top of our new config file to suppress build warnings

Only two more steps left to go! Now we want to configure PostCSS in the Ember Build Pipeline. To do this we need to open ember-cli-build.js and update it to look like the following:

// ember-cli-build.js
'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const isProduction = EmberApp.env() === 'production';

const purgeCSS = {
  module: require('@fullhuman/postcss-purgecss'),
  options: {
    content: [
      // add extra paths here for components/controllers which include tailwind classes
      './app/index.html',
      './app/templates/**/*.hbs'
    ],
    defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || []
  }
}

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    postcssOptions: {
      compile: {
        plugins: [
          {
            module: require('postcss-import'),
            options: {
              path: ['node_modules']
            }
          },
          require('tailwindcss')('./app/tailwind/config.js'),
          ...isProduction ? [purgeCSS] : []
        ]
      }
    }
  });
  return app.toTree();
};

Wiring up Tailwind

The last step is to create a new css file and ensure that the tailwind css is included. We want to create app/styles/components.css and app/styles/utilities.css and include them in our existing app/styles/app.css file like the following.

@import "tailwindcss/base";

@import "tailwindcss/components";
@import "components.css";

@import "tailwindcss/utilities";
@import "utilities.css";

Awesome! Now we can restart our app (running ember serve) and we should have a styled application! Our template should look like the below image.

That's a bit better 😄.

Static Types in EmberJs?

James Byrne — Mon, 10 Jun 2019 08:04:20 +0000

Static Types in EmberJs?

So you’ve decided to add Typescript to your Ember project. You’ve heard all about the benefits of Static Typing and how it will deliver a more maintainable codebase than plain ol’ javascript (couldn’t be that hard right?).

Well before you dive in head first there are a few points I’d recommend you consider. After all, this is a change to your underlying programming language (yes I know it’s a superset and more on that later) so some pros and cons are to be expected. But to start of positive, let’s look at some of the upsides first.

Note I will not be discussing Classes or decorators much in this doc, if you want an intro to them I highly recommend this post by pzuraq.

The Good

The Benefits of Static Typing

This is now my favourite meme ever

Probably the most talked about feature of Typescript is its Static Types which we can use to specify the type of value we expect from a paramter/variable. This in turn gives the Typescript compiler the ability to catch common errors in the compile step, reducing the number of bugs that make it to production.

An example of this would be parsing some data structure. Let’s say we are parsing an error but that the error can take a number of shapes. It can be a string or an object containing a list of strings. A potential solution might look something like this:

function getAllErrors(error = {}) {
  if (typeof error === 'string') return [error];
  if (typeof error === 'object') return error.errors;

  return [];
}

This looks good at first glance, we take in an error, check it’s types and if it matches what we want we return it, otherwise we return an empty list. However there is an bug here, if error is passed as null it will fail the first if statement but pass the later.

because of course typeof null === 'object' ….

Obviously that is not what we want. Luckily Static Typing will catch this error. Let’s start by writing the types (something you should always do first).

type ErrorMessage = string;

interface Error {
  errors: Array<ErrorMessage>
}

type PotentialError = any | ErrorMessage | Error;

Ok now we have a good idea what the shape of our data structures will be and we can express the intent of our function more clearly.

function getAllErrors(error: PotentialError): Array<ErrorMessage> {
  if (isErrorMessage(error)) return [error];
  if (isError(error)) return error.errors;

  return [];
}

Much nicer! But wait! What are those new functions? isErrorMessage and isError? Well those are type guards. They allow you to tell the typescript compiler what type is being returned. So for instance the isError type guard could look like this:

function isError(error: PotentialError): error is Error {
  return 'errors' in error;
}

And now that the compiler knows the type of the error, if we tried to change the return statement to return a parameter not in the Error interface or return the first index of errors.errors like below our compiler will tell us.

if (isError(error)) return error.errors[0];
//                               ^
//                               |
// Type string is not assignable to type string[]

This is a big win for maintainability because we know exactly what to expect from functions we have written and more importantly ones we didn't.

Documentation

Notice as well how clear the implementation of our example function is now. Previously, since this is a utility function meant for usage throughout the application, I would have written a set of comments like the following:

/* @method getAllErrors/1
 * @return List(Object)
 *
 * If it is a simple error (a
 * string) then that will be returned as
 * the expected return type.
 *
 * If a list of errors are found within
 * the object they will be returned.
 *
 * If it is not a string or an object we
 * will return an empty list.
 */
function getAllErrors(error = {}) {
  if (typeof error === 'string') return [error];
  if (typeof error === 'object') return error.errors;

  return [];
}

As the application becomes more complex I would consider this type of information to be the bare minimum required (more on that in a minute). Knowing the return types and the types of parameter a function accepts will let us both avoid issues when using the function and create a clear boundary within which we can refactor the function itself.

Now if we consider the same Typescript code, it’s obvious these comments are no longer required.

function getAllErrors(error: PotentialError): Array<ErrorMessage> {

More than that these types will have to stay up to date as we refactor (a big problem with regular comments) and they will give us extra information through compiler warnings and editor tools. I did say this was the bar minimum information required though so I will touch on that briefly.

Typescript gives us the types to answer the what of a function but not the why. For very simple functions just the name of the function is enough but sometimes a function will be quite complex, have a limited scope or have side effects. These things should still be recorded within the functions documentation. Otherwise we can’t know when to use a function or more importantly when not too.

In the case where documentation is still required (the why of a function is complex) the Typescript eco-system provides TsDoc. This is a standard way of writing documentation that also works with tooling such as the vscode editor.

Tooling

Another benefit of Typescript is its excellent editor integration, especially with VsCode where it offers intellisense, tools for refactoring, debugging, linting, documentation and formatting. All of these things will be surfaced by your editor and the compiler.

For Vim users check out tsuquyomi to get a similar set of tools

A Superset

Maybe Typescripts biggest feature and without question one of the biggest reasons for its growth. It’s a superset of javascript, which means that any javascript is also valid typescript. This makes becoming a typescript developer as easy as re-naming your .js files to .ts.

From there you can gradually type more and more of the code and make the compiler stricter until your whole codebase (or whatever amount you want) is fully written with Typescript in mind. This is huge for existing projects that don’t want to start all over again but still want the benefits of a typed language.

Note you will need to configure some sort of build pipeline but I’m considering that as separate

The Bad

Breaking Changes

Unfortunately Typescript does not strictly follow semver, something we take for granted within the Ember eco-system. Due to marketing pressure breaking changes are introduced through minor versions, though they do maintain some semblance of semver after that. A helpful diagram/comment from niieani shows how we should approach this.

       marketing
           ∨
TypeScript 2.34.2.1
             ∧∧ ∧ ∧
          major ∧ patch
                ∧
              minor

This is a problem in an eco-system that expects things to follow server and not make breaking changes on minor releases. But it surfaces a bigger problem. Besides Ember itself (though this applies to all frameworks), Typescript has the potential to require the largest refactors of your codebase.

Although unlikely, any fundamental changes to Typescript will have a knock on effect to your codebase and potentially a large swath of it. This makes the lack of semver even more concerning and is something that must be considered carefully before diving straight in.

Conventions & Expertise

Another consideration which I think is often glossed over is conventions and the expertise of your team. Sure Typescript is a super set of javascript but that doesn’t mean your team is positioned to take advantage of that. For instance, a question that arises from our previous example.

Should the types we declared above exist within a global types file?

How would you answer this question? I can definitely see the PotentialError type being used elsewhere in the application and Typescript offers us a way of declaring a global type within a project.

It sounds reasonable and useful, however my answer would be:

No. They are too specific, any global Error type would have to be far more generic. These types are specific to the structures expected by the functions within the file. At best they could be some sub-type of a broader type within the global types namespace.

I am lucky to have worked with a variety of different languages and frameworks from early in my career that includes both typed and non-typed languages. But not all teams have that kind of experience and coming from a Javascript background it will be important to make sure your team has the expertise they need to make the right decisions. Otherwise you can create one hell of a mess.

Missing Typings

Unfortunately not every library comes with a set of types fresh out of the oven. As a result you may run into issues where common libraries don’t have types. “Sure no problem, it’s a superset, it will still work” I hear you say.

While true the Typescript compiler & tools are able to strut their stuff best when the configuration is stricter. This will lead to errors & warnings when attempting to compile code that does not have types or at the least no type safety, which kind of defeats the point.

Now there are great projects such as DefinitelyTyped which provides a huge library of type definitions but even then common libraries such as ember-concurrency and Ember Data Storefront do not have types. This means either adding your own types though a .d.ts (a type definitions file) or compromising on the type safety you are supposed to rely on.

Transitioning To Typescript

So you’ve got this far and you’re undeterred, well then let’s outline a simple method of transitioning your existing Ember application to use Typescript.

Firstly we will install the excellent project ember-cli-typescript which will take care of building & converting our typescript files for us. This is the simplest way of setting up Typescript but it does have limitations that we should be aware of.

As for typing the application itself Mike North recommends the following steps:

Start with allowing implicit anys and just rename all .js files to .ts
Add as much type info as possible without going into detail. Opt for explicit any. Ban implicit any
Go into detail at certain, commonly used, modules (services, models etc)

By following these steps we can convert our whole application to typescript without interfering with other members of the team or preventing feature work.

And there you have it, Typescript in Ember with minimum fuss!

Ember Two Years On

James Byrne — Sat, 07 Jul 2018 21:30:02 +0000

A Retrospective

I’ve been programming professionally for a little over two years now. The majority of my time has been spent using Elixir, Erlang, Ruby on Rails and EmberJs with a brief stint of contracting with Angular 4 thrown in.

Ergo I thought with my new found knowledge why not write some of it down so people on the internet could tell me I’m wrong! ....... wait.

What I like about ember

Out of the box

Embers convention over configuration setup (the cool kids call this Zero-Config now) allows you to get up and running with your new project in the time it takes to run yarn/npm install. Which is anytime between now and the heat death of the universe, but you get my point.

This is really great for experimenting since you don’t need to spend any time on setup, just get working. With bigger projects you get the same benefit but, with the confidence that your project will scale over time.

Solid Development Experience

One of the things I love about Ember is the development experience. Over the last two years I have learned alot! Part of this has been how to best utilise the languages, patterns and frameworks at my disposal.

With Ember I’ve learned how to use the conventions and where I can lean on the framework to do the heavy lifting for me. This means I spend less time bike shedding and more time being productive. But the best part is that I am still seeing these results two years on. Partly due to the ecosystems growth in that time and partly due to a better mastery of existing tools.

The much loved ember-concurrency addon is a great example of this. Being new I wrote a lot of mixed synchronous/asynchronous state management code that turned out to be hard to manage and inflexible (sue me :P). Over the last year when working on smaller apps I have learned how to massively simplify managing state across an ember application using ember-concurrency tasks (generator functions).

As a result this new code is easier to test, maintain, change and most importantly, it’s simple. Something which is often overlooked in application design and programming but which is vitally important.

Community

The Ember community is awesome, simple as that. Both the core team and the community at large are extremely friendly and there is a real spirit around the project. It’s not driven by one of the big corporations or by a single person but rather the collective passion of the commun-. Ohh that was close, if I said the "comm" word three times Jono Bacon might appear.

The PWA Story

Now this is easily the thing I am most excited about. Ember has a number of really cool addons such as ember-service-worker, ember-cli-concat and ember-cli-critical that make creating Progressive Web Apps much much easier. Dockyard has made a great post showing just how easy it is to upgrade a standard app into a PWA.

And it doesn’t stop there, both ember-pouch and ember-orbit create a compelling story for apps that need to allow collaboration and creation while still offline and sync changes once a connection is re-established. A keen interest for me.

This is something I am really excited about and I can’t wait to see what the state of Progressive Web Apps will look like in the future. shakes fist at safari & iOS

Things I don’t like

So here’s the rub, there are not many things I dislike about Ember itself. I am a big believer of the right tool for the job mentality. As a result I don’t have many complaints, because the problem isn’t an issue with Ember it’s just not the right tool for the job I want to complete. For instance, if I wasn’t building a Single Page App, I wouldn’t choose Ember. Is that a bad thing? No, it’s just not the right tool. And saying that a framework should be able to do everything is like saying a language should be able to do the same. It’s a fools errand.

As a result I find the things I am not impressed with are not issues with Ember per say, but rather things I wish Javascript had. For instance I am really looking forward to having better Typescript support in Ember. My brief foray back into the Angular world (note to self: don’t mention the war) allowed me to experiment with Typescript in a real world project and I found it very useful in practice.

I would also love for functional programming to become more widely used within the Ember ecosystem, but unfortunately the trend seems to be going in the other direction. Which again, is not a bad thing, just the way the tool works.

Closing comments

Overall I have really enjoyed my time with Ember. Compared to the other frameworks, libraries and languages I have tried, Ember has struck a cord with me in both the values it maintains and the practical benefits it boasts. Looking forward I am excited to see what comes next for Ember and how it will help me deliver value for my users.

P.S. Also have you seen the mascots? They are awesome!