Publishing my own CSS utility library on NPM

I'm writing this because this is something I find myself creating and re-creating and re-creating every time I start a new side project.

I just wanted a set of simple CSS utility classes based on a few sets of SCSS variables.

Something like this:

$spacing: (
  'xs': 0.25rem,
  'sm': 0.5rem,
  'md': 1rem,
  'lg': 2rem,
  'xl': 4rem,
);

@each $key, $value in $spacing {
  .m-#{$key} {
    margin: $value;
  }
  .p-#{$key} {
    padding: $value;
  }
}

$colors: (
  "black": rgb(33, 33, 33),
  "black-75": rgba(33, 33, 33, 0.75),
  "black-50": rgba(33, 33, 33, 0.5),
  "black-25": rgba(33, 33, 33, 0.25),
  "white": rgb(247, 247, 247),
  "white-75": rgba(247, 247, 247, 0.75),
  "white-50": rgba(247, 247, 247, 0.5),
  "white-25": rgba(247, 247, 247, 0.25),
);

@each $key, $value in $colors {
  .color-#{$key} {
    color: $value;
  }
  .background-#{$key} {
    background-color: $value;
  }
}

...which makes available classes like...

.m-sm { margin: 1rem; }
...
.pb-lg { padding-bottom: 2rem; } 
...
.color-black { color: rgb(33, 33, 33); }
...

I haven't jumped on the Tailwind train just yet. I've used Tachyons, but even that feels like more than I need, and my brain prefers the class names to be slightly more verbose.

I don't need much — usually just colors, spacing, and breakpoints. Things like m-<size> for margin: <size>; and background-<color> for background-color: <color>;.

I liked the idea of maintaining my own little design-system-like-thing that I can pull into projects to set a baseline that I'm super familiar with. And I was pleasantly surprised with how easy it was to accomplish!

The following is a walkthrough of the steps I followed to publish my package, @evanwinter/styles.

They are specific to publishing a scoped and public npm package, where the source code is written in SCSS.

Write your code

For a bare minimum example, create a folder called css-utilities or whatever you wanna call it.

Create a file called index.scss and put some code like the SCSS code above into it.

Create a package.json

Run the following code, replacing "" with your actual npm username.

For example, this was npm init --scope=@evanwinter for me because my username is "evanwinter".

npm init --scope=@<your-npm-username>

Follow the prompts, naming your package @<your-npm-username>/css-utilities (or whatever you named your folder, or really whatever you wanna name it).

The entry point ("main" in package.json) should point to your index.scss file — the "root" file of your project.

Add sass dependency

To compile your SCSS into CSS, install the sass package from NPM as a devDependency:

npm install -D sass

In your package.json, update the "scripts" entry to look like this:

...
"scripts": {
  "build": "sass index.scss dist/index.css --style=compressed"
},
...

This means when npm run build runs, it will convert index.scss into a CSS file and place it at dist/index.css.

Run a build

Run the following:

npm run build

You should now see a dist/ folder created, with an index.css file inside it, containing a compressed CSS version of your original index.scss file.

Publish it!

Now you'll just need to log in to npm from your terminal, like so:

npm login

Go to the URL it gives you, and log in to your npm account.

Then, if successful, return to your terminal and run the following to publish it:

npm publish --access public

And that's it!

Use it in another project

To use the CSS classes generated by your new utility library, simply import the library in a CSS file.

For example:

// my-project/index.scss
@import "@evanwinter/styles";

...
<p class="m-xs">Hello world</p>
...