Forem: Daniel Del Core

A new way to ship Codemods

Daniel Del Core — Mon, 15 Aug 2022 01:39:02 +0000

A little under two years ago, my team was preparing for our first performance refactor of our Design System. Our plans to maximise performance gains were predicated on removing deprecated API, which had slowly accumulated over the years, now representing a substantial amount of bloat and code duplication. Worryingly, doing so would mean an unprecedented amount of breaking changes at a time when adoption and stability were a huge pain point for our consumers. Automated migration seemed like the only feasible way forward…

Like most popular libraries, e.g. React, Next.js and more, which provide codemods to help move their huge user base across versions, we needed a bespoke and fairly simple CLI wrapper of jscodeshift, that would provide a means of publishing, downloading and running codemods. So we created a custom 'codemod-cli', our first piece of internal codemod infrastructure.

We had already written a few codemods to help with some internal migrations. These were in the form of standalone transform files co-located with the packages they served but were one-offs which were written, run and forgotten about since the work was done and no longer necessary. This is not unlike what React and Next.js provide, unstructured but at times unclear as to when and why a codemod should be used. This is where we saw our first opportunity:

What if every breaking change was paired with a versioned codemod?

In this model, every breaking change would be accompanied by a codemod, the name of the codemod would point to the version which it targeted button-v2.0.0 so its intent was clear to the user. What’s more, once we accumulate codemods for multiple major versions, it would be possible for users lagging many versions behind to be slingshotted to the latest code by running all available codemods in sequence.

With this paradigm in place and the functionality implemented in the codemod-cli, we were at a point where we needed to put tools down. We needed to get back to the project we originally set out to complete, improving performance. It was now on us to start putting it to the test by writing and publishing codemods for our breaking changes. But now with the ability to actually change APIs that had been holding us back for years. To keep this short, I’ll skip over the next year or so by just saying: It worked! We wrote loads of codemods, they ran and they certainly did what we originally intended – Yay!

However, I walked away from that project with a lot of unfinished business, I felt that there were many more uncapitalised opportunities in this space. So I did what no other engineer has done before me, I started a side-project… 😅. With more and more Design Systems and convergence toward multi-package repositories, I feel like it’s the right time to share what I’ve been up to in the hope that it might also help folks in a similar situation to us.

🚚 CodeshiftCommunity

First and foremost, If the project was nothing else, it would simply be a docs site representing our collective codemod authoring knowledge. This is obviously a huge gap and barrier to entry for newcomers to jscodeshift. An onboarding experience that is quite intimidating, pieced together by various examples and blog posts.

Secondly, the strategy of codemods targeting specific versions of a package seemed strikingly similar to that of DefinitelyTyped, versioned artifacts (ts type definitions) supporting a package across its lifecycle. What if we could provide similar facilities to act as a single place where codemods could be distributed, documented and maintained in a controlled and structured way?

Thirdly, everyone using jscodeshift, including ourselves, is likely to be also writing/maintaining a bespoke CLI to solve this problem. We would need to tie everything together into a single and familiar CLI tool.

Lastly, my main objective and what I’m currently working on is to: Provide a renovate-like bot that can not only version bump, but also automatically migrate code across major versions and prompt maintainers to either merge on green CI or give them clear call-outs for their intervention in case a codemod can’t migrate them all the way.

How it works

Generally speaking, the library works by publishing every codemod to npm as its own package or piggybacking off an existing NPM package. Our CLI can then download and run them from anywhere. With the hidden benefit of being able to publish codemods with dependencies, currently, something that isn’t possible with vanilla jscodeshift CLI implementations.

Using NPM drastically lowers the adoption bar since all one would need to do is publish their existing package paired with a codemod.config.js, which is effectively a file that holds the names and locations of codemods. In existing npm packages, simply adding this file would be all that is necessary to adopt Codeshift, no dependency is required.

For example:

export.module = {
  transforms: { // Versioned transforms
    '12.0.0': require.resolve('./18.0.0/transform'),
    '13.0.0': require.resolve('./19.0.0/transform'),
  },
  presets: { // Generic utility transforms
    'format-imports': require.resolve('./format-imports/transform')
  }
};

Running the above codemod now is a simple matter of referencing the package name and version.

Let’s for a moment say this config exists within the @chakra/button package. Assuming the config and codemods are published to NPM, one could run:

$ codeshift -p @chakra/button@12.0.0 path/to/src

Codeshift will download the latest version of @chakra/button locally, ensuring we always have the most up-to-date codemods. The CLI would read the config and pass that to jscodeshift where normal transformation would take place.

Passing the --sequence flag will trigger a run of both v12 and v13, one after the other.

The presets config, is a place for “generic” or “non-version specific” codemods, which relate to @chakra/button. This is potentially where one might want to share codemods like, format-imports which would, for example, format button imports into a certain order. Running one looks like:

$ codeshift -p @chakra/button#format-imports path/to/src

How you adopt Codeshift is up to you

You can contribute to the public registry

Augment existing packages with codemods to make them available to via the @codeshift/cli.

Or create your own private codemod registry, utilising the same docs, best practices and structured API whilst being fully compatible the community.

See the authoring guide for more info.

What next?

The overarching goal is to lower the barrier to entry so that the JS ecosystem as a whole could leverage these resources and community and in turn generate codemod coverage for libraries that we depend on, in the same way we consume type definitions from DefinitelyTyped. The idea is that developers will eventually be able to leverage codemods the community collectively provide, simplifying migration for core dependencies (react, redux, next, emotion, jest, etc). A lofty goal, but consider if existing ecosystem codemods were to integrate with the library.

The only barrier to entry for them is providing a configuration file and using the @codeshift/cli, which can be safely done alongside existing infrastructure. Once published to NPM our build tooling and consumers can run these codemods from anywhere.

Ultimately and more importantly consolidating efforts in the space into a structured library serves the broader JS ecosystem.

If you’re interested or want to learn more please feel free to browse the docs: CodeshiftCommunity.

CSS-in-JS: What happened to readability?

Daniel Del Core — Fri, 06 Nov 2020 07:07:19 +0000

When I first started using BEM (block-element-modifier) early in my career, I distinctly remember how refreshing it was to have a system to name and assign semantic meaning to our otherwise esoteric CSS blocks. Almost immediately (once I understood the rules) it became easy to glance at some CSS and visualise the changes that will be applied to elements in their various states. Love it or hate it, something about its simple underlying principles stuck with me.

It looked something like this…

.my-button { }
.my-button.my-button__icon { }
.my-button.my-button--primary { }

Nowadays, most of us are using CSS-in-JS libraries like styled-components or emotion (which are fantastic libraries btw), but all of a sudden it seems like we forgot about the helpful methodologies we learned with BEM, OOCSS and SMACSS. As a result CSS-in-JS that you encounter in the wild is hard to read and reason about.

You might be familiar with seeing code like this:

styled.button`
 background: ${props => props.primary ? "you" : "didn't"}
 color: ${props => props.primary ? "read" : "this"};
 font-size: 1em;
 margin: 1em;
`;

In this case, properties for the primary modifier are computed individually, carrying an implicit runtime cost, which scales poorly as more modifiers are eventually added. More importantly, this carries substantial cognitive overhead for future maintainers, trying to understand how and when properties are being applied. A point proven by the fact that you probably didn’t read that code block at all (Check again 😉).

Now you’re the next developer to come along and attempt to add a disabled state to this button. You might be inclined to continue this pattern and do something like this…

function getBackgroundColor(props) {
 if (props.disabled) return 'grey';
 if (props.primary) return 'blue'; 
 return 'white';
}
function getColor(props) {
 if (props.disabled) return 'darkgrey';
 if (props.primary) return 'white'; 
 return 'black';
}
styled.button`
 background: ${getBackgroundColor};
 color: ${getColor};
 font-size: 1em;
 margin: 1em;
`;

But this only further exacerbates the problem by creating yet another layer of indirection.. OH NO 😱 Not only do you have to compute this function in your head, you now have to locate these helpers 🤯

For better or worse styled-components is totally unopinionated about these things, if you’re not careful you might inadvertently allow bad practices to propagate through your components. Sure, you could BEM-ify this code in styled-components, but my point is that you’re not forced to by the API. Even so, BEM-like methodologies are no better because they’re merely a set of rules and rules are great only until someone breaks them 👮‍♂️!

CSS-in-JS actually provides the perfect opportunity for an API abstraction to solve this very problem 🎉 by abstracting away the messy details of a methodology and leaving you and your colleagues with a library that guards you from these implicit issues.

This was my motivation to build Trousers 👖 (v4 coming soon)

😅

but I’m not the only one thinking about this! New libraries like Stitches are popping up all over the place, taking a similar approach to shepherding users into using good patterns through API design. Leaving us with the best of both worlds!

Trousers as an example provides grouped properties via modifiers…

import css from '@trousers/core';
const styles = css('button', { backgroundColor: 'blue' })
  .modifier('primary', { backgroundColor: 'white'})
  .modifier('disabled', { backgroundColor: 'grey' });

Named modifiers controlled via props…

/* @jsx jsx */
import css from '@trousers/core';
import jsx from '@trousers/react';
const styles = css('button', { backgroundColor: 'blue' })
  .modifier('primary', { backgroundColor: 'white'})
  .modifier('disabled', { backgroundColor: 'grey' });
const CustomButton = (props) => (
  <button 
    css={styles}
    $primary={props.isPrimary}
    $disabled={props.isDisabled} 
  />
);

Themes as css variables, allowing for even less dynamic css and runtime cost.

