Deadfire

A lightweight CSS preprocessor.

Use plain ol' CSS with a little bit of @import and @apply.

CSS is a staple technology when building web applications. With the introduction of LESS, SASS, SCSS it made CSS easier to maintain. However, most of these tools are no longer supported, maintained or have far too many features (wait... that's a bad thing?).

Deadfire sprinkles a few extra features which helps you write CSS, easier.

Deadfire can be used with or without a CSS framework.

Features

• @import
• @apply

@import

Imports allow you to easily include a file from the file system into your current css document.

/* shared/buttons.css */
.button {
  color: red;
  text-align: center;
}

/* application.css */
@import "shared/buttons.css";

.page-title {
  font-size: 20px;
}

Output;

/* application.css */
.button {
  color: red;
  text-align: center;
}

.page-title {
  font-size: 20px;
}

@apply

The @apply directive inlines your classes into your custom CSS, simplifying the process of applying existing styles to a new class.

The CSS apply rule was proposed to be included into CSS however it was abandoned. Mixins simplify applying existing css to a new class.

Let's take a look at an example of how to use the @apply directive. Note that all utility classes are automatically cached.

.font-bold: {
  font-weight: bold;
}

.btn: {
  padding-bottom: 10px;
  text-align: center;
}

Re-use the styles using @apply:

.btn-blue {
  @apply .btn .font-bold;
}

.homepage-hero {
  @apply .font-bold;
}

Fault tolerant

When Deadfire encounters an error, such as a missing mixin or other issues, it does not raise an error that would halt the execution. Instead, it continues processing the CSS code and collects the encountered errors. These errors are then reported through the ErrorReporter class, allowing you to handle or display them as needed.

By adopting this fault-tolerant approach, Deadfire aims to provide more flexibility and resilience when dealing with CSS code that may contain errors or inconsistencies. It allows you to gather information about the encountered issues and take appropriate actions based on the reported errors.

Installation

Add this line to your application's Gemfile:

gem 'deadfire'

And then execute:

> bundle install

Or install it yourself as:

> gem install deadfire

Ruby on Rails

Deadfire aims to work alongside the new asset pipeline, Propshaft.

With the gem included in your app's Gemfile, by default all your css files will be pre-processed.

For more control over the files you want to pre-process;

Deadfire.configuration.root_path - change the root path where files are processed e.g. tailwind is bundled into app/assets/builds/tailwind.css which means the root_path will need updating, whereas the default deadfire root_path is app/assetss/stylesheets.

# config/initializers/assets.rb
Deadfire.configuration.root_path = Rails.root.join("app/assets").to_s

Deadfire.configuration.preprocess - configure exactly which files you want to pre-process, which caches all the utility classes declared so they are available using @apply in your stylesheets.

# config/initializers/assets.rb
Deadfire.configuration.preprocess("builds/tailwind.css")

To preprocess a file for a specific path like admin e.g. /admin/users, use the path keyword;

Deadfire.configuration.preprocess("builds/tailwind.css", path: "admin")

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

To run the tests, run bin/test.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hahmed/deadfire. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Deadfire project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.