gl

grunt-libsum

The best Grunt plugin ever.

Showing:

Popularity

Downloads/wk

1

Maintenance

No Maintenance Data Available

Package

Dependencies

0

License

Type Definitions

Tree-Shakeable

No?

Categories

Readme

doc /*github.com style (c) Vasily Polovnyov <vast@whiteants.net>*/ pre code { display: block; padding: 0.5em; color: #333; background: #f8f8ff } pre .comment, pre .template_comment, pre .diff .header, pre .javadoc { color: #998; font-style: italic } pre .keyword, pre .css .rule .keyword, pre .winutils, pre .javascript .title, pre .nginx .title, pre .subst, pre .request, pre .status { color: #333; font-weight: bold } pre .number, pre .hexcolor, pre .ruby .constant { color: #099; } pre .string, pre .tag .value, pre .phpdoc, pre .tex .formula { color: #d14 } pre .title, pre .id { color: #900; font-weight: bold } pre .javascript .title, pre .lisp .title, pre .clojure .title, pre .subst { font-weight: normal } pre .class .title, pre .haskell .type, pre .vhdl .literal, pre .tex .command { color: #458; font-weight: bold } pre .tag, pre .tag .title, pre .rules .property, pre .django .tag .keyword { color: #000080; font-weight: normal } pre .attribute, pre .variable, pre .lisp .body { color: #008080 } pre .regexp { color: #009926 } pre .class { color: #458; font-weight: bold } pre .symbol, pre .ruby .symbol .string, pre .lisp .keyword, pre .tex .special, pre .prompt { color: #990073 } pre .built_in, pre .lisp .title, pre .clojure .built_in { color: #0086b3 } pre .preprocessor, pre .pi, pre .doctype, pre .shebang, pre .cdata { color: #999; font-weight: bold } pre .deletion { background: #fdd } pre .addition { background: #dfd } pre .diff .change { background: #0086b3 } pre .chunk { color: #aaa }

grunt-libsum-plugin

The best libsum grunt plugin ever.

This plugin assumes you have a number of components in your project that you want to publish as a library and share with others. It will produce a categorized index that can then be used by some other tool (like 'libsum-browser') to browse or search the components available in the library.

The components may be of any type an may reside anywhere in the project source tree, and just have to meet following criteria:

  • every component should be self-contained in its own folder.
  • that folder must include a 'json' component descriptor

The 'component.json' component descriptor

Indexing the library is all about providing the information for each individual component in a component descriptor file, like this:

{
    "name": "component3",
    "description": "description for component 3",
    "version": "0.0.1",
    "section": "layout",
    "type": "style",
    "uses": ["bootstrap"],
    "depends": [component2]
}

Note that the exact information you give for every component is user-definable. You may define any tags you like, and decide which ones should be mandatory. The example above shows the tags as currently expected by the 'libsum-browser' tool, which assumes that each component

  • belongs to a given "section",
  • is of some "type",
  • may "depend" on other components in the same library
  • and may "use" third party dependencies.

Note also that you can name the component descriptor however you like, 'component.json' is just a sensible default. It doesn't even have to be the same for each component, you can specify any other naming strategy while configuring the grunt task.

Getting Started

This plugin requires GruntJS ~0.4.1

First install the grunt-libsum plugin. The --save-dev option tells npm to save this as a developement dependency in your package.json.

npm install grunt-libsum --save-dev

Once the plugin has been installed, enabled it in your gruntfile with:

grunt.loadNpmTasks('grunt-libsum');

The "libsum" task

Overview

In your project's gruntfile configuration object, add a section named libsum, like so:

grunt.initConfig({
        ...
        libsum : {
            components : {
                options : {
                    libraryName : 'testLibrary',
                    libraryVersion : '1.0.0',
                    libraryBaseUrl : __dirname,
                    requiredTags : [ 'name', 'section', 'type', 'description', 'version', 'depends' ],
                },
                files : {
                    'tmp/libindex.json' : [ 'src/**/component.json' ],
                },
            }
        },
        ...
})

This example task wil produce the file 'tmp/libindex.json', which will contain a catalog of all components having a 'component.json' file in the 'src' or any subfolder. Every component will be required to define the tags 'name', 'section', 'type', 'description', 'version' and 'depends'. The library will be named 'testLibrary', version is '1.0.0'. Finally, the base url will be the same as the project root.

libsum is a multi-task, a somewhat unfortunate GruntJS term meaning you may define different tasks/configurations in the same gruntfile. You normally will have just one and might invoke the task shown above as

grunt libsum:components

or just:

grunt libsum

But you might aswell need to have different libraries in the same project, or separate packages of the same library, something like this:

grunt.initConfig({
        libsum : {
            core_components : {
                ...
            },
            optional_extension_a : {
                ...
            },
            optional_extension_b : {
                ...
            },
        },
})

In any case, each task configuration will scan the specified source folders for component descriptors, will validate that each of them includes all mandatory tags and that there are no name collisions, and will combine them in a single JSON file.

Configuration options

These are the available configuration options for every libsum task:

options.libraryName

Just gives the library a name. Nice to have!

options.libraryVersion

The published version of the library.

options.libraryBaseUrl

The base URL from where assests for the library can be retrieved. The relative location for each component is assumed by the plugin to be the same as it's location in the source tree.

options.requiredTags

A list of tags every component must define. The plugin will throw an error if any of these is missing while building the index (you may of course use '--force')

files

The files section specifies what goes where, e.g.:

  • the name and location for the output file for the library index,
  • any number of globbing patterns to look for component descriptors.

Release History

(Nothing yet)

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial