https://github.com/rmosolgo/css_modules
Local CSS rules for sass, Rails views and JS
https://github.com/rmosolgo/css_modules
Last synced: 3 months ago
JSON representation
Local CSS rules for sass, Rails views and JS
- Host: GitHub
- URL: https://github.com/rmosolgo/css_modules
- Owner: rmosolgo
- License: mit
- Created: 2016-06-29T19:19:51.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2016-10-31T21:03:57.000Z (about 9 years ago)
- Last Synced: 2025-09-19T07:43:57.507Z (4 months ago)
- Language: Ruby
- Homepage:
- Size: 63.5 KB
- Stars: 22
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# CSSModules
[](https://travis-ci.org/rmosolgo/css_modules)
[](https://badge.fury.io/rb/css_modules)
An alternative to "magic string" classnames in Sass or SCSS.
Thanks to [Fatih Kadir Akın](https://twitter.com/fkadev) for his post, ["How I Implemented CSS Modules in Ruby on Rails, Easily"](https://medium.com/@fkadev/how-i-implemented-css-modules-to-ruby-on-rails-easily-abb324ce22d), which led the way on this idea!
## Usage
### Add modules to stylesheets
Your `.sass` or `.scss` stylesheets can define modules with `:module(module_name)`:
```scss
:module(events) {
.header {
font-style: bold;
}
.link:visited {
color: purple;
}
#footer {
font-size: 0.8em;
}
}
```
Sass requires an extra `\`:
```sass
\:module(events)
.header
font-style: bold
```
### Put modulized names into HTML
To access the contents of a module in a view, you must include the helpers in your controller:
```ruby
class EventsController < ApplicationController
helper CSSModules::ViewHelper
end
```
(To use the view helper _everywhere_, include it in `ApplicationController`.)
Then, in your view, you can access the module & its contents by name:
```erb
">
Events
<% css_module("events") do |events_module| %>
">
<%= link_to "Home", "/", class: events_module.selector("link") %>
© My company
<% end %>
```
#### Extra classes
You can also provide _multiple_, space-separated class names and/or extra class names to join without a module:
```ruby
# Apply "events" to "image-wrapper" and "image", then add "pull-left" without modification
css_module("events", "image-wrapper image", "pull-left")
#=> "events_123_image-wrapper events_123_image pull-left
```
#### Null module
If you pass `nil` as the module name, _no_ transformation is applied to the selectors.
```ruby
css_module(nil, "media-row")
# => "media-row"
css_module(nil) do |styles|
styles.selector("image image--main", "pull-left")
# => "image image--main pull-left"
end
```
### Use modulized names in JavaScript
In JavaScript, you can include a helper to access module styles:
```jsx
//= require css_module
// Module + identifier
var headerClass = CSSModule("events", "header")
$("." + headerClass).text() // => "Events"
// Or module helper function
var eventsModule = CSSModule("events")
function header() {
var headerClass = eventsModule("header")
return (
Events
)
}
```
#### Extra classes
You can also provide _multiple_, space-separated class names and/or extra class names to add without a module:
```js
// Apply "events" to "image-wrapper" and "image", then add "pull-left" without modification
CSSModule("events", "image-wrapper image", "pull-left")
// "events_123_image-wrapper events_123_image pull-left"
```
#### Null module
If you pass `null` as the module name, `CSSModule` will make _no_ transformation:
```js
CSSModule(null, "item")
// => "item"
var cssModule = CSSModule(null)
cssModule("item")
// => item
```
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'css_modules'
```
And then execute:
```bash
$ bundle
```
Or install it yourself as:
```bash
$ gem install css_modules
```
## Implementation notes
- The gem outputs shorter names when `Rails.env.production?`
- Module names are hashed in Ruby and JS, see `transform.rb` and `css_module.js` for the hash function
## TODO
- Dead code warning for Development env:
- Warn when not all styles are used?
- Sprockets require CSS to JS? `require_styles` ?
- Support plain `.css`
- Check for hash collisions in development
- Fix sprockets cache: a new version of this gem should expire an old cache
## License
[MIT](http://opensource.org/licenses/MIT).