Half the battle in web development when adopting a new tool into your workflow is getting the damn thing set up with your current workflow. I've spent far to much time doing the install/setup song and dance in my short career, so I decided I would spend the time for you since it is my song and I want you to dance. All the build examples use the Less flavor of ctr
not the JavaScript flavor. If you're interested in using the JavaScript flavor of ctr
head on over to the ctr-loader docs.
All the build examples are bare-bone setups intended to get you rockin' and rollin' as fast as possible or to act as a template to help you plug ctr
in your personal build tool. Having said that, the build examples are not configured for production, although, you could easily configure them for production purposes. In addition, each build example has a README in which I give a little description, list the commands, and list the tech it employs.
If you want to checkout the actual code for the Less plugin it's currently located in the ctr repository here.
Prerequisites
- Make sure you have yarn installed.
- Why
yarn
, and not whynpm
? There's a slew of reasons, but for me it's consistency. - Technically, if you want, you should be able to replace
npm
withyarn
and everything will work as expected
- Why
Install
yarn install
Install All Examples
yarn run install:all
Scripts
yarn run script:build
- Builds all the examples
yarn run script:clean
- Cleans out all the
/build
directories of examples yarn run script:clean-all
-> removes/build
and/node_modules
- Cleans out all the
yarn run script:update-check
- Checks for any
package.json
updates
- Checks for any
yarn run script:update
- Updates all
package.json
files
- Updates all
Test
yarn test
- Installs, builds, and tests all the examples
The configuration of ctr
for any build tool is dead simple as long as the build tool has a Less plugin, loader, or adapter given that ctr
is a Less plugin. The following process is universal among all build tools.
- Install and set up Less with the build tool.
- Brunch: less-brunch
- Grunt: grunt-contrib-less
- Gulp: gulp-less
- Webpack: less-loader
- Install
ctr
. require
ctr
, and use theless
property to get thectr
plugin Function for Less. If you want you can pass the resultingctr
plugin Function an option Object, although, I recommend you use the.ctrrc
.
const ctr = require('ctr').less;
// plugin ctr in the "plugin" location for buildtool
// ex. plugnis: [ctr()]
- Plug-in the
ctr
plugin Function. - Profit.
The main limitation for this plugin is the inability to use it with various Less logic Functions to a large extent. That is, you can't use custom Less mixins within ctr
instances and various types of complex loop logic, although, at the same time Less is not made for complex logic, and you can, and should, be performing said login in Javascript. Additionally, you can only use the declarative form of invocation, ie ctr('.test', { /*code*/ })
. Outside of these two limitations everything should work as expected (fingers crossed).
p.s. You should be able to use Less variables within ctr
instances.
The Less plugin offers both "Stylus" syntax and YAML syntax. However, I'm not sure how I feel about the YAML syntax and it was/is more or less of an experiment at this stage of the game. That's to say, if you want to use the YAML syntax you should probably ditch Less and migrate to a pure YAML based project.
Default Stylus Syntax
// Stylus Syntax (what you should use)
ctr('.test', {
font-size: 2em
hover-on: {
option: {
duration: 2s
}
color: blue
}
})
YAML Syntax
To use YAML syntax on the "fly" you can do so by declaring // SYNTAX_YAML
in your ctr
instance. Otherwise in the Less ctr
plugin Function pass an option Object with the value of syntaxStylus: flase
, although, in doing so you can only use YAML syntax and not Stylus syntax. Use at you're own risk.
// on the "fly"
ctr('.test', {
// SYNTAX_YAML
font-size: 2em
hover-on:
option:
duration: 2s
color: blue
})
It’s important that you understand how the ctr
Less plugin works so that you understand how to set up you’re @import
statements. In a nutshell, the ctr
plugin receives the Less file before Less has processed the file and it extracts, compiles, and replaces all ctr
related instances with their respected CSS output. What this means is, if you want to use ctr
specific variables or classes you must use an accumulator file. Or in other words, you cannot @import
Less files containing ctr
specific variables and then use those variables in the same file. Furthermore, this is what an “accumulator” file looks like:
// Base/global styles
@import 'base.less';
// Class styles to use in other Less files
@import 'classes/My-Kool-Class.less';
// You can now use the "My-Kool-Class" in both of the below Less files
@import 'components/money-maker.less';
@import 'components/open-source-your-shit.less';
BAD - WONT WORK
// File: open-source-your-shit.less
@import 'classes/My-Kool-Class.less';
// ctr instance
ctr('#but-really', {
size: 200px
color: red
// WILL NOT WORK!
extend: 'My-Kool-Class'
})
@import
Sync Options
To ensure your Less @import
statements are processed in the proper order I recommend you use the following options for Less.
{
// @important, needed to ensure proper variable and class import loading
syncImport: true,
async: false,
fileAsync: false
}
Best, te