css('button', { backgroundColor: 'blue' })
  .modifier('primary', { backgroundColor: 'var(--color-primary)' })
  .theme({ color: { primary: 'red' });

And all of the examples above will only ever mount 1 + number of modifiers, regardless of component state and active theme.

All possible because CSS-in-JS provides us with layer of abstraction to do this work!

So my ask for you to takeaway from this blog is not to necessarily use my library, but start to think the cognitive science behind how we write CSS-in-JS today and how you can start incorporate these principles into your apps and libraries in the future to improve the readability and maintainability of your code!

Quick aside: Trousers is simply standing on the shoulders of other great libraries, so full credit to the people and libraries that inspired it!

Please do yourself a favour and checkout these fantastic libraries if you haven’t already:

Thanks for reading 👋

Learnings from migrating Atlaskit to TypeScript

Daniel Del Core — Thu, 22 Oct 2020 06:13:52 +0000

This blog is aimed at people who are considering migrating their large projects to TypeScript!

So TypeScript support has recently landed in Atlaskit 🎉 and what a journey it was! I think now is a good time to reflect on what I found worked and what I would do if I was to do it all over again.

Full disclosure: It was a large and challenging undertaking… but one I would encourage regardless!

Our project

In the spirit of transparency, I'd like to share some rough resource numbers, to give you an idea of what you might be in for.

We had roughly ~10 different engineers working on the project over its lifespan. At the start, we had 5 people working on it full-time. This is where we made most of our progress. But as time went on, naturally people were pulled into other, more important initiatives and so about halfway through and we dropped back to 1 to 2 full-time engineers at best, for the remainder of the project.

It's important to note that we were also juggling other priorities such as support, bugs, other projects, etc.

The whole effort spanned *~6 months all up.

Tip #1: Automate everything 🤖

I can't stress this enough, use or build your own automation to do the tedious bits. You'll likely never get something that converts perfectly, but you can get most of the way there.

This worked for us: alexreardon/sink

It automated:

Transformed our already type-safe flow code and converted whatever syntax it could into TypeScript
It renamed files from .js to .ts & .tsx (surprisingly tedious)
Added TS specific configuration files
Removed old configuration files

Sink is highly Atlaskit specific, but consider taking a similar approach. You wont regret it 😉!

In hindsight I wish we invested more time in automating our conversion. If I was to do it again today, I would definitely investigate an AST based approach.

But still definitely worth the upfront effort!

Tip #2: Do not refactor AND convert to TypeScript 🔥

It is really tempting to refactor code as you go, but you must resist the urge to clean up code while you're migrating at all costs!

When you're migrating you'll look at every line of code critically. You're bound to find things that bother you. But it's important to resist because the risk of introducing a regression is extremely high and there is a strong chance that you or your PR reviewers will miss issues. Think about it, you're touching a lot of files, your PR diff is already cluttered with deltas, and then introducing logic changes on top of that - A recipe for disaster🔥.

Trust me on this one 😅

Just focus on moving from one working state to the next. If you need to refactor your component it should be a separate activity all together. Make a note or Jira ticket somewhere, do it later.

Tip #3: Enable allowJs 🌲

allowjs: Allow JavaScript files to be compiled.

If your codebase is big, do yourself a favor and enable allowJs so you can progressively convert components file-by-file, instead of doing an entire component at a time, which is what we did 😆. I found that it blew-out the size of the PRs and made getting past CI a real pain in the butt 🍑.

Tip #4: Capture the Gotchas 🗒

Keep a list of rules / best practices to govern the team. There are lots of little scenarios that happen over and over such as:

Which event handler do I use for this prop? How do I type HOCs? When should I use an interface over a type? Should I export my props?

Form these opinions as a team, share resources, discuss together and document it for later use.

Here are some resources we used…

Absolute god-send: typescript-cheatsheets/react

You might also find these useful:

Tip #5: Go upwards from the leaf nodes 🍂

This should be a no-brainer: Start with the most simple and dependency-free components you have and move up and up the tree until you're finished.

Tip #6: Beware the HOC 🐲

In our conversion the most challenging obstacle to overcome, by far, was successfully typing a HOC (higher order component). Handle these with the most care, because it's possible that the return type of a HOC can be incorrectly typed.

It's worth noting here that HOCs come in different flavors and the way you approach typing them varies slightly. If you get stuck check out these guides:

Closing thoughts 🙏

Don't let this blog discourage you, it was totally worth every second of the effort in my eyes. We found countless bugs in the process, we learned a lot about the quality of our components and in general feel like we're walking away with an a lot more stable codebase!

An approach to theming Design Systems

Daniel Del Core — Tue, 29 Sep 2020 01:41:16 +0000

To create a theme that will scale with the needs of your organisation, you must first choose the set of rules and principles that contribute to a scalable, flexible and sane theming solution. These rules need to be incorporated into a specification which will eventually need to be supported as a first-class API contract between your Design System and consumers.

A theme can be thought of as a set of variables or 'global tokens' that are applied globally to your components. Containing all of the colours, spacing units and typography rules. Together they define how your components look and feel (not their behaviour). Allowing you to provide tailored and accessible experiences via dark mode, high contrast mode and more.

Themes need to conform to some form of 'Theme specification', a schema which describes the structure, naming conventions, properties, data types, and scales of our theme. The definition of this schema carries hidden long-term implications, so it's important to define these rules with care. Let's walk through a some solutions you can put in place to navigate these complexities.

Theming is not the silver bullet for customisation

Firstly, I want to call out that customisation is tricky. There are many ways to achieve it and all come with a healthy amount of pros and cons. It's a matter of using the right tool for the job. Global Theming is no exception, it's a great tool for rapidly and consistently effect change to colours and spacing and seeing immediate results, but it does not have any way to express component behaviour. Nor should it be expected to turn your Design System into a completely white-label suite of components. There are just too many tiny decisions baked into every aspect modern components, it would simply be next to impossible to control every case.

Instead, think of a theme as the broad brushstrokes of customisation. Almost always used alongside other techniques such as Props, Composition, Overrides, CSS hacks etc.

Setting the expectations of what theming is and what it is not is important to ensure the solution isn’t carrying too much of a burden, which is often followed by degraded performance and increased cognitive overhead. In short, doing less is always best (ha).

Most Design Systems offer multiple avenues for customisation, but the decision making should be in the hands of users to choose the right approach for them.

Themes are a reflection of UI anatomy

Consider the following example of a theme:

// theme.js
export default {
  colors: {
    transparent: "transparent",
    black: "#000",
    white: "#fff",
    gray: {
      light: "#eeeeee",
      dark: "#202633",
    },
  },
};

Each colour defined here describes a value not a destination. What if you want to invert black and white in your UI to create a dark theme? You might naively switch the values, but then quickly realise that the names become a lie. Black is white and white is black.

Moreover, consumers of the theme might be using these colours in different ways. gray.light might be a great background colour to one developer, but also might already be used as a background by secondary buttons. Eventually, someone will want to tweak the theme’s background colour (gray.light) which might then break colour contrast for secondary buttons. There’s nothing stopping these values from being inadvertently mixed up, causing wide-reaching issues. Remember we are operating in the global scope 🌏.

Similar to how every ridge, bump and groove of a human skeleton 💀 has been analysed, named and catalogued, so should every facet of our UI “anatomy”, if you will. That catalogue is the Theme, which describes the relationship between spacing, colours, focus rings, typography, etc have with the particular ridges and grooves of our UI, Buttons, Navigation, Forms...

So with that in mind, the theme above might be better represented in the form:

// theme.js
export default {
  colors: {
    typography: {
      body: '#000',
      heading: '#393939',
      anchor: '#439dfa',
    },
    background: {
      body: '#eee',
      aside: '#e2e8f0',
      footer: '#e2e8f0',      
    }
  },
};

As you can see some of the primary elements of the Holy grail are listed here. These concepts are abstract in meaning and don’t refer to any specific component, they are simply parts of a typical webpage’s anatomy that you, the designer or developer, are already familiar with. These “concepts” are what I believe is the key to encoding semantic and contextual meaning into a theme.

Theme properties should have contextual & semantic meaning

Through describing where properties are intended to be used, rather than the value they hold, via abstract concepts, users of the theme should find it intuitive and easy to use the correct properties in the correct place.

Given the examples above, consider a user wants to ensure some text on the page is using the correct typography colour, the structure and naming of the theme describes to them the best fit.

Before:

const CustomHeading = styled.h1`
  font-size: 3rem;
  color: ${(theme) => theme.colors.black};
`;

After:

const CustomHeading = styled.h1`
  font-size: 3rem;
  color: ${theme => theme.colors.typography.heading};
`;

Hierarchy integrates our intention for each theme property into the structure of the theme. It’s clear that for typography colours, it’s probably best to use color.typography.element and so, if I decide to use a background colour to style some text, I’m probably doing something wrong and it's going to be prone to breaking sometime in the future.

It’s also worth noting that Material-UI already does a great job of using hierarchy to group properties into significant elements.

Values making up the theme should be restricted to ‘Brand Tokens'

Values that populate our theme should be limited to the set of 'Brand Tokens' for use within your organisation, so whichever combination of values selected from these tokens, the end result will still be distinctly on brand.

Not all brand tokens need to be in use for any given theme. They’re just the available “pool” of options for you to choose from. For extreme use-cases it’s still possible to substitute your own values.

Again, taking the example from above, moving the values into ‘Brand tokens’ allows us to apply colours consistently without picking arbitrary values.

// tokens.js
const neutral50 = '#eee';
const neutral100 = '#e2e8f0';
const neutral500 = '#393939';
const neutral600 = '#000';

const blue100 = '#439dfa';
const blue200 = '#439ddd';

// theme.js
export default {
  colors: {
    typography: {
      body: neutral600,
      heading: neutral500,
      anchor: blue100,
    },
    background: {
      body: neutral50,
      aside: neutral100,
      footer: neutral100,      
    }
  },
};

In a dark mode theme, you could simply replace the lighter tokens with darker ones whilst still conforming to your Brand.

// theme-dark-mode.js
export default {
  colors: {
    typography: {
      body: neutral50,
      heading: neutral50,
      anchors: blue200,
    },
    background: {
      body: neutral600,
      aside: neutral500,
      footer: neutral600,      
    }
  },
};

Scales need to defined and consistently applied

If I use T-shirt sizing can I scale it to suit my needs in the future? Will an array carry enough semantics for others to understand? How can I describe progression of colour?

No doubt you’ve already done these mental gymnastics when trying to rationalise a scale or a group of related values. Choosing the right scales can be hard. They need to be consistent, flexible and hold some form of semantic value. The right system also needs to be paired with the right type of value, e.g. T-Shirt sizes can’t describe colours. It’s a tricky problem and it imposes a large obstacle to the flexibility and longevity of your theme.

As you would expect there has already been plenty of thought on this, so i’ll point you to this wonderful blog incase you wanted to go into more detail.

I’ve seen a handful of scales used in themes in the wild, here are a few popular ones:

T-Shirt sizing: xxs, xs, s, m, l,xl, xxl, xxxl, xxxxl
Arrays: fontSizes: [14, 16, 18, 24, 32]
Enumeration: b100, b200, b300
Degrees of x: lighter, light, lightest, lightestest…

Like everything, all have pros & cons, but to offer up an alternate opinion. What if we could extend on the thinking above and use that same thought process to side step the scales conversation?

Consider spacing, you have an obvious set of options for defining a scale of spaces, you might use an array or T-Shirt sizes. But those values are still subjective, some people might use space.m where others use space.s it’s still largely open to interpretation. What if every value in the spacing scale had a finite set of use-cases and those use-cases could be encoded into the name, the same way we did with colours above?

Stealing an image from this blog by Nathan Curtis (definitely worth a read).

We could use those concepts to define a new spacing scale:

// tokens.js
const space50 = '0.5rem';
const space100 = '1rem';
const space200 = '2rem';
const space300 = '3rem';
const space400 = '4rem';
const space500 = '5rem';

// theme.js
export default {
  colors: {...},
  space: {
   inset: space200,
   inline: space50,
   squishedInset: `${space100} ${space50}`,
   stack: space400
  }
};

Now when choosing a spacing value for a new container component, we can take the guesswork out of the process, since we know that space.inset is primarily used for padding the inside of containing elements.

Most collaborators can’t see space, a primary reason it’s so arbitrarily applied. But now we’ve got a system: a limited number of concepts, each offering a limited range of options.

But weight (hehe get it?) there’s more, since one inset is never going to be enough, now is the perfect time to introduce a scale to provide more granular control within the safe boundaries of a meaningful naming convention.

// tokens.js
const space50 = '0.5rem';
const space100 = '1rem';
const space200 = '2rem';
const space300 = '3rem';
const space400 = '4rem';
const space500 = '5rem';

// theme.js
export default {
  colors: {...},
  space: {
   inset: {
    default: space200,
    small: space50,
    medium: space300,
    large: space400,
   },
   ...
  }
};

In this way, the spacing scale is not as inclined to grow organically into a huge unmanageable array of values as new values are eventually added, making the system more resilient to change over time.

A Theme’s concepts should be well documented

Lastly, it is not enough to have a great theme, it needs good documentation because when used incorrectly it has the potential to destroy its value and lock API maintainers into a lifetime of breaking changes and workarounds.

With all of these abstract concepts in place like “scales”, “inset”, “squish”, “token”, there needs to be a somewhere people can go to make sense of it all. So again, i’ll point you to this blog:

Teach your spatial concepts using a tight doc diagram or cheat sheet. Such references quicken how we grasp, apply, and sustain the concepts through design and code.

And better yet, visual prototyping tools can bring the docs to life by giving users a feel for what they’re changing as they’re changing it. And the ability alter UI in broad brushstrokes 🖌.

The ecosystem has already made a headstart on this:

With good documentation in place, a greater overall understanding of how the theme should be used can form within your organisation. Future changes to the theme, as it grows organically overtime, fit into the already understood frameworks and paradigms we’ve defined (and documented). New themes can be designed, published and shared easily between products, teams and users. And limitations of a theme for customisation purposes become more apparent, prompting people to take more appropriate avenues to customisation problems they’re trying to solve.

Thanks for coming 👋

There are many ways to skin the big fat theming cat 😺, so treat this blog as merely a set of observations and ideas you could potentially incorporate into your Design System.

Please feel free to post your ideas and opinions below, i’d love to hear them!