grunt-at-imports
A grunt task to create one file with import statements from a collection of stylesheet files.
This is an adaption of the already existing npm plugin grunt-less-imports
which only supports .less
files.
LessCSS
@import (once) "filename"; // <-- these. in one file.
SASS/SCSS
@import "filename"; // <-- these. in one file.
Javascript
import "filename"; // <-- these. in one file.
Why use this? To get useful error messages from the parser, that tell you in what file the error was encountered! The parser uses import statements to aggregate files and will tell you about parsing errors in those files. But maintaining these statements by hand is a pain. In order to automatically aggregate all the style files in a project, a method of first concatenating the files before parsing is widely used. This works but you loose the valuable information about where to fix your mistakes.
So, automate import creation with this plugin and use the resulting file as the source for the parser.
By default any .css source files are inlined in the output before the import statements for the less files start.
Getting Started
This plugin requires Grunt ^0.4.5
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-at-imports --save-dev
--save-dev
adds the plugin to your devDependencies.
Once the plugin has been installed, load it in your Gruntfile.js
like so:
grunt.loadNpmTasks('grunt-at-imports');
The "at_imports" task
Overview
In your project's Gruntfile, add a section named at_imports
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
at_imports: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
}
}
})
Options
-
options.inlineCSS
{Boolean} true
By default any
.css
source files are inlined in the output before the@import
statements for the files start. The parser itself will generate CSS from@import
statements, but any.css
imports are left as is. If that's the behavior you want, setinlineCSS
to false. The imports will be created in order of the provided files. -
options.banner
{String} "// This file was generated by grunt-at-imports"
This option contains the banner that is added to the beginning of the generated output file.
-
options.import
{String|Function} "once"
Set Less import option keyword. Only applies if the output file extension is
.less
. String: Set the keyword for all@import
statements in the task target. Function: Dynamically set the@import
keyword with a callback. The path and extension of the current file are passed as arguments. The function must return a string.
Examples
Basic example with options
grunt.initConfig({
at_imports: {
options: {
inlineCSS: false, // default: true
import: 'reference' // default: once
},
src: [ 'styles/*.css', 'styles/*.less'],
dest: 'temp/imports.less'
}
})
More Examples
Using 'files' shorthand notation
In this example, a files
shorthand is used to specify input files and the output file instead of src
and dest
.
grunt.initConfig({
at_imports: {
options: {
},
files: {
'dist/imports.scss': ['styles/styles.css', 'styles/styles.scss']
}
}
})
Using multiple task targets
grunt.initConfig({
at_imports: {
options: { // general task options
inlineCSS: false
},
project: {
src: [ 'styles/*.css', 'styles/*.less'],
dest: 'dist/project.less'
},
vendor: {
options: { // target-specific options
import: 'reference'
},
src: [ 'styles/vendor/*.css', 'styles/vendor/*.less'],
dest: 'dist/vendor.less'
}
}
})
Example with a options.import callback
grunt.initConfig({
at_imports: {
options: {
import: function(filepath, extension) {
if (filepath === 'styles/helpers.less')
return 'reference';
else
return 'once';
}
},
src: [ 'styles/*.css', 'styles/*.scss'],
dest: 'temp/imports.scss'
}
})
Troubleshooting
Warning: Arguments to path.join must be strings
Most likely caused by a change in Node 0.10.0. Fixed in Grunt 0.4.1. Update grunt and grunt-cli.
Contributing
How to contribute to a project on Github
Release History
see CHANGELOG.md